12. Customize CSS classes and inline styles

Plugins shipped with djangocms-cascade offer a basic set of CSS classes as declared by the chosen CSS framework. These offered classes normally do not fulfill the requirements for real world sites. This is specially true, if you extend your site with one of the many available Bootstrap themes.

While djangocms-cascade is easily expendable, it would be overkill to re-implement the available plugins, just to add an extra field for a customized CSS class or an extra inline style. For that purpose, one can add a set of potential CSS classes and potential CSS inline styles for Cascade plugins, enabled for this feature. Moreover, this feature can be adopted individually on a per-site base.

12.1. Configure a Cascade plugins to accept extra fields

It is possible to configure each plugin to accept an additional ID tag, one ore more CSS classes or some inline styles. By default the plugins: BootstrapButtonPlugin, BootstrapRowPlugin, BootstrapJumbotronPlugin and the SimpleWrapperPlugin are eligible for accepting extra styles. Additionally, by default the user can override the margins of the HeadingPlugin and the HorizontalRulePlugin.

To override these defaults, first assure that 'cmsplugin_cascade.extra_fields' is part of your INSTALLED_APPS. Then add a dictionary of Cascade plugins, which shall be extendible to the project’s settings.py, for instance:

CMSPLUGIN_CASCADE = {
    ...
    'plugins_with_extra_fields': {
        'BootstrapButtonPlugin': PluginExtraFieldsConfig(),
        'BootstrapRowPlugin': PluginExtraFieldsConfig(),
        'BootstrapJumbotronPlugin': PluginExtraFieldsConfig(inline_styles={
            'extra_fields:Paddings': ['padding-top', 'padding-bottom'],
            'extra_units:Paddings': 'px,em'}),
        'SimpleWrapperPlugin': PluginExtraFieldsConfig(),
        'HeadingPlugin': PluginExtraFieldsConfig(inline_styles={
            'extra_fields:Paddings': ['margin-top', 'margin-right', 'margin-bottom', 'margin-left'],
            'extra_units:Paddings': 'px,em'}, allow_override=False),
        'HorizontalRulePlugin': PluginExtraFieldsConfig(inline_styles={
            'extra_fields:Paddings': ['margin-top', 'margin-bottom'],
            'extra_units:Paddings': 'px,em'}, allow_override=False),
    },
    ...
}

Here the class PluginExtraFieldsConfig is used to fine-tune which extra fields can be set while editing the plugin. Assigning that class without arguments to a plugin, allows us to specify the extra fields using the Django administration backend at:

Home › django CMS Cascade › Custom CSS classes and styles

Here the site administrator can specify for each concrete plugin, which extra CSS classes, ID tags and extra inline styles shall be used.

If we use PluginExtraFieldsConfig(allow_override=False), then the site administrator can not override the configuration using the backend. Then every extra field must be specified by the configuration directive:

12.2. Enable extra fields through the administration backend

To enable this feature, in the administration backend navigate to

Home › django CMS Cascade › Custom CSS classes and styles and click onto the button named Add Custom CSS classes styles.

From the field named “Plugin Name”, select one of the available plugins, for example Bootstrap Simple Wrapper. Then, from the field named “Site”, select the site where those extra styles shall be applied.

customize-styles

12.2.1. Allow ID

With “Allow id tag” enabled, an extra field will appear on the named plugin editor. There a user can add any arbitrary name which will be rendered as id="any_name" for the corresponding plugin instance.

Allowing ID’s is specially useful for the Heading Plugin, so the Links can point directly to that ID (bookmark linking).

12.2.2. CSS classes

In the field named “CSS class names”, the administrator may specify arbitrary CSS classes separated by commas. One of these CSS classes then can be added to the corresponding Cascade plugin. If more than one CSS class shall be addable concurrently, activate the checkbox named “Allow multiple”.

12.2.3. CSS inline styles

The administrator may activate all kinds of CSS inline styles by clicking on the named checkbox. For settings describing distances, additionally specify the allowed units to be used.

If a user opens the corresponding plugin inside the Structure View, he will see an extra select field to choose the CSS class and some input fields to enter say, extra margins, heights or whatever has been activated.

12.2.3.1. Use it rarely, use it wise

Adding too many styling fields to a plugin can mess up any web project. Therefore be advised to use this feature rarely and wise. If many people have write access to plugins, set extra permissions on this table, in order to not mess things up. For instance, it rarely makes sense to activate min-width, width and max-width.

12.3. Dynamically add styles to the Text-Editor

In Cascade it is also possible to dynamically add styles to the CKTextEditor. Ensure that in your settings.py the following is active:

Then in the Django-Admin, by adding entries in Start › django CMS Cascade › Text Editor Configs it is possible to use these special styles inside the text editor.