Create a Python Virtual Environment¶

To keep environments separate, first create a virtualenv.

#!/bin/sh
sudo pip install --upgrade virtualenv
virtualenv --distribute --no-site-packages myvirtualenv
source myvirtualenv/bin/activate
(myvirtualenv)$

Clone the latest stable releases¶

Create a temporary file, for instance named requirements.txt, containing these entries:

Django==1.8.8
Django-Select2==5.5.0
Pillow==2.9.0
Unidecode==0.4.18
django-classy-tags==0.6.2
django-cms==3.2.0
django-filer==1.1.1
django-treebeard==4.0
django-polymorphic==0.9.1
django-reversion==1.10.1
django-sass-processor==0.3.2
django-sekizai==0.9.0
djangocms-admin-style==0.2.8
-e git+https://github.com/jrief/djangocms-bootstrap3.git#egg=djangocms-bootstrap3
-e git+https://github.com/jrief/djangocms-cascade.git#egg=djangocms-cascade
djangocms-text-ckeditor==2.8.1
easy-thumbnails==2.3
html5lib==0.9999999
jsonfield==1.0.3
six==1.9.0

and install them into your environment:

pip install -r requirements.txt

this will take a few minutes. After the installation finished, change into the folder containing the demo application, install missing CSS and JavaScript files, initialize the database and create a superuser:

cd $VIRTUAL_ENV/src/djangocms-cascade
bower install --require
cd examples
./manage.py migrate --settings=bs3demo.settings
./manage.py createsuperuser --settings=bs3demo.settings
./manage.py runserver --settings=bs3demo.settings

Point a browser onto http://localhost:8000/ and log in as the super user. Here you should be able to add your first page. Do this by changing into into Structure mode on the top of the page. Now a heading named MAIN CONTENT CONTAINER appears. This heading symbolizes a djangoCMS Placeholder.

Locate the plus sign right to the heading and click on it. From its context menu select Container located in the section Bootstrap:

This brings you into the editor mode for a Bootstrap container. To this container you may add one or more Bootstrap Rows. Inside these rows you may organize the layout using some Bootstrap Columns.

Please proceed with the detailled explanation on how to use the Bootstrap’s grid system within djangocms-cascade.

Extensibility¶

This module requires one database table with one column to store all data in a JSON object. All DjangoCMS-Cascade plugins share this same model, therefore they can be easily extended, because new data structures are added to that JSON object without requiring a database migration.

Another three database tables are required for additional optional features.

Dependencies¶

• Django >=1.6
• DjangoCMS >=3.0.8

Create a database schema¶

if you use Django-1.7 or higher

./manage.py migrate cmsplugin_cascade

if you use Django-1.6

./manage.py syncdb --migrate

Install Bootstrap¶

Since the Bootstrap CSS and JavaScript files are part of their own repository, they are not shipped within this package. Furthermore, as they are not part of the PyPI network, they have to be installed through another package manager, namely bower.

cd djangocms-cascade
bower install --require

Alternatively copy the installed bower_components into a directory of your project or to any other meaningful location, but ensure that the directory bower_components can be found by your StaticFileFinder. In doubt, add that directory to your STATICFILES_DIRS:

STATICFILES_DIRS = (
    os.path.abspath(os.path.join(MY_PROJECT_DIR, 'bower_components')),
)

Configuration¶

Add 'cmsplugin_cascade' to the list of INSTALLED_APPS in the project’s settings.py file. Optionally add ‘cmsplugin_cascade.extra_fields’ and/or ‘cmsplugin_cascade.sharable’ to the list of INSTALLED_APPS. Make sure that these entries are located before the entry cms.

INSTALLED_APPS = (
    ...
    'cmsplugin_cascade',
    'cmsplugin_cascade.extra_fields',  # optional
    'cmsplugin_cascade.sharable',  # optional
    'cms',
    ...
)

CMSPLUGIN_CASCADE_PLUGINS = ('cmsplugin_cascade.bootstrap3',)

CMSPLUGIN_CASCADE_PLUGINS = ('cmsplugin_cascade.bootstrap3.container',)

CMSPLUGIN_CASCADE_PLUGINS += ('cmsplugin_cascade.link',)

CMS_PLACEHOLDER_CONF = {
    'Page Content': {
        'plugins': ['BootstrapContainerPlugin'],
    },
}

CMSPLUGIN_CASCADE = {
    ...
    'alien_plugins': ('TextPlugin', 'FilerImagePlugin', 'OtherLeafPlugin',),
    ...
}

Template Customization¶

