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_PLUGIN_DEFAULTS¶

Default: {}

A dictionary of plugin model class names to default configuration values. These defaults are applied when a new plugin instance is created (e.g. when a plugin auto-creates child plugins). They override the form field defaults but can still be changed by editors in the plugin form.

The keys of the inner dictionary correspond to the form field names (which map to keys in the plugin’s config JSON field). The values use the same format as the form field’s compressed value.

Example: to give all Container plugins a default vertical padding of 5 and all Column plugins a default horizontal padding of 3:

DJANGOCMS_FRONTEND_PLUGIN_DEFAULTS = {
    "GridContainer": {
        "padding_y": "py-5",
    },
    "GridColumn": {
        "padding_x": "px-3",
    },
}

Plugin model class names correspond to the proxy model names defined in djangocms_frontend.contrib.*.models (e.g. GridContainer, GridRow, GridColumn, Card, CardLayout, Alert, etc.).

Note

Plugin models can also declare a default_config class attribute (a dictionary with the same format) to provide code-level defaults. The priority order is: form field initials (lowest) < model default_config < DJANGOCMS_FRONTEND_PLUGIN_DEFAULTS (highest).

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.

settings.DJANGOCMS_FRONTEND_SHOW_ADVANCED_SETTINGS¶

Default: True

Controls whether the “Advanced settings” tab is available in plugin edit forms. Advanced settings allow editors to set custom HTML attributes (such as id, class, data-*, style) and change the HTML tag type of a plugin.

Set to False to hide the tab and suppress all user-configured advanced settings at render time:

The “Advanced settings” fieldset is removed from plugin admin forms.
Custom HTML attributes stored in the plugin’s attributes config are ignored during rendering.
User-specified CSS classes (set through the attributes field) are not applied. Programmatically added classes (e.g. from spacing, responsive, or background mixins) continue to work.
The tag_type is reset to the default (div) at render time, regardless of the value stored in the database.

Note

Disabling this setting does not remove existing advanced settings from the database. To clean up previously stored values use the clear_advanced_settings management command.

Example:

DJANGOCMS_FRONTEND_SHOW_ADVANCED_SETTINGS = False