django-ckeditor-5 0.2.20

Example of using a widget in a form:

from django import forms

from django_ckeditor_5.widgets import CKEditor5Widget
from .models import Comment


class CommentForm(forms.ModelForm):
      """Form for comments to the article."""

      def __init__(self, *args, **kwargs):
          super().__init__(*args, **kwargs)
          self.fields["text"].required = False

      class Meta:
          model = Comment
          fields = ("author", "text")
          widgets = {
              "text": CKEditor5Widget(
                  attrs={"class": "django_ckeditor_5"}, config_name="comment"
              )
          }

Example of using a widget in a template:

{% extends 'base.html' %}
{% block header %}
    {{ form.media }} # Required for styling/js to make ckeditor5 work
{% endblock %}
{% block content %}
    <form method="POST">
        {% csrf_token %}
        {{ form.as_p }}
        <input type="submit" value="Submit article">
    </form>
{% endblock %}

Custom storage example:

import os
from urllib.parse import urljoin

from django.conf import settings
from django.core.files.storage import FileSystemStorage


class CustomStorage(FileSystemStorage):
    """Custom storage for django_ckeditor_5 images."""

    location = os.path.join(settings.MEDIA_ROOT, "django_ckeditor_5")
    base_url = urljoin(settings.MEDIA_URL, "django_ckeditor_5/")

Changing the language:

You can change the language via the language key in the config

CKEDITOR_5_CONFIGS = {
  'default': {
      'toolbar': ['heading', '|', 'bold', 'italic', 'link',
                  'bulletedList', 'numberedList', 'blockQuote', 'imageUpload', ],
      'language': 'de',
  },
}

language can be either:

1. a string containing a single language

2. a list of languages

3. a dict {"ui": <a string (1) or a list of languages (2)>}

If you want the language to change with the user language in django you can add CKEDITOR_5_USER_LANGUAGE=True to your django settings. Additionally you will have to list all available languages in the ckeditor config as shown above.

Creating a CKEditor5 instance from javascript:

To create a ckeditor5 instance dynamically from javascript you can use the ClassicEditor class exposed through the window global variable.

const config = {};
window.ClassicEditor
   .create( document.querySelector( '#editor' ), config )
   .catch( error => {
       console.error( error );
   } );
}

Alternatively, you can create a form with the following structure:

<form method="POST">
    <div class="ck-editor-container">
        <textarea id="id_text" name="text" class="django_ckeditor_5" >
        </textarea>
        <div></div> <!-- this div or any empty element is required -->
        <span class="word-count" id="id_text_script-word-count"></span>
   </div>
   <input type="hidden" id="id_text_script-ck-editor-5-upload-url" data-upload-url="/ckeditor5/image_upload/" data-csrf_cookie_name="new_csrf_cookie_name">
   <span id="id_text_script-span"><script id="id_text_script" type="application/json">{your ckeditor config}</script></span>
</form>

The ckeditor will be automatically created once the form has been added to the DOM.

To access a ckeditor instance you can either get them through window.editors

const editor = windows.editors["<id of your field>"];

or by registering a callback

//register callback
window.ckeditorRegisterCallback("<id of your field>", function(editor) {
  // do something with editor
});
// unregister callback
window.ckeditorUnregisterCallback("<id of your field>");

Using JS callbacks in the config:

Some CKEditor 5 plugins (e.g. Mention) require JavaScript functions in the config. Since the config is passed as JSON, you can use the callback: prefix to reference a function defined on window.

In your settings.py:

CKEDITOR_5_CONFIGS = {
    'default': {
        'toolbar': ['heading', '|', 'bold', 'italic'],
        'mention': {
            'feeds': [{
                'marker': '@',
                'feed': 'callback:fetchMentions',
                'minimumCharacters': 1,
            }],
        },
    },
}

In your template (loaded before CKEditor):

<script>
    window.fetchMentions = function(queryText) {
        return fetch('/api/mentions/?q=' + queryText)
            .then(function(res) { return res.json(); });
    };
</script>

The JSON reviver detects any string value starting with callback: and replaces it with the corresponding window function. If the function is not found, the original string value is kept as-is.

Allow file uploading as link:

By default only images can be uploaded and embedded in the content. To allow uploading and embedding files as downloadable links you can add the following to your config:

CKEDITOR_5_ALLOW_ALL_FILE_TYPES = True
CKEDITOR_5_UPLOAD_FILE_TYPES = ['jpeg', 'pdf', 'png'] # optional
CKEDITOR_5_CONFIGS = {
  'default': {
      'toolbar': ['heading', '|', 'bold', 'italic', 'link',
                  'bulletedList', 'numberedList', 'blockQuote', 'imageUpload', 'fileUpload' ], # include fileUpload here
      'language': 'de',
  },

Warning: Uploaded files are not validated and users could upload malicious content (e.g. a pdf which actually is an executable). Furthermore allowing file uploads disables any validation for the image upload as the backend can’t distinguish between image and file upload. Exposing the file upload to all/untrusted users poses a risk!

Automatic image cleanup:

When an object with a CKEditor5Field is updated or deleted, images that are no longer referenced in the content can be automatically removed from storage. This requires an extra SELECT query on every update to compare old and new image references.

This feature is disabled by default. To enable it, add the following to your settings.py:

CKEDITOR_5_IMAGE_CLEANUP = True

Restrict upload file size:

You can restrict the maximum size for uploaded images and files by adding

CKEDITOR_5_MAX_FILE_SIZE = 5 # Max size in MB

to your config. Default is 0 (allow any file size).

Installing from GitHub:

cd your_root_project
git clone https://github.com/hvlads/django-ckeditor-5.git
cd django-ckeditor-5
yarn install
yarn run prod
cd your_root_project
python manage.py collectstatic

Example Sharing content styles between front-end and back-end:

To apply ckeditor5 styling outside of the editor, download content.styles.css from the official ckeditor5 docs and include it as a styleshet within your HTML template. You will need to add the ck-content class to the container of your content for the styles to be applied. https://ckeditor.com/docs/ckeditor5/latest/installation/advanced/content-styles.html#sharing-content-styles-between-frontend-and-backend

<link rel="stylesheet" href="path/to/assets/content-styles.css" type="text/css">
...
<div class="ck-content">
<p>ckeditor content</p>
</div>