Make sure that the style sheets are referenced correctly by the used templates. DjangoCMS requires Django-Sekizai to organize these includes, so a strong recommendation is to use that Django app.

The templates used for a DjangoCMS project shall include a header, footer and the menu bar, but should leave out an empty working area. When using HTML5, wrap this area into an <article> or <section> element. This placeholder shall be named using a meaningless identifier, for instance “Page Content” or similar:

<section>{% placeholder "Page Content" %}</section>

From now on, the page layout can be adopted inside this placeholder, without having to fiddle with template coding anymore.

Link Plugin with sharable fields¶

If your web-site contains many links pointing onto external URLs, you might want to refer to them by a symbolic name, rather than having to reenter the URL repeatedly. With djangocms-cascade this can be achieved easily by declaring some of the plugin’s fields as “sharable”.

Assure that INSTALLED_APPS contain 'cmsplugin_cascade.sharable', then redefine the TextLinkPlugin to have sharable fields in settings.py:

CMSPLUGIN_CASCADE = {
    ...
    'plugins_with_sharables':
        ...
        'TextLinkPlugin':  ('link',),  # and optionally other fields
        ...
    },
    ...
}

This will change the Link Plugin’s editor slightly. Note the extra field added to the bottom of the form.

Now the URL for this ink entity is stored in a central entity. This feature is useful, if for instance the URL of an external web page may change in the future. Then the administrator can change that link in the administration area once, rather than having to go through all the pages and check if that link was used.

To retain the Link settings, click onto the checkbox Remember these settings as: ... and give it a name of your choice. The next time your create a Shared Link element, you may select a previously named settings from the select field Shared Settings. Since these settings can be shared among other plugins, these input fields are disabled and can’t be changed anymore.

Extending the Link Plugin¶

While programming third party modules for Django, one might have to access a model instance through a URL and thus add the method get_absolute_url to that Django model. Since such a URL is neither a CMS page, nor a URL to an external web page, it would be convenient to access that model using a special Link type.

For example, this special Link plugin is used by djangoSHOP to allow direct linking from a CMS page to a shop’s product.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

# -*- coding: utf-8 -*-
from django.utils.translation import ugettext_lazy as _
from django.apps import apps
from django.core.exceptions import ObjectDoesNotExist
from django_select2.fields import AutoModelSelect2Field
from cms.plugin_pool import plugin_pool
from cmsplugin_cascade.link.forms import TextLinkForm
from cmsplugin_cascade.link.models import SimpleLinkElement
from cmsplugin_cascade.link.plugin_base import TextLinkPluginBase
from cmsplugin_cascade.utils import resolve_dependencies
from shop.models.product import Product


class ProductSearchField(AutoModelSelect2Field):
    empty_value = []
    search_fields = ['product_code__startswith', 'translations__name__startswith']
    queryset = Product.objects.all()

    def security_check(self, request, *args, **kwargs):
        user = request.user
        if user and not user.is_anonymous() and user.is_staff:
            return True
        return False

    def prepare_value(self, value):
        if not value:
            return None
        return super(ProductSearchField, self).prepare_value(value)


class LinkForm(TextLinkForm):
    LINK_TYPE_CHOICES = (('cmspage', _("CMS Page")), ('product', _("Product")), ('exturl', _("External URL")), ('email', _("Mail To")),)
    product = ProductSearchField(required=False, label='',
        help_text=_("An internal link onto a product from the shop"))

    def clean_product(self):
        if self.cleaned_data.get('link_type') == 'product':
            self.cleaned_data['link_data'] = {
                'type': 'product',
                'model': 'shop.Product',
                'pk': self.cleaned_data['product'] and self.cleaned_data['product'].pk or None,
            }

    def set_initial_product(self, initial):
        try:
            Model = apps.get_model(*initial['link']['model'].split('.'))
            initial['product'] = Model.objects.get(pk=initial['link']['pk'])
        except (KeyError, ObjectDoesNotExist):
            pass


class LinkPlugin(TextLinkPluginBase):
    model = SimpleLinkElement
    fields = ('link_content', ('link_type', 'cms_page', 'product', 'ext_url', 'mail_to'), 'glossary',)
    form = LinkForm

    class Media:
        js = resolve_dependencies('shop/js/admin/linkplugin.js')

plugin_pool.register_plugin(LinkPlugin)

When using this implementation, remember to change CMSPLUGIN_CASCADE_PLUGINS in your project’s settings.py to that alternative Link plugin.

Now the select box for Link type will offer one additional option: “Product”. When this is selected, the site administrator can choose between all of the shops products.

Bootstrap Container¶

