Reference#
Settings#
djangocms-frontend can be configured by putting the appropriate settings
in your project’s settings.py
.
- 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
andslide.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
anditem.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
.
- 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
’scss
attribute of itsMedia
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. If1
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 aclass="align-top"
. Adding aclass
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 settings.DJANGOCMS_PICTURE_RESPONSIVE_IMAGES`` is set to
True
,uploaded images will create thumbnails of different sizes according toDJANGOCMS_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 aDJANGOCMS_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 thedefault
folder inside that directory and renaming it tobackground
.
- settings.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 theFrontendUIItem
instance. For example,ui_item.context
will giveui_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
). Theclass
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 respectiveinitial
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 theMedia
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 fromCheckboxSelectMultiple
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.
Management commands#
Management commands are run by typing ./manage.py 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 users
orsync_permissions groups
Django allows to set permissions for each user and group on a per plugin level. This might become somewhat tedious which is why this command will sync permissions. For each user or group it will copy the permissions of
djangocms_frontend.models.FrontendUIItem
to all installed djangocms-frontend plugins. If you need to change permissions for all plugins this requires you only to change them forFrontendUIItem
and then syncing the new permission with these commands.
Running Tests#
You can run tests by executing:
virtualenv env
source env/bin/activate
pip install -r tests/requirements.txt
python ./run_tests.py