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