A Container is the outermost component the Bootstrap framework knows of. Here the designer can specify the breakpoints of a web page. By default, Bootstrap offers 4 breakpoints: “large”, “medium”, “small” and “tiny”. These determine for which kind of screen widths, the grid system may switch the layout.

The editor window for a Container element offers the possibility to deactivate certain breakpoints. While this might make sense under certain conditions, it is safe to always keep all four breakpoints active, since this gives the designer of the web page the maximum flexibility.

@media(min-width: 1200px) {
  .container {
    max-width: 970px;
  }
}

@media(min-width: $screen-lg) {
  .container {
    max-width: $container-desktop;
  }
}

CMSPLUGIN_CASCADE = {
    ...
    'bootstrap3': {
        'fluid-lg-width': 2500,
    },
}

Bootstrap Row¶

Each Bootstrap Container may contain one or more Bootstrap Rows. A row does not accept any configuration setting. However, while editing, one can specify the number of columns. When adding or changing a row, then this number of columns are added if its value exceeds the current number of columns. Reducing the number of columns does not delete any of them; they must explicitly be chosen from the context menu in structure view.

Horizontal Rule¶

A horizontal rule is used to separate rows optically from each other.

Column¶

In the column editor, one can specify the width, the offset and the visibility of each column. These values can be set for each of the four breakpoints (tiny, small, medium and large), as specified by the Container plugin.

At the beginning this may feel rather complicate, but consider that Bootstrap 3 is mobile first, therefore all column settings, first are applied to the narrow breakpoints, which later can be overridden for larger breakpoints at a later stage. This is the reason why this editor starts with the column widths and column offsets for tiny rather than for large displays.

Complete DOM Structure¶

After having added a container with different rows and columns, you may add the leaf plugins. These hold the actual content, such as text and images.

By pressing the button Publish changes, the single blocks are regrouped and displayed using the Bootstrap’s grid system.

Adding Plugins into a hard coded grid¶

Sometimes the given Django template already defines a Bootstrap Container, or Row inside a Container element. Example:

<div class="container">
    {% placeholder "Row Content" %}
</div>

or

<div class="container">
    <div class="row">
        {% placeholder "Column Content" %}
    </div>
</div>

Here the Django templatetag {% placeholder "Row Content" %} requires a Row- rather than a Container-plugin; and the templatetag {% placeholder "Column Content" %} requires a Column-plugin. Hence we must tell djangocms-cascade which breakpoints shall be allowed and what the containers extensions shall be. This must be hard-coded inside your setting.py:

CMS_PLACEHOLDER_CONF = {
    # for a row-like placeholder configuration ...
    'Row Content': {
        'plugins': ['BootstrapRowPlugin'],
        'parent_classes': {'BootstrapRowPlugin': []},
        'require_parent': False,
        'glossary': {
            'breakpoints': ['xs', 'sm', 'md', 'lg'],
            'container_max_widths': {'xs': 750, 'sm': 750, 'md': 970, 'lg': 1170},
            'fluid': False,
            'media_queries': {
                'xs': ['(max-width: 768px)'],
                'sm': ['(min-width: 768px)', '(max-width: 992px)'],
                'md': ['(min-width: 992px)', '(max-width: 1200px)'],
                'lg': ['(min-width: 1200px)'],
            },
        }
    },
    # or, for a column-like placeholder configuration ...
    'Colummn Content': {
        'plugins': ['BootstrapColumnPlugin'],
        'parent_classes': {'BootstrapColumnPlugin': []},
        'require_parent': False,
        'glossary': {
            'breakpoints': ['xs', 'sm', 'md', 'lg'],
            'container_max_widths': {'xs': 750, 'sm': 750, 'md': 970, 'lg': 1170},
            'fluid': False,
            'media_queries': {
                'xs': ['(max-width: 768px)'],
                'sm': ['(min-width: 768px)', '(max-width: 992px)'],
                'md': ['(min-width: 992px)', '(max-width: 1200px)'],
                'lg': ['(min-width: 1200px)'],
            },
        }
    },
}

Please refer to the DjangoCMS documentation for details about these settings with the exception of the dictionary glossary. This latter setting is special to djangocms-cascade: It gives the placeholder the ability to behave like a plugin for the Cascade app. Remember, each djangocms-cascade plugin stores all of its settings inside a Python dictionary which is serialized into a single database field. By having a placeholder behaving like a plugin, here this so named glossary is emulated using an additional entry inside the setting CMS_PLACEHOLDER_CONF, and it should:

• include all the settings a child plugin would expect from a real container plugin
• reflect how hard coded container was defined (e.g. whether it is fluid or not)

