Plugins#

CMSPluginBase Attributes and Methods Reference#

class cms.plugin_base.CMSPluginBase#

Inherits django.contrib.admin.ModelAdmin and in most respects behaves like a normal sub-class. Note however that some attributes of ModelAdmin simply won’t make sense in the context of a Plugin.

Attributes

admin_preview#

Default: False

If True, displays a preview in the admin.

allow_children#

Default: False

Allows this plugin to have child plugins - other plugins placed inside it?

If True you need to ensure that your plugin can render its children in the plugin template. For example:

{% load cms_tags %}
<div class="myplugin">
    {{ instance.my_content }}
    {% for plugin in instance.child_plugin_instances %}
        {% render_plugin plugin %}
    {% endfor %}
</div>

instance.child_plugin_instances provides access to all the plugin’s children. They are pre-filled and ready to use. The child plugins should be rendered using the {% render_plugin %} template tag.

cache#

Default: CMS_PLUGIN_CACHE

Is this plugin cacheable? If your plugin displays content based on the user or request or other dynamic properties set this to False.

If present and set to False, the plugin will prevent the caching of the resulting page.

Important

Setting this to False will effectively disable the CMS page cache and all upstream caches for pages where the plugin appears. This may be useful in certain cases but for general cache management, consider using the much more capable get_cache_expiration().

Warning

If you disable a plugin cache be sure to restart the server and clear the cache afterwards.

change_form_template#

Default: admin/cms/page/plugin/change_form.html

The template used to render the form when you edit the plugin.

Example:

class MyPlugin(CMSPluginBase):
    model = MyModel
    name = _("My Plugin")
    render_template = "cms/plugins/my_plugin.html"
    change_form_template = "admin/cms/page/plugin/change_form.html"

See also: icon_alt(), icon_src().

Methods

get_plugin_urls(instance)#

Returns the URL patterns the plugin wants to register views for. They are included under django CMS’s page admin URLS in the plugin path (e.g.: /admin/cms/page/plugin/<plugin-name>/ in the default case).

get_plugin_urls() is useful if your plugin needs to talk asynchronously to the admin.

get_render_template()#

If you need to determine the plugin render model at render time you can implement the get_render_template() method on the plugin class; this method takes the same arguments as render.

The method must return a valid template file path.

Example:

def get_render_template(self, context, instance, placeholder):
    if instance.attr = 'one':
        return 'template1.html'
    else:
        return 'template2.html'

get_extra_placeholder_menu_items(self, request, placeholder)#

Extends the context menu for all placeholders.

To add one or more custom context menu items that are displayed in the context menu for all placeholders when in structure mode, override this method in a related plugin to return a list of cms.plugin_base.PluginMenuItem instances.

get_extra_global_plugin_menu_items(self, request, plugin)#

Extends the context menu for all plugins.

To add one or more custom context menu items that are displayed in the context menu for all plugins when in structure mode, override this method in a related plugin to return a list of cms.plugin_base.PluginMenuItem instances.

get_extra_local_plugin_menu_items()#: Extends the context menu for a specific plugin. To add one or more custom context menu items that are displayed in the context menu for a given plugin when in structure mode, override this method in the plugin to return a list of cms.plugin_base.PluginMenuItem instances.

get_cache_expiration(self, request, instance, placeholder)#

Provides expiration value to the placeholder, and in turn to the page for determining the appropriate Cache-Control headers to add to the HTTPResponse object.

Must return one of:

None:

This means the placeholder and the page will not even consider this plugin when calculating the page expiration.

datetime:

A specific date and time (timezone-aware) in the future when this plugin’s content expires.

Important

The returned datetime must be timezone-aware or the plugin will be ignored (with a warning) during expiration calculations.

int:

An number of seconds that this plugin’s content can be cached.

There are constants are defined in cms.constants that may be useful: EXPIRE_NOW and MAX_EXPIRATION_TTL.

An integer value of 0 (zero) or EXPIRE_NOW effectively means “do not cache”. Negative values will be treated as EXPIRE_NOW. Values exceeding the value MAX_EXPIRATION_TTL will be set to that value.

Negative timedelta values or those greater than MAX_EXPIRATION_TTL will also be ranged in the same manner.

Similarly, datetime values earlier than now will be treated as EXPIRE_NOW. Values greater than MAX_EXPIRATION_TTL seconds in the future will be treated as MAX_EXPIRATION_TTL seconds in the future.

Parameters:

request – Relevant HTTPRequest instance.
instance – The CMSPlugin instance that is being rendered.

Return type:

None or datetime or int

get_vary_cache_on(self, request, instance, placeholder)#

Returns an HTTP VARY header string or a list of them to be considered by the placeholder and in turn by the page to caching behaviour.

Overriding this method is optional.

Must return one of:

None:

This means that this plugin declares no headers for the cache to be varied upon. (default)

string:

The name of a header to vary caching upon.

list of strings:

A list of strings, each corresponding to a header to vary the cache upon.

icon_alt()#

By default icon_alt() will return a string of the form: “[plugin type] - [instance]”, but can be modified to return anything you like.

This function accepts the instance as a parameter and returns a string to be used as the alt text for the plugin’s preview or icon.

Authors of text-enabled plugins should consider overriding this function as it will be rendered as a tooltip in most browser. This is useful, because if the same plugin is used multiple times, this tooltip can provide information about its configuration.

icon_alt() takes 1 argument:

instance: The instance of the plugin model

The default implementation is as follows:

def icon_alt(self, instance):
    return "%s - %s" % (force_str(self.name), force_str(instance))

CMSPlugin Attributes and Methods Reference#

class cms.models.pluginmodel.CMSPlugin#