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.
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
can be 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 we can not override the
configuration using the administration backend, but must specify all settings in it’s constructor:
-
class
cmsplugin_cascade.extra_fields.config.
PluginExtraFieldsConfig
(allow_id_tag=False, css_classes=None, inline_styles=None, allow_override=True)¶ Each Cascade Plugin can be configured to accept extra fields, such as an ID tag, one or more CSS classes or inlines styles. It is possible to configure these fields globally using an instance of this class, or to configure them on a per site base using the appropriate admin’s backend interface at:
` *Start › django CMS Cascade › Custom CSS classes and styles › PluginExtraFields* `
:param allow_id_tag: IfTrue
, allows to set theid
attribute in HTML elements. :param css_classes: A dictionary containing:class_names
a comma separated string of allowed class names.multiple
a Boolean indicating if more multiple classes are allowed concurrently. :param inline_styles: A dictionary containing: :param allow_override: IfTrue
, allows to override this configuration using the admin’s backend interface.
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 current site.
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.
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.
Now, 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
.