Nested Columns and Rows¶

One of the great features of Bootstrap is the ability to nest Rows inside Columns. These nested Rows then can contain Columns of 2nd level order. A quick example:

<div class="container">
  <div class="row">
    <div class="col-md-3">
      Left column
    </div>
    <div class="col-md-9">
      <div class="row">
        <div class="col-md-6">
          Left nested column
        </div>
        <div class="col-md-6">
          Right nested column
        </div>
      </div>
    </div>
  </div>
</div>

rendered, it would look like:

If a responsive image shall be placed inside a column, we must estimate the width of this image, so that when rendered, it fits exactly into that column. We want easy-thumbnails to resize our images to the columns width and not having the browser to up- or down-scale them.

Therefore djangocms-cascade keeps track of all the breakpoints and the chosen column widths. For simplicity, this example only uses the breakpoint “medium”. The default Boostrap settings for this width is 992 pixels. Doing simple math, the outer left column widths gives 3 / 12 * 992 = 248 pixels. Hence, adding a responsive image to that column means, that easy-thumnails automatically resizes it to a width of 248 pixels.

To calculate the width of the nested columns, first evaluate the width of the outer right column, which is 9 / 12 * 992 = 744 pixels. Then this width is subdivided again, using the the width of the nested columns, which is 6 / 12 * 744 = 372 pixels.

These calculations are always performed recursively for all nested column and for all available breakpoints.

Other Bootstrap3 specific Plugins¶

{% load bootstrap3_tags %}
...
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a class="navbar-brand" href="/">Project name</a>
    </div>
    <div class="collapse navbar-collapse">
      <ul class="nav navbar-nav">{% main_menu %}</ul>
    </div>
  </div>
</div>

Configuration¶

The SegmentationPlugin must be activated separately on top of other djangocms-cascade plugins. In settings.py, add to

INSTALLED_APPS = (
    ...
    'cmsplugin_cascade',
    'cmsplugin_cascade.segmentation',
    ...
)

Then, depending on what kind of data shall be emulated, add a list of two-tuples to the configuration settings CMSPLUGIN_CASCADE['segmentation_mixins']. The first entry of each two-tuple specifies the mixin class added the the proxy model for the SegmentationPlugin. The second entry specifies the mixin class added the the model admin class for the SegmentationPlugin.

# this entry is optional:
CMSPLUGIN_CASCADE = {
    ...
    'segmentation_mixins': (
        ('cmsplugin_cascade.segmentation.mixins.EmulateUserModelMixin', 'cmsplugin_cascade.segmentation.mixins.EmulateUserAdminMixin',),  # the default
        # other segmentation plugin classes
    ),
    ...
}

Usage¶

When editing djangoCMS plugins in Structure mode, below the section Generic a new plugin type appears, named Segment.

This plugin now behaves as an if block, which is rendered only, if the specified condition evaluates to true. The syntax used to specify the condition, is the same as used in the Django template language. Therefore it is possible to evaluate against more than one condition and combine them with and, or and not as described in boolean operators in the Django docs

Immediately below a segmentation block using the condition tag if, it is possible to use the tags elif or else. This kind of conditional blocks is well known to Python programmers.

Note, that when rendering pages in djangoCMS, a RequestContext- rather than a Context-object is used. This RequestContext is populated by the user object if 'django.contrib.auth.context_processors.auth' is added to your settings.py TEMPLATE_CONTEXT_PROCESSORS. This therefore is a prerequisite when the Segmentation plugin evaluates conditions such as user.username == "john".

Emulating Users¶

As of version 0.5.0, in djangocms-cascade a staff user or administrator can emulate the currently logged in user. If this plugin is activated, in the CMS toolbar a new menu tag appears named “Segmentation”. Here a staff user can select another user. All evaluation conditions then evaluate against this selected user, instead of the currently logged in user.

It is quite simple to add other overriding emulations. Have a look at the class cmsplugin_cascade.segmentation.mixins.EmulateUserMixin. This class then has to be added to your configuration settings CMSPLUGIN_CASCADE_SEGMENTATION_MIXINS. It then overrides the evaluation conditions and the toolbar menu.

Configure a Cascade Plugins to optionally share some fields¶

Configuring a plugin to share specific fields with other plugins of the same type is very easy. In the projects settings.py, assure that 'cmsplugin_cascade.sharable' is part of your INSTALLED_APPS.

Then add a dictionary of Cascade plugins, with a list of fields which shall be sharable. For example, with this settings, the image plugin can be configured to share its sizes and rendering options among each other.

