Reference¶

Settings¶

djangocms-frontend can be configured by putting the appropriate settings in your project’s settings.py.

settings.CMS_COMPONENT_PLUGINS¶

Defaults to []

A list of dotted pathes to plugin classes that are supposed to also be components (see How to use frontend plugins as components in templates). Components are plugins to also be used in templates using the {% plugin %} template tag.

For performance reason, the plugin templates are compiled at startup.

To make djangocms-frontend plugins available as components, add the following line to your project’s settings:

CMS_COMPONENT_PLUGINS = [
    "djangocms_frontend.cms_plugins.CMSUIPlugin",  # All subclasses are added
    # add other plugins here if needed
]

settings.DJANGOCMS_FRONTEND_COMPONENT_FOLDER¶

Defaults to "cms_components"

The subfolder where the component templates are discovered. This is used by the template components to find the templates for the components.

The folder needs to be created in your app’s templates/<app_name>/ directory. If you want to use a different folder, set this to the folder name of your choice.

For example, if you want to use "my_components", add the following line to your project’s settings:

DJANGOCMS_FRONTEND_COMPONENT_FOLDER = "my_components"

This causes djangocms-frontend to search for templates on the following paths: templates/<app_name>/my_components/, where <app_name> is the name of any installed app.

settings.DJANGOCMS_FRONTEND_COMPONENT_FIELDS¶

Defaults to {}

A dictionary of installed Django apps and a list of Django form fields to be provided to template components’ context during their registration. The form fields can be used with the {% field %} template tag.

For example, to add a custom field to the context of all components, add the following line to your project’s settings:

DJANGOCMS_FRONTEND_COMPONENT_FIELDS = {
    "myapp": [
        "myapp.fields.MySuperFieldField",
        "myapp.fields.ChatBotField",
    ],
    # add other apps here if needed
}

These fields can be used in the template like this:

{% field "superField" MySuperFieldField required=True %}
{% field "chat_bot" ChatBotField required=False %}

Fields are only imported into the context if the app is installed in the project’s INSTALLED_APPS.

settings.DJANGOCMS_FRONTEND_TAG_CHOICES¶

Defaults to ['div', 'section', 'article', 'header', 'footer', 'aside'].

Lists the choices for the tag field of all djangocms-frontend plugins. div is the default tag.

These tags appear in Advanced Settings of some elements for editors to chose from.

settings.DJANGOCMS_FRONTEND_GRID_SIZE¶: Defaults to 12.

settings.DJANGOCMS_FRONTEND_GRID_CONTAINERS¶

Default:

(
    ("container", _("Container")),
    ("container-fluid", _("Fluid container")),
    ("container-full", _("Full container")),
)

settings.DJANGOCMS_FRONTEND_USE_ICONS¶

Defaults to True.

Decides if icons should be offered, e.g. in links.

settings.DJANGOCMS_FRONTEND_CAROUSEL_TEMPLATES¶

Defaults to (('default', _('Default')),)

If more than one option is given editors can select which template a carousel uses for rendering. Carousel expects the templates in a template folder under djangocms_frontend/bootstrap5/carousel/{{ name }}/. {{ name }} denotes the value of the template, i.e. default in the default example.

Carousel requires at least two files: carousel.html and slide.html.

settings.DJANGOCMS_FRONTEND_TAB_TEMPLATES¶

Defaults to (('default', _('Default')),)

If more than one option is given editors can select which template a tab element uses for rendering. Tabs expects the templates in a template folder under djangocms_frontend/bootstrap5/tabs/{{ name }}/. {{ name }} denotes the value of the template, i.e. default in the default example.

Tabs requires at least two files: tabs.html and item.html.

settings.DJANGOCMS_FRONTEND_LINK_TEMPLATES¶

Defaults to (('default', _('Default')),)

If more than one option is given editors can select which template a link or button element uses for rendering. Link expects the templates in a template folder under djangocms_frontend/bootstrap5/link/{{ name }}/. {{ name }} denotes the value of the template, i.e. default in the default example.

Link requires at least one file: link.html.

The default template adds rel="noopener noreferrer" to links with target="_blank", which is recommended for security and performance. If you do not want this behaviour, provide a custom template (e.g. via an additional entry in DJANGOCMS_FRONTEND_LINK_TEMPLATES and a corresponding link.html in your project) and omit or adjust the rel attribute there.

settings.DJANGOCMS_FRONTEND_JUMBOTRON_TEMPLATES¶

Defaults to (('default', _('Default')),)

