Placeholders#

class cms.models.placeholdermodel.Placeholder(*args, **kwargs)#

Bases: Model

Placeholders can be filled with plugins, which store or generate content.

add_plugin(instance)#

New in version 4.0.

Adds a plugin to the placeholder. The plugin’s position field must be set to the target position. Positions are enumerated from the start of the palceholder’s plugin tree (1) to the last plugin (n, where n is the number of plugins in the placeholder).

Parameters:: instance (cms.models.pluginmodel.CMSPlugin instance) – Plugin to add. It’s position parameter needs to be set.

Note

As of version 4 of django CMS the position counter does not re-start at 1 for the first child plugin. The position field and language field are unique for a placeholder.

Example:

new_child = MyCoolPlugin()
new_child.position = parent_plugin.position + 1  # add as first child: directly after parent
parent_plugin.placeholder.add(new_child)

clear(language=None)#: Deletes all plugins from the placeholder

delete_plugin(instance)#

New in version 4.0.

Removes a plugin and its descendants from the placeholder and database.

Parameters:: instance (cms.models.pluginmodel.CMSPlugin instance) – Plugin to add. It’s position parameter needs to be set.

get_cache_expiration(request, response_timestamp)#

Returns the number of seconds (from «response_timestamp») that this placeholder can be cached. This is derived from the plugins it contains.

This method must return: EXPIRE_NOW <= int <= MAX_EXPIRATION_IN_SECONDS

Return type:: int

get_filled_languages()#

Returns language objects for every language for which the placeholder has plugins.

This is not cached as it’s meant to be used in the frontend editor.

get_next_plugin_position(language, parent=None, insert_order='first')#

New in version 4.0.

Helper to calculate plugin positions correctly.

Parameters:

language (str) – language for which the position is to be calculated
parent (cms.models.pluginmodel.CMSPlugin instance) – Parent plugin or None (if position is on top level)
insert_order (str) – Either "first" (default) or "last"

get_plugin_tree_order(language, parent_id=None)#: Returns a list of plugin ids matching the given language ordered by plugin position.

get_plugins(language=None)#: Returns a queryset of plugins attached to this placeholder. If language is given only plugins in the given language are returned.

get_plugins_list(language=None)#: Returns a list of plugins attached to this placeholder. If language is given only plugins in the given language are returned.

get_vary_cache_on(request)#: Returns a list of VARY headers.

has_add_plugin_permission(user, plugin_type)#: Returns True if user has permission to add plugin_type to this placeholder.

has_add_plugins_permission(user, plugins)#: Returns True if user has permission to add all plugins in plugins to this placeholder.

has_change_permission(user)#: Returns True if user has permission to change all models attached to this placeholder.

has_change_plugin_permission(user, plugin)#: Returns True if user has permission to change plugin to this placeholder.

has_clear_permission(user, languages)#: Returns True if user has permission to delete all plugins in this placeholder

has_delete_plugin_permission(user, plugin)#: Returns True if user has permission to delete plugin to this placeholder.

has_delete_plugins_permission(user, languages)#: Returns True if user has permission to delete all plugins in this placeholder

has_move_plugin_permission(user, plugin, target_placeholder)#: Returns True if user has permission to move plugin to the target_placeholder.

has_plugins(language=None)#: Checks if placeholder is empty (False) or populated (True)

move_plugin(plugin, target_position, target_placeholder=None, target_plugin=None)#

New in version 4.0.

Moves a plugin within the placeholder (target_placeholder=None) or to another placeholder.

Parameters:

plugin (cms.models.pluginmodel.CMSPlugin instance) – Plugin to move
target_position (int) – The plugin’s new position
target_placeholder (cms.models.placeholdermodel.Placeholder instance) – Placeholder to move plugin to (or None)
target_plugin (cms.models.pluginmodel.CMSPlugin instance) – New parent plugin (or None). The target plugin must be in the same placeholder or in the target_placeholder if one is given.

The target_position is enumerated from the start of the palceholder’s plugin tree (1) to the last plugin (n, where n is the number of plugins in the placeholder).

cache_placeholder = True#: Flag caching the palceholder’s content

default_width#: A default width is passed to the templace context as width

is_editable = True#: If False the content of the placeholder is not editable in the frontend

is_static = False#: Set to “True” for static placeholders (by the template tag)

property page#: Gives the page object if the placeholder belongs to a cms.models.titlemodels.PageContent object (and not to some other model.) If the placeholder is not attached to a page it returns None

slot#: slot name that appears in the frontend

class cms.admin.placeholderadmin.FrontendEditableAdminMixin#

Adding FrontendEditableAdminMixin to models admin class allows to open that admin in the frontend by double-clicking on fields rendered with the render_model template tag.

get_urls()#: Register the url for the single field edit view

class cms.admin.placeholderadmin.PlaceholderAdminMixin#: Warning

PlaceholderAdminMixin is deprecated. It is no longer needed and thus will be removed