CMSPLUGIN_CASCADE = {
    ...
    'plugins_with_sharables': {
        'BootstrapImagePlugin': ('image-shapes', 'image-width-responsive', 'image-width-fixed', 'image-height', 'resize-options',),
    },
    ...
}

Control some named settings¶

Whenever a plugin is configured to allow to share fields, at the bottom of the plugin editor a special field appears:

By activating the checkbox, adding an arbitrary name next to it and saving the plugin, an entity of sharable fields is saved in the database. Now, whenever someone starts to edit a plugin of this type, a select box appears on the top of the editor:

By choosing a previously named shared settings, the configured fields are disabled for input and replaced by their shared field’s counterparts.

In order to edit these shared fields in the administration backend, one must access Home › Cmsplugin_cascade › Shared between Plugins. By choosing a named shared setting, one can enter into the shared field’s editor. This editor auto adopts to the fields declared as shared, hence will change from entity to entity. For the above example, it may look like this:

In this editor one can change these shared settings globally, for all plugin instances where this named shared settings have been applied to.

Configure a Cascade plugins to accept extra fields¶

Configuring a plugin to allow an HTML id tag, an extra CSS classes or some inline styles is very easy. In the projects settings.py, assure that 'cmsplugin_cascade.extra_fields' is part of your INSTALLED_APPS.

Then add a list of Cascade plugins, which shall be extendible. It is a good idea to enable at least these plugins for extendibility:

CMSPLUGIN_CASCADE = {
    ...
    'plugins_with_extra_fields': ('BootstrapButtonPlugin', 'BootstrapRowPlugin',
        'SimpleWrapperPlugin', 'HorizontalRulePlugin',
    ),
    ...
}

If at least one plugin has been added to this settings variable, the Django administration backend offers an additional view:

Home › Cmsplugin_cascade › Custom CSS classes and styles › Add Custom CSS classes styles

Here the site administrator can specify, which extra CSS classes, ID tags and extra inline styles may be used by a concrete plugin.

Configure the kind of extra inline styles a Cascade plugin may accept¶

By default, djangocms-cascade specifies a sensible set of CSS styles, which can be added to the Cascade plugins, if enabled. This set however might not be enough for your installation and therefore can be extended by the settings variable CMSPLUGIN_CASCADE['extra_inline_styles'] containing an OrderedDict. The key element is an arbitrary name. The value element is a 2-tuple whose first element is a list of CSS inline styles. The second element of this tuple specifies the widget to be used to render the input fields.

Please check the default in cmsplugin_cascade/settings.py on how to set this list of extra inline styles.

Enable extra fields¶

To enable this feature, in the administration backend navigate to

Home › Cmsplugin_cascade › Custom CSS classes and styles and click onto the button named Add Custom CSS classes styles.

From the field named “Plugin Name”, for instance select Bootstrap Simple Wrapper. Then, from the field named “Site”, select the current site.

Change the path for template lookups¶

Some Bootstrap Plugins are shipped with templates, which are optimized to be rendered by Angular-UI rather than the default jQuery. These alternative templates are located in the folder cascade/bootstrap3/angular-ui. If your project uses AngularJS instead of jQuery, then configure the lookup path in settings.py with

CMSPLUGIN_CASCADE = {
    ...
    'bootstrap3': {
        ...
        'template_basedir': 'angular-ui',
    },
}

This lookup path is applied only to the Plugin’s field render_template prepared for it. Such a template contains the placeholder {}, which is expanded to the configured template_basedir.

For instance, the CarouselPlugin defines its render_template such as:

class CarouselPlugin(BootstrapPluginBase):
    ...
    render_template = 'cascade/bootstrap3/{}/carousel.html'
    ...

Configure Cascade Plugins to be rendered using alternative templates¶

All plugins which offer more than one rendering template, shall be added in the projects settings.py to the dictionary CMSPLUGIN_CASCADE['plugins_with_extra_render_templates']. Each item in this dictionary consists of a key naming the plugin and a value containing a list of two-tuples. The first element of this two-tuple must be the templates filename, while the second element shall contain an arbitrary name to identify that template.

Example:

CMSPLUGIN_CASCADE = {
    ...
    'plugins_with_extra_render_templates': {
        'TextLinkPlugin': (
            ('cascade/link/text-link.html', _("default")),
            ('cascade/link/text-link-linebreak.html', _("with linebreak")),
        )
    },
    ...
}

Persisting the Clipboard¶