Jumbotrons have been discontinued form Bootstrap 5 (and are not present in other frameworks either). The default template mimics the Bootstrap 4’s jumbotron.

If more than one option is given editors can select which template a jumbotron element uses for rendering. Jumbotron expects the template in a template folder under djangocms_frontend/bootstrap5/jumbotron/{{ name }}/. {{ name }} denotes the value of the template, i.e. default in the default example.

Link requires at least one file: jumbotron.html.

settings.DJANGOCMS_FRONTEND_SPACER_SIZES¶

Default:

 (
    ('0', '* 0'),
    ('1', '* .25'),
    ('2', '* .5'),
    ('3', '* 1'),
    ('4', '* 1.5'),
    ('5', '* 3'),
)

settings.DJANGOCMS_FRONTEND_CAROUSEL_ASPECT_RATIOS¶

Default: ((16, 9),)

Additional aspect ratios offered in the carousel component

settings.DJANGOCMS_FRONTEND_COLOR_STYLE_CHOICES¶

Default:

(
    ("primary", _("Primary")),
    ("secondary", _("Secondary")),
    ("success", _("Success")),
    ("danger", _("Danger")),
    ("warning", _("Warning")),
    ("info", _("Info")),
    ("light", _("Light")),
    ("dark", _("Dark")),
)

settings.DJANGOCMS_FRONTEND_ADMIN_CSS¶

Default: None

Adds css format files to the frontend editing forms of djangocms-frontend. The syntax is with a ModelForm’s css attribute of its Media class, e.g., DJANGOCMS_FRONTEND_ADMIN_CSS = {"all": ("css/admin.min.css",)}.

This css might be used to style have theme-specific colors available in the frontend editing forms. The included css file is custom made and should only contain color settings in the form of

.frontend-button-group .btn-primary {
    color: #123456;  // add !important here if using djangocms-admin-style
    background-color: #abcdef;
}

Note

Changing the color attribute might require a !important statement if you are using djangocms-admin-style.

settings.DJANGOCMS_FRONTEND_MINIMUM_INPUT_LENGTH¶: If unset or smaller than 1 the link plugin will render all link options into its form. If 1 or bigger the link form will wait for the user to type at least this many letters and search link targets matching this search string using an ajax request.

Note

The following settings of djangocms-picture are respected.

settings.DJANGOCMS_PICTURE_ALIGN¶

You can override alignment styles with DJANGOCMS_PICTURE_ALIGN, for example:

DJANGOCMS_PICTURE_ALIGN = [
    ('top', _('Top Aligned')),
]

This will generate a class prefixed with align-. The example above would produce a class="align-top". Adding a class key to the image attributes automatically merges the alignment with the attribute class.

settings.DJANGOCMS_PICTURE_RATIO¶

You can use DJANGOCMS_PICTURE_RATIO to set the width/height ratio of images if these values are not set explicitly on the image:

DJANGOCMS_PICTURE_RATIO = 1.618

We use the golden ratio, approximately 1.618, as a default value for this.

settings.DJANGOCMS_PICTURE_RESPONSIVE_IMAGES¶: You can enable responsive images technique by setting``DJANGOCMS_PICTURE_RESPONSIVE_IMAGES`` to True.

settings.DJANGOCMS_PICTURE_RESPONSIVE_IMAGES_VIEWPORT_BREAKPOINTS¶: If DJANGOCMS_PICTURE_RESPONSIVE_IMAGES is set to True,uploaded images will create thumbnails of different sizes according to DJANGOCMS_PICTURE_RESPONSIVE_IMAGES_VIEWPORT_BREAKPOINTS (which defaults to [576, 768, 992]) and browser will be responsible for choosing the best image to display (based upon the screen viewport).

settings.DJANGOCMS_PICTURE_TEMPLATES¶

This addon provides a default template for all instances. You can provide additional template choices by adding a DJANGOCMS_PICTURE_TEMPLATES setting:

DJANGOCMS_PICTURE_TEMPLATES = [
    ('background', _('Background image')),
]

You’ll need to create the background folder inside templates/djangocms_picture/ otherwise you will get a template does not exist error. You can do this by copying the default folder inside that directory and renaming it to background.

settings.TEXT_SAVE_IMAGE_FUNCTION¶

If you want to use djangocms-text-ckeditor’s Drag & Drop Images so be sure to set TEXT_SAVE_IMAGE_FUNCTION:

TEXT_SAVE_IMAGE_FUNCTION = 'djangocms_frontend.contrib.image.image_save.create_image_plugin'

Otherwise set TEXT_SAVE_IMAGE_FUNCTION = None

