djangocms-text 0.3.0

Features

• Swappable Rich Text Editors: Choose and switch between different rich text editors as per project requirements.

• Customization and Extensions: Easily add new or customized versions of your favorite rich text editors.

• Enhanced Data Storage: Store content in either HTML or JSON format, offering versatility for different use cases.

• djangocms-text-ckeditor Compatibility: Initial version includes a port of the CKEditor 4 interface and child plugin functionality. This editor is compatible with the djangocms-text-ckeditor plugin, and can be used as a drop-in replacement.

Installation

Install djangocms-text using pip: pip install djangocms-text.

Build latest development branch using git:

git clone git@github.com:fsbraun/djangocms-text.git
cd djangocms-text
nvm use
npm install
npx webpack --mode development

You then can install the cloned repo using pip install -e /path/to/the/repo/djangocms-text.

Finally, add djangocms_text to your INSTALLED_APPS in your Django project settings:

INSTALLED_APPS = [..., "djangocms_text", ...]

Add an editor frontend to your installed apps (if different from the default TipTap frontend), and set the editor you want to use:

INSTALLED_APPS = [..., "djangocms_text.contrib.text_ckeditor5", ...]
DJANGOCMS_TEXT_EDITOR = "djangocms_text.contrib.text_ckeditor5.ckeditor5"

Upgrading from djangocms-text-ckeditor

djangocms-text’s migrations automatically migrate existing text plugins from djangocms-text-ckeditor. All you have to do is:

• remove djangocms_text_ckeditor from INSTALLED_APPS

• add djangocms_text to INSTALLED_APPS (see above)

• run python -m manage migrate djangocms_text

When transitioning from CKEditor4 to Tiptap as the rich text editor in your project, consider the following points:

• Switching Editors: The biggest challenge will likely be adapting to the differences between CKEditor4 and the new default rich text editor Tiptap. Tiptap offers a more modern editing experience, but there are important distinctions in how content is handled.

• No HTML Source Code Editing: Tiptap does not support direct HTML source code editing. While this simplifies the editor for most users, it could be a drawback for those accustomed to manually editing HTML, such as advanced users or developers.

• Loss of Non-standard Formatting: Formatting created through CKEditor4 plugins or manually added HTML classes may not be preserved. Tiptap stores content in an abstract JSON format and regenerates the HTML upon editing, which can lead to a loss of non-standard formatting. However, this only happens if a field is edited after migration.

• Potential Workaround: If maintaining CKEditor4 functionality is essential, you could circumvent these issues by using the CKEditor4 backend provided with djangocms-text. This allows you to retain the familiar CKEditor4 behavior while benefiting from other updates.

Usage

After installation, djangocms-text can be used as your rich text editor in Django CMS. It can be used as a drop-in for djangocms-text-ckeditor. Detailed documentation on usage and customization will be provided.

Editors

djangocms-text supports multiple rich text editors, which can be swapped out as needed. The following editors are currently supported:

• TipTap: A modern rich text editor with a modular architecture, TipTap is currently in development and is the default editor. TipTap does not allow the user to edit HTML directly, which means that some formating options are lost when switching from CKEditor 4 to TipTap.

• CKEditor 4: The initial version of djangocms-text includes a port of the CKEditor 4 interface and child plugin functionality. This editor is compatible with the djangocms-text-ckeditor plugin, and can be used as a drop-in replacement. It supports inline editing and text-enabled plugins.

• CKEditor 5: The current version of CKEditor might be supported in a future release of djangocms-text or as a separate package. Its current implementation does not support text-enabled plugins or dynamic attributes.

Contributing

Contributions to djangocms-text are welcome! Please read our contributing guidelines to get started.

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details. The CKEditor 5 interface is licensed under the GPL-2.0 License.

Configuration

INSTALLED_APPS = [
    ...,
    "djangocms_text.contrib.text_ckeditor4",
    ...
]

DJANGOCMS_TEXT_EDITOR = "djangocms_text.contrib.text_ckeditor5.ckeditor4"

TEXT_INLINE_EDITING = True

class MyTextPlugin(TextPlugin):
    name = "My text plugin"
    model = MyTextModel
    text_enabled = True

class MyTextPlugin(TextPlugin):
    name = "My text plugin"
    model = MyTextModel
    text_enabled = True
    text_icon = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8zm-1-13h2v6h-2zm0 8h2v2h-2z"/></svg>'

CMS_PLACEHOLDER_CONF = {
    'content': {
        'name' : _('Content'),
        'plugins': ['TextPlugin', 'LinkPlugin'],
        'default_plugins':[
            {
                'plugin_type':'TextPlugin',
                'values':{
                    'body':'<p>Great websites : %(_tag_child_1)s and %(_tag_child_2)s</p>'
                },
                'children':[
                    {
                        'plugin_type':'LinkPlugin',
                        'values':{
                            'name':'django',
                            'url':'https://www.djangoproject.com/'
                        },
                    },
                    {
                        'plugin_type':'LinkPlugin',
                        'values':{
                            'name':'django-cms',
                            'url':'https://www.django-cms.org'
                        },
                    },
                ]
            },
        ]
    }
}

Configurable sanitizer

djangocms-text uses nh3 to sanitize HTML to avoid security issues and to check for correct HTML code. Sanitisation may strip tags useful for some use cases such as iframe; you may customize the tags and attributes allowed by overriding the TEXT_ADDITIONAL_ATTRIBUTES setting:

TEXT_ADDITIONAL_ATTRIBUTES = {
    'iframe': {'scrolling', 'allowfullscreen', 'frameborder'},
}

Note that the TEXT_ADDITIONAL_ATTRIBUTES setting is a dictionary, where the keys are the tag names and the values are sets of attribute names.

If you have settings in the style of djangocms-text-ckeditor, which utilizes both TEXT_ADDITIONAL_TAGS and TEXT_ADDITIONAL_ATTRIBUTES, those will be translated for you automatically, but you will get a warning from the Django checks framework at server startup.

NOTE: Some frontend editors will pre-sanitize your text before passing it to the web server, rendering the above settings useless.

To completely disable the feature, set TEXT_HTML_SANITIZE = False.

pre-commit hooks

The repo uses pre-commit git hooks to run tools which ensure code quality.

To utilise this, run pip install pre-commit and then pre-commit install.

Building the JavaScript

djangocms-text distributes a javascript bundle required for the plugin to work, which contains frontend editors themselves and all the necessary plugins for functioning within CMS. To build the bundle you need to have to install dependencies with nvm use, npm install and then to run npx webpack.

Acknowledgments

• Special thanks to the Django CMS community and all contributors to the djangocms-text-ckeditor project.