In the context menu of a CMS plugin, use Cut or Copy to move a plugin together with its children to the CMS clipboard. In Edit Mode this clipboard is available from the primary menu item within the CMS toolbar. From this clipboard, the copy plugins can be dragged and dropped to any CMS placeholder which is allowed to accept the root node.

Since the content of the clipboard is overridden by every operation which cuts or copies a tree of plugins, djangocms-cascade offers some functionality to persist the clipboard’s content. To do this, locate Persited Clipboard Content in Django’s administration backend.

The Identifier field is used to give a unique name to the persited clipboard entity.

The Save button fetches the content from the CMS clipboard and persists it.

The Restore button replaces the content of the CMS clipboard with the current persisted entity. This is the opposite operation of Save.

Since the clipboard content is serialized using JSON, the site administrator can grab and paste it into another site using djangocms-cascade, if persisting clipboards are enabled.

INSTALLED_APPS = (
    ...
    'cmsplugin_cascade',
    'cmsplugin_cascade.clipboard',
    ...
)

Simple Example¶

This plugin is very simple and just renders static content which has been declared in the template.

from cms.plugin_pool import plugin_pool
from cmsplugin_cascade.plugin_base import CascadePluginBase

class StylishPlugin(CascadePluginBase):
    name = 'Stylish Element'
    render_template = 'myapp/cascade/stylish-element.html'

plugin_pool.register_plugin(StylishPlugin)

If the editor form pops up for this plugin, a dumb message appears: “There are no further settings for this plugin”. This is because no editable fields have been added to that plugin yet.

Customize Stored Data¶

In order to make the plugin remember its settings and other optional data, the programmer must add a list of special form fields to its plugin. These fields then are used to auto-generate the editor for this DjangoCMS plugin.

Each of those form fields handle a special field value, or in some cases, a list of field values. They all require a widget, which is used when rendering the editors form.

Lets add a simple selector to choose between a red and a green color. Do this by adding a PartialFormField to a member list named glossary_fields.

from django.forms import widgets
from cmsplugin_cascade.plugin_base import CascadePluginBase, PartialFormField

class StylishPlugin(CascadePluginBase):
    ...
    glossary_fields = (
        PartialFormField('color',
            widgets.Select(choices=(('red', 'Red'), ('green', 'Green'),)),
            label="Element's Color",
            initial='red',
            help_text="Specify the color of the DOM element."
        ),
        # more PartialFormField objects
    )

In the plugin’s editor, the form now pops up with a single select box, where the user can choose between a red and a green element.

A PartialFormField accepts five arguments:

• The name of the field. It must be unique in the given list of glossary_fields.
• The widget. This can be a built-in Django widget or any valid widget derived from it.
• The label used to describe the field. If omitted, the name of the partial form field is used.
• An optional initial value to be used with Radio- or Select fields.
• An optional help_text to describe the field’s purpose.

Widgets for a Partial Form Field¶

For single text fields or select boxes, Django’s built-in widgets, such as widgets.TextInput or widgets.RadioSelect can be used. Sometimes these simple widgets are not enough, therefore some special input widgets have been prepared to be used with DjangoCMS-Cascade. They are all part of the module cmsplugin_cascade.widgets.

Overriding the Form¶

For the plugin editor, djangocms-cascade automatically creates a form for each PartialFormField in the list of glossary_fields. Sometimes however, you might need more control over the fields displayed in the editor, versus the fields stored inside the glossary.

Similar to the Django’s admin.ModelAdmin, this can be achieved by overriding the plugins form element. Such a customized form can add as many fields as required, while the controlled glossary contains a compact summary.

To override the plugins form, add a member form to your plugin. This member variable shall refer to a customized form derived from forms.models.ModelForm. For further details about how to use this feature, refer to the supplied implementations.

Overriding the Model¶

Since all djangocms-cascade plugins store their data in a JSON-serializable field, there rarely is a need to add another database field to the common models CascadeElement and/or SharableCascadeElement and thus no need for database migrations.

However, quite often there is a need to add or override the methods for these models. Therefore each Cascade plugin creates its own proxy model on the fly. These models are derived from CascadeElement and/or SharableCascadeElement and named like the plugin class, with the suffix Model. By default, their behavior is the same as for their parent model classes.

To extend this behavior, the author of a plugin may declare a tuple of mixin classes, which are injected during the creation of the proxy model. Example:

class MySpecialPropertyMixin(object):
    def processed_value(self):
        value = self.glossary.get('field_name')
        # process value
        return value

class MySpecialPlugin(LinkPluginBase):
    module = 'My Module'
    name = 'My special Plugin'
    model_mixins = (MySpecialPropertyMixin,)
    render_template = 'my_module/my_special_plugin.html'
    glossary_fields = (
        PartialFormField('field_name',
            widgets.TextInput(),
        ),
        # other partial form fields
    )
    ...

