djangocms-text 0.9.3

Rich text editor selection

To select a rich text editor, add the editor’s package to your INSTALLED_APPS and add the setting TEXT_EDITOR to point to the editor’s RTEConfig path.

Example:

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

TEXT_EDITOR = "djangocms_text.contrib.text_ckeditor4.ckeditor4"

Rich text editor global configuration

The TEXT_EDITOR setting points to a RTEConfig object. You can create your custom RTEConfig instance. The following attributes are available:

• name (str): The name of the RTE configuration.

• config (str): The configuration string.

• js (Iterable[str]): An iterable of JavaScript files to include.

• css (dict): A dictionary of CSS files to include.

• admin_css (Iterable[str]): An iterable of CSS files for the admin interface only.

• inline_editing (bool): Whether to enable inline editing.

• child_plugin_support (bool): Whether to support child plugins.

• configuration (dict): Additional configuration options for the RTE.

• additional_context (dict): Additional context to pass to global editor configuration.

The default configuration is:

DEFAULT_EDITOR = RTEConfig(
    name="tiptap",
    config="TIPTAP",
    js=("djangocms_text/bundles/bundle.tiptap.min.js",),
    css={"all": ("djangocms_text/css/bundle.tiptap.min.css",)},
    admin_css=("djangocms_text/css/tiptap.admin.css",),
    inline_editing=True,
    child_plugin_support=True,
    configuration={},  # Default configuration (see below)
)

You can use the admin_css attribute to include CSS files that you need to be loaded into the dialog window, e.g., to declare custom colors or other styles.

Adding configuration to rich text editor frontend

Configuration to the rich text editor frontend can be passed by adding entries to the configuration property of the RTEConfig. The contents depends on the rich text editor frontend (TipTap, CKEditor 4, etc.).

The preferred method to add configuration to rich text editor frontend. Some configuration can be done using the TEXT_EDITOR_SETTINGS which is a dictionary that corresponds to the configuration property of the RTEConfig. For backwards compatibility with djangocms-text-ckeditor, CKEDITOR_SETTINGS is also passed on the the rich text editor frontend (even if it is not CKEditor 4).

Here is an example for Tiptap which represents the default configuration:

# TipTap configuration
DEFAULT_EDITOR.configuration = {
    "inlineStyles": [  # Styles menu, by default contains some rarer styles
            { name: 'Small', element: 'small' },
            { name: 'Kbd', element: 'kbd' },
            { name: 'Var', element: 'var' },
            { name: 'Samp', element: 'samp' },
        ],
    "blockStyles": [],
    # Block styles menu, e.g., for paragraphs, etc.; empty by default
    # Example entry: [{"name": "Lead", "element": "div", "attributes": {"class": "lead"}},]
    "textColors": {  # Colors offered for the text color menu - the keys are CSS classes
            'text-primary': {name: "Primary"},
            'text-secondary': {name: "Secondary"},
            'text-success': {name: "Success"},
            'text-danger': {name: "Danger"},
            'text-warning': {name: "Warning"},
            'text-info': {name: "Info"},
            'text-light': {name: "Light"},
            'text-dark': {name: "Dark"},
            'text-body': {name: "Body"},
            'text-muted': {name: "Muted"},
        },
    "tableClasses": "table",  # Classes added to new(!) tables
}

Here’s an example to configure the classes which should be added to new tables:

# Option 1:
# Modify the default editor configuration and point the ``TEXT_EDITOR`` setting to it
from djangocms_text.editors import DEFAULT_EDITOR

DEFAULT_EDITOR.configuration["tableClasses"] = "table ui"

# Option 2:
# Modify the default editor configurartion to offer choices to the editor
from djangocms_text.editors import DEFAULT_EDITOR

DEFAULT_EDITOR.configuration["tableClasses"] = [
    ["table", _("Default")],
    ["table table-striped", _("Striped")],
]

# Option 3:
# Both of the above can be replaced adding TEXT_EDITOR_SETTINGS to your settings.py
TEXT_EDITOR_SETTINGS = {
    "tableClasses": "table ui",
}

Inline editing feature

Inline editing allows editors to directly click on a text plugin and change the contents in django CMS’ edit mode. The CKEditor appears directly around the text field and can be used normally. Changes are saved as soon as the text field leaves focus.

Inline editing requires to encapsulate the HTML text in a <div> in edit mode. This might cause some side effects with a site’s CSS, e.g. direct child rules.

Inline editing is active by default. To deactivate inline editing add the following line in your project’s settings.py:

TEXT_INLINE_EDITING = False

With inline editing active, a toggle button to the toolbar to allow to switch inline editing on and off for the current session.

When inline editing is active the editor will save the plugin’s content each time it loses focus. If only text has changed the user can immediately continue to edit. If a text-enabled plugin was changed, added, or removed he page will refresh to update the page tree and get the correctly rendered version of the changed plugin.

Text-enabled plugins

djangocms-text supports text-enabled plugins, not all rich text editor frontends will, however.

If you have created a plugin that you want to use within Text plugins you can make them appear in the dropdown by making them text_enabled. This means that you assign the property text_enabled of a plugin to True, the default value is False. Here is a very simple implementation:

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

When the plugin is picked up, it will be available in the CMS Plugins dropdown (puzzle icon), which you can find in the editor. This makes it very easy for users to insert special content in a user-friendly Text block, which they are familiar with.

The plugin will even be previewed in the text editor. Pro-tip: make sure your plugin provides its own icon_alt method. That way, if you have many text_enabled-plugins, it can display a hint about it. For example, if you created a plugin which displays prices of configurable product, it can display a tooltip with the name of that product.

For more information about extending the CMS with plugins, read django-cms doc on how to do this.

Text-enabled plugins can have their own icons with djangocms-text. If the plugin class has a text_icon property, it should contain a SVG source code of an icon. The icon will be displayed in the CMS plugin pulldown menu, or in the toolbar.

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>'

You can also configure text-enabled plugins to be directly accessible from the rich text editor toolbar by adding the plugin’s name to the toolbar configuration, e.g. "LinkPlugin".

Default content in Placeholder

You can use TextPlugin in “default_plugins” (see docs about the CMS_PLACEHOLDER_CONF setting). TextPlugin requires just one value: body where you write your default HTML content. If you want to add some “default children” to your automagically added plugin (i.e. a LinkPlugin), you have to put children references in the body. References are "%(_tag_child_<order>)s" with the inserted order of children. For example:

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'
                        },
                    },
                ]
            },
        ]
    }
}

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:

$ nvm use
$ npm install
$ npx webpack