Placeholders

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

Bases: Model

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

add_plugin(instance: CMSPlugin)

Added 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 placeholder’s plugin tree (1) to the last plugin (n, where n is the number of plugins in the placeholder).

It is discouraged to call this method directly from outside the CMS. Use the cms.api.add_plugin() function instead.

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)

Added 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(site_id=None)

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

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

Added in version 4.0.

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

Parameters:

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

edit_message = 'Edit object'

Message used in the frontend editing UI for static placeholder edit link

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

static_message = 'This is an external placeholder'

Message used in the frontend editing UI for static placeholder tooltip

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() → list[str]

Register the url for the edit field view