Reference¶

Settings¶

Available settings will be revised. For now only the following can be changed:

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.

settings.DJANGOCMS_FRONTEND_GRID_SIZE¶: Defaults to 12.

settings.DJANGOCMS_FRONTEND_GRID_CONTAINERS¶

Default:

 (
    ('container', _('Container')),
    ('container-fluid', _('Fluid container')),
    ("container-sm", _("sx container")),
    ("container-md", _("md container")),
    ("container-lg", _("lg container")),
    ("container-xl", _("xl 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')),)

settings.DJANGOCMS_FRONTEND_TAB_TEMPLATES¶: Defaults to (('default', _('Default')),)

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')),
    ('custom', _('Custom')),
)

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.

TEXT_SAVE_IMAGE_FUNCTION¶: Requirement: TEXT_SAVE_IMAGE_FUNCTION = None

Warning

Please be aware that this package does not support djangocms-text-ckeditor’s Drag & Drop Images so be sure to set TEXT_SAVE_IMAGE_FUNCTION = None.

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 attriubte 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.

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.

Management commands¶

Management commands are run by typing ./manage.py command in the project directory.

migrate_frontend

Migrates plugins from other frontend packages to djangocms-frontend. Currently supports djangocms-bootstrap4 and djangocms_styled_link.

stale_frontend_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.

Running Tests¶

You can run tests by executing:

virtualenv env
source env/bin/activate
pip install -r tests/requirements.txt
python ./run_tests.py