Plugins

admin_preview

Default:

Should the plugin be previewed in admin when you click on the plugin or save it?

allow_children

Default: False

Can this plugin have child plugins? Or can other plugins be placed inside this plugin? If set to True you are responsible to render the children in your plugin template.

Please use something like this or something similar:

Be sure to access instance.child_plugin_instances to get all children. They are pre-filled and ready to use. To finally render your child plugins use the {% render_plugin %} templatetag.

See also: child_classes, , require_parent

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.

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")
    change_form_template = "admin/cms/page/plugin_change_form.html"

child_classes

Default: None

A List of Plugin Class Names. If this is set, only plugins listed here can be added to this plugin.

disable_child_plugins

Default: False

Disables dragging of child plugins in structure mode.

frontend_edit_template

Default: cms/toolbar/placeholder_wrapper.html

The template used for wrapping the plugin in frontend editing.

model

Default: CMSPlugin

If the plugin requires per-instance settings, then this setting must be set to a model that inherits from CMSPlugin.

page_only

Default: False

Can this plugin only be attached to a placeholder that is attached to a page? Set this to True if you always need a page for this plugin.

parent_classes

Default: None

A list of Plugin Class Names. If this is set, this plugin may only be added to plugins listed here.

render_plugin

Default: True

Should the plugin be rendered at all, or doesn’t it have any output? If render_plugin is True, then you must also define render_template()

render_template

Default:

The path to the template used to render the template. If render_plugin is True either this or get_render_template must be defined;

require_parent

Default: False

Is it required that this plugin is a child of another plugin? Or can it be added to any placeholder, even one attached to a page.

text_enabled

Default: False

Can the plugin be inserted inside the text plugin? If this is True then icon_src() must be overridden.

render

The render() method takes three arguments:

context: The context with which the page is rendered.
instance: The instance of your plugin that is rendered.
placeholder: The name of the placeholder that is rendered.

This method must return a dictionary or an instance of , which will be used as context to render the plugin template.

New in version 2.4.

By default this method will add instance and placeholder to the context, which means for simple plugins, there is no need to overwrite this method.

get_render_template

If you need to determine the plugin render model at render time you can implement get_render_template() method on the plugin class; this method taks the same arguments as render. The method must return a valid template file path.

Example:

icon_src

By default, this returns an empty string, which, if left unoverridden would result in no icon rendered at all, which, in turn, would render the plugin uneditable by the operator inside a parent text plugin.

Therefore, this should be overridden when the plugin has text_enabled set to True to return the path to an icon to display in the text of the text plugin.

icon_src takes 1 argument:

instance: The instance of the plugin model

Example:

def icon_src(self, instance):
    return settings.STATIC_URL + "cms/img/icons/plugins/link.png"

icon_alt

Although it is optional, authors of “text enabled” plugins should consider overriding this function as well.

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

icon_alt() takes 1 argument:

instance: The instance of the plugin model

The default implementation is as follows:

get_extra_placeholder_menu_items

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

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

get_extra_local_plugin_menu_items(self, request, plugin)

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.

CMSPlugin Attributes and Methods Reference

These are a list of attributes and methods that can (or should) be overridden on your plugin’s model definition.

translatable_content_excluded_fields

Default: [ ]

A list of plugin fields which will not be exported while using get_translatable_content().

copy_relations

Handle copying of any relations attached to this plugin. Custom plugins have to do this themselves.

copy_relations takes 1 argument:

old_instance: The source plugin instance

get_translatable_content

Get a dictionary of all content fields (field name / field value pairs) from the plugin.

Example:

from djangocms_text_ckeditor.models import Text
plugin = Text.objects.get(pk=1).get_plugin_instance()[0]
plugin.get_translatable_content()
# returns {'body': u'<p>I am text!</p>\n'}

post_copy

Can (should) be overridden to handle the copying of plugins which contain children plugins after the original parent has been copied.

post_copy takes 2 arguments:

old_instance: The old plugin instance instance
new_old_ziplist: A list of tuples containing new copies and the old existing child plugins.

set_translatable_content

Takes a dictionary of plugin fields (field name / field value pairs) and overwrites the plugin’s fields. Returns True if all fields have been written successfully, and False otherwise.

set_translatable_content takes 1 argument:

: A dictionary containing the field names and translated content for each.

Example: