Plugins

class cms.plugin_base.CMSPluginBase(model=None, admin_site=None)

get_render_template(self, context, instance, placeholder)

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

model

alias of CMSPlugin

classmethod get_child_class_overrides(slot, page)

Returns a list of plugin types that are allowed as children of this plugin.

classmethod get_child_classes(slot, page, instance=None)

Returns a list of plugin types that can be added as children to this plugin.

classmethod get_child_plugin_candidates(slot, page)

Returns a list of all plugin classes that will be considered when fetching all available child classes for this plugin.

classmethod get_empty_change_form_text(obj=None)

Returns the text displayed to the user when editing a plugin that requires no configuration.

get_cache_expiration(request, instance, placeholder)

Provides hints 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;

• A TZ-aware datetime of a specific date and time in the future when this plugin’s content expires;

• A datetime.timedelta instance indicating how long, relative to the response timestamp that the content can be cached;

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

There are constants are defined in cms.constants that may be helpful:

• EXPIRE_NOW

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

get_fieldsets(request, obj=None)

Same as from base class except if there are no fields, show an info message.

get_plugin_urls()

Return URL patterns for which the plugin wants to register views for.

get_vary_cache_on(request, instance, placeholder)

Provides hints to the placeholder, and in turn to the page for determining VARY headers for the response.

Must return one of:

• None (default),

• String of a case-sensitive header name, or

• iterable of case-sensitive header names.

NOTE: This only makes sense to use with caching. If this plugin has cache = False or plugin.get_cache_expiration(…) returns 0, get_vary_cache_on() will have no effect.

icon_alt(instance)

Overwrite this if necessary if text_enabled = True Return the ‘alt’ text to be used for an icon representing the plugin object in a text editor.

icon_src(instance)

Overwrite this if text_enabled = True

Return the URL for an image to be used for an icon for this plugin instance in a text editor.

log_addition(request, obj, bypass=None)

Log that an object has been successfully added.

The default implementation creates an admin LogEntry object.

log_change(request, obj, message, bypass=None)

Log that an object has been successfully changed.

The default implementation creates an admin LogEntry object.

log_deletion(request, obj, object_repr, bypass=None)

Log that an object will be deleted. Note that this method must be called before the deletion.

The default implementation creates an admin LogEntry object.

render_change_form(request, context, add=False, change=False, form_url='', obj=None)

We just need the popup interface here

response_add(request, obj, **kwargs)

Determine the HttpResponse for the add_view stage.

response_change(request, obj)

Determine the HttpResponse for the change_view stage.

save_form(request, form, change)

Given a ModelForm return an unsaved instance. change is True if the object is being changed, and False if it’s being added.

save_model(request, obj, form, change)

Override original method, and add some attributes to obj This have to be made, because if object is newly created, he must know where he lives.

form = None

class cms.plugin_base.PluginMenuItem(name, url, data=None, question=None, action='ajax', attributes=None)

class cms.models.pluginmodel.CMSPlugin(*args, **kwargs)

The base class for a CMS plugin model. When defining a new custom plugin, you should store plugin-instance specific information on a subclass of this class.

An example for this would be to store the number of pictures to display in a galery.

Two restrictions apply when subclassing this to use in your own models: 1. Subclasses of CMSPlugin cannot be further subclassed 2. Subclasses of CMSPlugin cannot define a “text” field.

exception DoesNotExist

exception MultipleObjectsReturned

classmethod fix_tree(**kwargs)

Fixes the plugin tree by first calling treebeard fix_tree and the recalculating the correct position property for each plugin.

copy_plugin(target_placeholder, target_language, parent_cache, no_signals=False)

Copy this plugin and return the new plugin.

The logic of this method is the following:

# get a new generic plugin instance # assign the position in the plugin tree # save it to let mptt/treebeard calculate the tree attributes # then get a copy of the current plugin instance # assign to it the id of the generic plugin instance above;

this will effectively change the generic plugin created above into a concrete one

# copy the tree related attributes from the generic plugin to

the concrete one

# save the concrete plugin # trigger the copy relations # return the generic plugin instance

This copy logic is required because we don’t know what the fields of the real plugin are. By getting another instance of it at step 4 and then overwriting its ID at step 5, the ORM will copy the custom fields for us.

copy_relations(old_instance)

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

delete(no_mp=False, *args, **kwargs)

Removes a node and all it’s descendants.

get_bound_plugin()

Returns an instance of the plugin model configured for this plugin type.

get_instance_icon_alt()

Get alt text for instance’s icon

get_instance_icon_src()

Get src URL for instance’s icon

get_plugin_instance(admin=None)

Given a plugin instance (usually as a CMSPluginBase), this method returns a tuple containing:

instance - The instance AS THE APPROPRIATE SUBCLASS OF

CMSPluginBase and not necessarily just ‘self’, which is often just a CMSPluginBase,

plugin - the associated plugin class instance (subclass

of CMSPlugin)

get_position_in_placeholder()

1 based position!

move(target, pos=None)

Moves the current node and all it’s descendants to a new position relative to another node.

Raises:

PathOverflow – when the library can’t make room for the node’s new position

notify_on_autoadd(request, conf)

Method called when we auto add this plugin via default_plugins in CMS_PLACEHOLDER_CONF. Some specific plugins may have some special stuff to do when they are auto added.

notify_on_autoadd_children(request, conf, children)

Method called when we auto add children to this plugin via default_plugins/<plugin>/children in CMS_PLACEHOLDER_CONF. Some specific plugins may have some special stuff to do when we add children to them. ie : TextPlugin must update its content to add HTML tags to be able to see his children in WYSIWYG.

post_copy(old_instance, new_old_ziplist)

Handle more advanced cases (eg Text Plugins) after the original is copied

refresh_from_db(*args, **kwargs)

Reload field values from the database.

By default, the reloading happens from the database this instance was loaded from, or by the read router if this instance wasn’t loaded from any database. The using parameter will override the default.

Fields can be used to specify which fields to reload. The fields should be an iterable of field attnames. If fields is None, then all non-deferred fields are reloaded.

When accessing deferred fields of an instance, the deferred loading of the field will call this method.

save(no_signals=False, *args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class cms.plugin_pool.PluginPool

get_plugin(name)

Retrieve a plugin from the cache.

register_plugin(plugin)

Registers the given plugin(s).

Static sanity checks is also performed.

If a plugin is already registered, this will raise PluginAlreadyRegistered.

unregister_plugin(plugin)

Unregisters the given plugin(s).

If a plugin isn’t already registered, this will raise PluginNotRegistered.

validate_templates(plugin=None)

Plugins templates are validated at this stage

Plugin utility functions

cms.utils.plugins.assign_plugins(request, placeholders, template=None, lang=None, is_fallback=False)

Fetch all plugins for the given placeholders and cast them down to the concrete instances in one query per type.

cms.utils.plugins.copy_plugins_to_placeholder(plugins, placeholder, language=None, root_plugin=None)

cms.utils.plugins.downcast_plugins(plugins, placeholders=None, select_placeholder=False, request=None)

cms.utils.plugins.get_bound_plugins(plugins)

cms.utils.plugins.get_plugin_class(plugin_type)

cms.utils.plugins.get_plugin_model(plugin_type)

cms.utils.plugins.get_plugin_restrictions(plugin, page=None, restrictions_cache=None)

cms.utils.plugins.get_plugins(request, placeholder, template, lang=None)

cms.utils.plugins.has_reached_plugin_limit(placeholder, plugin_type, language, template=None, parent_plugin=None)

Checks if placeholder has reached it’s global plugin limit, if not then it checks if it has reached it’s plugin_type limit.