settings.DJANGOCMS_FRONTEND_ICON_LIBRARIES¶

Default:

DJANGOCMS_FRONTEND_ICON_LIBRARIES = {
    'font-awesome': (
        'font-awesome.min.json',
        'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css'
    ),
    'bootstrap-icons': (
        'bootstrap-icons.min.json',
        'https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.3/font/bootstrap-icons.css'
     ),
    'material-icons-filled': (
        'material-icons-filled.min.json',
        'https://fonts.googleapis.com/css2?family=Material+Icons'
    ),
    ...

For each available icon set there is an entry in this dictionary. The key is the basis for the displayed name. The value is a 2-tuple:

The name of the config file which is a static file with the path djangocms_frontend/icon/vendor/assets/icon-libraries/.
The name of the css file defining the icons. It is either a path or a file name. If it is a file name the css file is fetched from djangocms_frontend/icon/vendor/assets/stylesheets/.

settings.DJANGOCMS_FRONTEND_ICON_LIBRARIES_SHOWN¶

Default:

DJANGOCMS_FRONTEND_ICON_LIBRARIES_SHOWN = (
    "font-awesome",
    "bootstrap-icons",
    "material-icons-filled",
    "material-icons-outlined",
    "material-icons-round",
    "material-icons-sharp",
    "material-icons-two-tone",
    "fomantic-ui",
    "foundation-icons",
    "elegant-icons",
    "feather-icons",
    "open-iconic",
    "tabler-icons",
    "weather-icons",
)

This settings allows to restrict the number of icon sets shown to the user. Typically one or two icon sets should be sufficient to keep a consistent icon expierence.

Warning

This setting only has an effecet if DJANGOCMS_FRONTEND_ICON_LIBRARIES is not explicitly set.

settings.DJANGOCMS_FRONTEND_ICON_SIZE_CHOICES¶

Default:

DJANGOCMS_FRONTEND_ICON_SIZE_CHOICES = (
    ("", _("Regular")),
    ("200%", _("x 2")),
    ("300%", _("x 3")),
    ("400%", _("x 4")),
    ("500%", _("x 5")),
    ("800%", _("x 8")),
    ("1200%", _("x 12")),
)

This lost of options define the icon size choices a user can select. The values (first tuple element) are css units for the font-size css property. Besides relative units (%) any css unit can be used, e.g. 112pt.

settings.DJANGOCMS_FRONTEND_SHOW_EMPTY_CHILDREN¶

Default: False

If set to True the frontend editing will show a message where children can be added to plugins to complete the design. This is supposed to make the editing experience more intuitive for editors.

Models¶

djangocms-frontend subclasses the CMSPlugin model.

class FrontendUIItem(CMSPlugin)¶

Import from djangocms_frontend.models.

All concrete models for UI items are proxy models of this class. This implies you can create, delete and update instances of the proxy models and all the data will be saved as if you were using this original (non-proxied) model.

This way all proxies can have different python methods as needed while still all using the single database table of FrontendUIItem.

FrontendUIItem.ui_item¶: This CharField contains the UI item’s type without the suffix “Plugin”, e.g. “Link” and not “LinkPlugin”. This is a convenience field. The plugin type is determined by CMSPlugin.plugin_type.

FrontendUIItem.tag_type¶: This is the tag type field determining what tag type the UI item should have. Tag types default to <div>.

FrontendUIItem.config¶: The field config is the JSON field that contains a dictionary with all specific information needed for the UI item. The entries of the dictionary can be directly read as attributes of the FrontendUIItem instance. For example, ui_item.context will give ui_item.config["context"].

Warning

Note that changes to the config must be written directly to the dictionary: ui_item.config["context"] = None.

FrontendUIItem.add_classes(self, *args)¶

This helper method allows a Plugin’s render method to add framework-specific html classes to be added when a model is rendered. Each positional argument can be a string for a class name or a list of strings to be added to the list of html classes.

These classes are not saved to the database. They merely a are stored to simplify the rendering process and are lost once a UI item has been rendered.

FrontendUIItem.get_attributes(self)¶: This method renders all attributes given in the optional attributes field (stored in .config). The class attribute reflects all additional classes that have been passed to the model instance by means of the .add_classes method.

FrontendUIItem.initialize_from_form(self, form)¶

Since the UIItem models do not have default values for the contents of their .config dictionary, a newly created instance of an UI item will not have config data set, not even required data.

This method initializes all fields in .config by setting the value to the respective initial property of the UI items admin form.

FrontendUIItem.get_short_description(self)¶: returns a plugin-specific short description shown in the structure mode of django CMS.

Form widgets¶

djangocms-frontend contains button group widgets which can be used as for forms.ChoiceField. They might turn out helpful when adding custom plugins.

class ButtonGroup(forms.RadioSelect)¶

Import from djangocms_frontend.fields

The button group widget displays a set of buttons for the user to chose. Usable for up to roughly five options.

class ColoredButtonGroup(ButtonGroup)¶

Import from djangocms_frontend.fields

Used to display the context color selection buttons.

class IconGroup(ButtonGroup)¶

Import from djangocms_frontend.fields.

This widget displays icons in stead of text for the options. Each icon is rendered by <span class="icon icon-{{value}}"></span>. Add css in the Media subclass to ensure that for each option’s value the span renders the appropriate icon.

class IconMultiselect(forms.CheckboxSelectMultiple)¶

Import from djangocms_frontend.fields.

Like IconGroup this widget displays a choice of icons. Since it inherits from CheckboxSelectMultiple the icons work like checkboxes and not radio buttons.

class OptionalDeviceChoiceField(forms.MultipleChoiceField)¶

Import from djangocms_frontend.fields.

This form field displays a choice of devices corresponding to breakpoints in the responsive grid. The user can select any combination of devices including none and all.

The result is a list of values of the selected choices or None for all devices selected.

class DeviceChoiceField(OptionalDeviceChoiceField)¶

Import from djangocms_frontend.fields.

This form field is identical to the OptionalDeviceChoiceField above, but requires the user to select at least one device.

Template filters¶

djangocms-frontend provides template filters that can be used in component templates. Load them with {% load frontend %}.

get_slot(instance, slot_name)¶

Import from djangocms_frontend.templatetags.frontend.

Get plugins for a specific slot directly from a component instance. This is useful for manually iterating over slot plugins in a component’s template instead of using the {% childplugins %} template tag.

Parameters:

instance – The component plugin instance
slot_name – The name of the slot to retrieve plugins from

Returns:

Generator yielding child plugin instances in the specified slot

Usage in templates:

{% load frontend %}

{% for plugin in instance|get_slot:"buttons" %}
    {# Manually render each plugin in the slot #}
    <div class="button-wrapper">
        {% render_plugin plugin %}
    </div>
{% endfor %}

This is useful when you need more control over how slot content is rendered, compared to the {% childplugins %} tag which handles rendering automatically.

get_attributes(attribute_field, *add_classes)¶

Simple tag that joins classes with an attributes field and returns all HTML attributes formatted for use in templates.

Parameters:

attribute_field – Dictionary of HTML attributes (e.g., {"class": "btn", "id": "my-id"})
add_classes – Additional CSS classes to merge with existing ones

Returns:

Safe HTML string of formatted attributes

Usage in templates:

{% load frontend %}

{# Basic usage with attributes field #}
<div {% get_attributes instance.attributes %}>

{# Add additional classes #}
<div {% get_attributes instance.attributes "extra-class" "another-class" %}>

{# Combine multiple class sources #}
<button {% get_attributes instance.attributes some_variable "static-class" %}>

Behavior:

Merges all provided classes into a single class attribute
Properly escapes attribute values for safety
Handles boolean attributes (renders just the attribute name if value is empty)
Returns a safe HTML string that can be used directly in templates

Template tags¶

djangocms-frontend provides template tags for rendering components and slots. Load them with {% load frontend %}.

childplugins()¶

Template tag for rendering child plugins of a component instance. This is the primary way to render slot content in component templates.

Basic usage:

{% load frontend %}

{# Render all child plugins #}
{% childplugins instance %}

{# Render plugins in a specific slot #}
{% childplugins instance "buttons" %}

With fallback content:

You can provide fallback content that displays when the slot is empty:

{% childplugins instance "buttons" or %}
    <button>Default Button</button>
{% endchildplugins %}

Declaring slots in component definitions:

When used with both slot name and verbose name in a component template during registration, it declares a new slot:

{% childplugins instance "buttons" "Action Buttons" %}
    <!-- Fallback content -->
{% endchildplugins %}

Parameters:

instance – The component plugin instance (optional, defaults to instance from context)
plugin_type – Slot name or plugin type to filter (optional)
verbose_name – Verbose name for slot declaration (optional, used during component registration)

Behavior:

If plugin_type is provided without “Plugin” suffix, it treats it as a slot name and automatically constructs the full plugin type name
Renders all matching child plugins using their respective templates
If a block with fallback content is provided (using or), it displays when no plugins match
During component registration, declaring slots with verbose names automatically adds them to the component’s slot configuration

See also Creating Components with Slots for detailed slot usage examples.

plugin()¶

Template tag for rendering a plugin instance without saving it to the database. This is useful for creating demo content, prototyping, or rendering plugins programmatically.

Basic usage:

{% load frontend %}

{# Render a plugin with default settings #}
{% plugin "GridContainer" %}

{# Render with custom parameters #}
{% plugin "GridRow" container_fluid=True %}

{# Store rendered output in a variable #}
{% plugin "Alert" alert_context="info" alert_dismissable=True as my_alert %}
{{ my_alert }}

With child content:

{% plugin "Card" card_alignment="left" %}
    <h3>Card Title</h3>
    <p>Card content goes here</p>
{% endplugin %}

Parameters:

name – The plugin name (must be registered in CMS_COMPONENT_PLUGINS setting)
kwargs – Keyword arguments matching the plugin’s form fields
varname (as) – Optional variable name to store the rendered output

Requirements:

The plugin must be listed in the CMS_COMPONENT_PLUGINS setting
Plugin templates are compiled at startup for performance
Child content can be provided between {% plugin %}...{% endplugin %} tags

Note

The {% plugin %} tag creates a temporary instance that is never saved to the database. This makes it ideal for testing and prototyping but should not be used for production content that needs to be editable by content editors.

slot()¶

Template tag used within {% plugin %}...{% endplugin %} blocks to define boundaries for different slots when testing multi-slot components.

Usage:

{% load frontend %}

{% plugin "Card" %}
    {% slot "header" %}
        <h3>Card Header</h3>
    {% endslot %}

    {% slot "body" %}
        <p>Card body content</p>
    {% endslot %}

    {% slot "footer" %}
        <small>Card footer</small>
    {% endslot %}
{% endplugin %}

Parameters:

Parameters:: slot_name – The name of the slot (must match a slot defined in the component)

Behavior:

Creates dummy plugin instances for each slot
Content between {% slot %}...{% endslot %} is assigned to that slot
Only works within {% plugin %} blocks
The slot tag itself doesn’t render anything; child plugins are rendered by {% childplugins %}

This is primarily used for testing and demonstrating components with multiple slots.

inline_field()¶

Template tag that enables inline editing of plugin fields in django CMS edit mode. This allows editors to edit field values directly in the frontend without opening the plugin edit dialog.

Basic usage:

{% load frontend %}

{# Edit a specific field of the current instance #}
{% inline_field instance "title" %}

{# Shortcut: instance from context #}
{% inline_field "title" %}

{# With custom filters #}
{% inline_field instance "content" filters="safe|linebreaks" %}

Parameters:

instance – The plugin instance to edit (optional if instance is in context)
attribute – The field name to make editable
language – Language code for multilingual fields (optional)
filters – Template filters to apply to the field value (optional)
view_url – Custom URL for the edit view (optional)
view_method – Custom view method (optional)

Behavior:

In edit mode: Wraps the field in an editable interface with save/cancel buttons
In live mode: Simply displays the field value
During component registration: Automatically registers the field as editable
Only works with saved plugin instances (requires a primary key)

Example in a component template:

<div class="card">
    <h3>{% inline_field "title" %}</h3>
    <div>{% inline_field "content" filters="safe" %}</div>
</div>

Note

Inline editing only activates when the django CMS toolbar is in edit mode and the plugin has been saved to the database. It will not work with dummy plugins created via the {% plugin %} tag.

Management commands¶

Management commands are run by typing python -m manage frontend command in the project directory. command can be one of the following:

migrate

Migrates plugins from other frontend packages to djangocms-frontend. Currently supports djangocms_bootstrap4 and djangocms_styled_link. Other packages can be migrated adding custom migration modules to the DJANGOCMS_FRONTEND_ADDITIONAL_MIGRATIONS setting.

stale_references

If references in a UI item are moved or removed the UI items are designed to fall back gracefully and both not throw errors or be deleted themselves (by a db cascade).

The drawback is, that references might become stale. This command prints all stale references, their plugins and pages/placeholder they belong to.

sync_permissions

This command syncs permissions for users or groups. It is run with one of the following arguments:

users: Syncs permissions for all users.
groups: Syncs permissions for all groups.

Permissions are copied from the FrontendUIItem model to all installed plugins. This way you can set permissions for all plugins by setting them for FrontendUIItem and then syncing them.

Running Tests¶

You can run tests by executing:

python -m venv env
source env/bin/activate
pip install -r tests/requirements/base.txt
pytest