Plugins

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.

  See also: child_classes, parent_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.

  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: frontend_edit_template.

• child_classes

  Default: None

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

  See also: parent_classes.

• disable_child_plugins

  Default: False

  Disables dragging of child plugins in structure mode.

• form

  Custom form class to be used to edit this plugin.

• frontend_edit_template

  Default: cms/toolbar/placeholder_wrapper.html

  The template used for wrapping the plugin in frontend editing.

  See also: change_form_template.

• model

  Default: CMSPlugin

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

  See also: Storing configuration.

• module

  Will group the plugin in the plugin picker. If module is None, plugin is listed in the “Generic” group.

• name

  Will be displayed in the plugin picker.

• page_only

  Default: False

  Set to True if this plugin should only be used in a placeholder that is attached to a django CMS page, and not other models with PlaceholderFields.

  See also: child_classes, parent_classes, require_parent.

• parent_classes

  Default: None

  A list of the names of permissible parent classes for this plugin.

  See also: child_classes, require_parent.

• render_plugin

  If set to False, this plugin will not be rendered at all. Default: True

  If True, render_template() must also be defined.

  See also: render_template, get_render_template().

• render_template

  Default: None

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

  See also: render_plugin , get_render_template().

• 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.

  See also: child_classes, parent_classes.

• text_enabled

  Default: False

  Not all plugins are usable in text plugins. If your plugin is usable in a text plugin:

  • set this to True
  • make sure your plugin provides its own icon_src()

  See also: icon_src, icon_alt.

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'

  See also: render_plugin() , render_template()

• 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()

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

  This function accepts the instance as a parameter and returns a string to be used as the alt text for the plugin’s icon which will appear as a tooltip in most browsers. This is useful, because if the same plugin is used multiple times within the same text plugin, they will typically all render with the same icon rendering them visually identical to one another. This alt text and related tooltip will help the operator distinguish one from the others.

  By default icon_alt() 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:

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

  See also: text_enabled, icon_src.

• icon_src(instance)

  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"

  See also: text_enabled, icon_alt()

• render(context, instance, placeholder)

  This method returns the context to be used to render the template specified in render_template.

  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 django.template.Context, 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.

  If you overwrite this method it’s recommended to always populate the context with default values by calling the render method of the super class:

  def render(self, context, instance, placeholder):
      context = super(MyPlugin, self).render(context, instance, placeholder)
      ...
      return context

  Parameters:	context – Current template context. instance – Plugin instance that is being rendered. placeholder – Name of the placeholder the plugin is in.
  Return type:	dict

• text_editor_button_icon()

  When text_enabled is True, this plugin can be added in a text editor and there might be an icon button for that purpose. This method allows to override this icon.

  By default, it returns None and each text editor plugin may have its own fallback icon.

  text_editor_button_icon() takes 2 arguments:

  • editor_name: The plugin name of the text editor
  • icon_context: A dictionary containing information about the needed icon like width, height, theme, etc

  Usually this method should return the icon URL. But, it may depends on the text editor because what is needed may differ. Please consult the documentation of your text editor plugin.

  This requires support from the text plugin; support for this is currently planned for djangocms-text-ckeditor 2.5.0.

  See also: text_enabled.

class cms.plugin_base.``PluginMenuItem

• __init___(name, url, data, question=None, action=’ajax’, attributes=None)

  Creates an item in the plugin / placeholder menu

  Parameters:	name – Item name (label) url – URL the item points to. This URL will be called using POST data – Data to be POSTed to the above URL question – Confirmation text to be shown to the user prior to call the given URL (optional) action – Custom action to be called on click; currently supported: ‘ajax’, ‘ajax_add’ attributes – Dictionary whose content will be addes as data-attributes to the menu item

class cms.plugin_pool.``PluginPool