The proxy model created for this plugin class, now contains the extra method content(), which for instance may be accessed during template rendering.

templates/my_module/my_special_plugin.html:

<div>{{ instance.processed_value }}</div>

Needless to say, that you can’t add any extra database fields to the class named MySpecialPropertyMixin, since the corresponding model class is marked as proxy.

Plugin Attribute Reference¶

CascadePluginBase is derived from CMSPluginBase, so all CMSPluginBase attributes can also be overridden by plugins derived from CascadePluginBase. Please refer to their documentation for details.

Additionally BootstrapPluginBase allows the following attributes:

@classmethod
def get_identifier(cls, obj):
    return 'A plugin name'

SimpleWrapperPlugin¶

Use this plugin to add a wrapping element around a group of other plugins. Currently these HTML elements can be used as wrapper: <div>, <span>, <section>, <article>. There is one special wrapper named naked. It embeds its children only logically, without actually embedding them into any HTML element.

HorizontalRulePlugin¶

This plugins adds a horizontal rule <hr> to the DOM.

HeadingPlugin¶

This plugins adds a text heading <h1>...``<h6>`` to the DOM. Although simple headings can be achieved with the TextPlugin, there they can’t be styled using special CSS classes or styles. Here the HeadingPlugin can be used, since any allowed CSS class or style can be added.

0.8.0.dev0¶

• Compatible with Django-1.9
• Fixed #133: BootstrapPanelPlugin now supports custom CSS classes.
• Fixed #132: Carousel Slide plugin with different form.
• Fixed migration problems for proxy models outside Cascade.
• Replaced SelectMultiple against CheckboxSelectMultiple in admin for extra fields.
• Removed SegmentationAdmin from admin backend.
• Disallow whitespace in CSS attributes.
• Require django-reversion 1.10.1 or newer.
• Require django-polymorphic 0.9.1 or newer.
• Require django-filer 1.1.1 or newer.
• Require django-treebeard 4.0 or newer.
• Require django-sekizai 0.9.0 or newer.

0.7.3¶

• Use the outer width for fluid containers. This allows us to add images and carousels which extend the the browser’s edges.
• Fixed #132: Carousel Slide plugin different form.
• Fixed #133: BootstrapPanelPlugin does not support custom CSS classes.
• Fixed #134: More plugins can be children of the SimpleWrapperPlugin. This allows us to be more flexible when building the DOM tree.
• BootstrapContainerPlugin now by default accepts extra inline styles and CSS classes.

0.7.2¶

• Add a possibility to prefix Cascade plugins with a symbol of your choice, to avoid confusion if the same name has been used by another plugin.
• All Bootstrap plugins can override their templates globally though a configuration settings variable. Usefule to switch between jQuery and AngularJS versions of a widget.
• Added TabSet and TabPanel plugins.
• It is possible to persist the content of the clipboard in the database, retrieve and export it as JSON to be reimported on an unrelated site.

0.7.1¶

• Added a HeadingPlugin to add single text headings independently of the HTML TextEditorPlugin.

0.7.0¶

Cleanup release, removing a lot of legacy code. This adds some incompatibilities to previous versions:

• Instead of half o dozen of configuration directives, now one Python dict is used. Therefore check your settings.py for configurations starting with CMSPLUGIN_CASCADE_....
• Tested with Django-1.8. Support for version 1.7 and lower has been dropped.
• Tested with djangoCMS version 3.2. Support for version 3.0 and lower has been dropped.
• Tested with django-select2 version 5.2. Support for version 4 has been dropped.
• The demo project now uses SASS instead of plain CSS, but SASS is not a requirement during normal development.

0.6.2¶

• In Segment: A condition raising a TemplateSyntaxError now renders that error inside a HTML comment. This is useful for debugging non working conditions.
• In Segment: An alternative AdminModel to UserAdmin, using a callable instead of a model field, now works.
• In Segment: It is possible to use segmentation_list_display = (list-of-fields) in an alternative AdminModel, to override the list view, when emulating a user.

0.6.1¶

• Added a panel plugin to support the Bootstrap Panel.
• Added experimental support for secondary menus.
• Renamed AccordionPlugin to BootstrapAccordionPlugin for consistency and to avoid future naming conflicts.

0.6.0¶

