13. Choose an alternative rendering template

Sometimes you must render a plugin with a slightly different template, other than the given default. A possible solution is to create a new plugin, inheriting from the given one and overriding the render_template attribute with a customized template. This however adds another plugin to the list of registered CMS plugins.

A simpler solution to solve this problem, is to allow a plugin to be rendered with a customized template out of a set of alternatives.

13.1. 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'
    ...

13.2. 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")),
        )
    },
    ...
}

13.2.1. Usage

When editing a djangoCMS plugins with alternative rendering templates, the plugin editor adds a select box containing choices for alternative rendering templates. Choose one other than the default, and the plugin will be rendered using that template.