• Fixed #79: The column width is not reduced in width, if a smaller column precedes a column for a smaller displays.
• Fixed: Added extra space before left prefix in buttons.
• Enhanced: Access the link content through the glossary’s link_content.
• New: Plugins now can be rendered using an alternative template, choosable through the plugin editor.
• Fixed in SegmentationPlugin: When overriding the context, this updated context was only used for the immediate child of segment. Now the overridden context is applied to all children and grandchildren.
• Changed in SegmentationPlugin: When searching for siblings, use a list index instead of get_children().get(position=...).
• Added unit tests for SegmentationPlugin.
• Added support for django-reversion.
• By using the setting CMSPLUGIN_CASCADE_LINKPLUGIN_CLASSES, one can replace the class LinkPluginBase by an alternative implementation.
• When using Extra Styles distances now can have negative values.
• In caption field of CarouselSlidePlugin it now is possible to set links onto arbitrary pages.

Possible backwards incompatibility:

• For consistency with naming conventions on other plugins, renamed cascade/plugins/link.html -> cascade/link/link-base.html. Check your templates!
• The setting CMSPLUGIN_CASCADE_SEGMENTATION_MIXINS now is a list of two-tuples, where the first declares the plugin’s model mixin, while the second declares the model admin mixin.
• Removed from setting: CMSPLUGIN_CASCADE_BOOTSTRAP3_TEMPLATE_DIR. The rendering template now can be specified during runtime.
• Refactored and moved SimpleWrapperPlugin and HorizontalRulePlugin from cmsplugin_cascade/bootstrap3/ into cmsplugin_cascade/generic/. The glossary field element_tag has been renamed to tag_type.
• Refactored LinkPluginBase so that external implementations can create their own version, which then is used as base for TextLinkPlugin, ImagePlugin and PicturePlugin.
• Renamed: PanelGroupPlugin -> Accordion, PanelPlugin -> AccordionPanelPlugin, because the Bootstrap project renamed them back to their well known names.

0.5.0¶

• Added SegmentationPlugin. This allows to conditionally render parts of the DOM, depending on the status of various request object members, such as user.
• Setting CASCADE_LEAF_PLUGINS has been replaced by CMSPLUGIN_CASCADE_ALIEN_PLUGINS. This simplifies the programming of third party plugins, since the author of a plugin now only must set the member alien_child_classes = True.

0.4.5¶

• Fixed: If no breakpoints are set, don’t delete widths and offsets from the glossary, as otherwise this information is lost.
• Fixed broken import for PageSelectFormField when not using django_select2.
• Admin form for PluginExtraFields now is created on the fly. This fixes a rare circular dependency issue, when accessing plugin_pool.get_all_plugins().

0.4.4¶

• Removed hard coded input fields for styling margins from BootstrapButtonPlugin, since it is possible to add them through the Extra Fields dialog box.
• [Column ordering](http://getbootstrap.com/css/#grid-column-ordering) using col-xx-push-n and col-xx-pull-n has been added.
• Fixed: Media file linkplugin.js was missing for BootstrapButtonPlugin.
• Hard coded configuration option EXTRA_INLINE_STYLES can now be overridden by the projects settings

0.4.3¶

• The templatetag bootstrap3_tags and the templates to build Boostrap3 styled menus, breadcrumbs and paginator, have been moved into their own repository at https://github.com/jrief/djangocms-bootstrap3.
• Column ordering using col-xx-push-n and col-xx-pull-n has been added.

0.4.2¶

• Fixed: Allow empty setting for CMSPLUGIN_CASCADE_PLUGINS
• Fixed: Use str(..) instead of b’’ in combination with from __future__ import unicode_literals

0.4.1¶

• Fixed: Exception when saving a ContainerPlugin with only one breakpoint.
• The required flag on a field for an inherited LinkPlugin is set to False for shared settings.
• Fixed: Client side code for disabling shared settings did not work.

0.4.0¶

• Renamed context from model CascadeElement to glossary`. The identifier ``context lead to too much confusion, since it is used all way long in other CMS plugins, where it has a complete different meaning.
• Renamed partial_fields in all plugins to glossary_fields, since that’s the model field where they keep their information.
• Huge refactoring of the code base, allowing a lot of more features.

0.3.2¶

• Fixed: Missing unicode conversion for method get_identifier()
• Fixed: Exception handler for form validation used getattr incorrectly.

0.3.1¶

• Added compatibility layer for Python-3.3.

0.3.0¶

• Complete rewrite. Now offers elements for Bootstrap 3 and other CSS frameworks.

0.2.0¶

• Added carousel.

0.1.2¶

• Fixed: Added missign migration.

0.1.1¶

• Added unit tests.

0.1.0¶

• First published revision.