API References¶
cms.api¶
Python APIs for creating CMS content. This is done in cms.api
and not
on the models and managers, because the direct API via models and managers is
slightly counterintuitive for developers. Also the functions defined in this
module do sanity checks on arguments.
Warning
None of the functions in this module does any security or permission checks. They verify their input values to be sane wherever possible, however permission checks should be implemented manually before calling any of these functions.
Warning
Due to potential circular dependency issues, it’s recommended to import the api in the functions that uses its function.
e.g. use:
def my_function():
from cms.api import api_function
api_function(...)
instead of:
from cms.api import api_function
def my_function():
api_function(...)
Functions and constants¶
-
cms.api.
VISIBILITY_ALL
¶ Used for the
limit_menu_visibility
keyword argument tocreate_page()
. Does not limit menu visibility.
-
cms.api.
VISIBILITY_USERS
¶ Used for the
limit_menu_visibility
keyword argument tocreate_page()
. Limits menu visibility to authenticated users.
-
cms.api.
VISIBILITY_ANONYMOUS
¶ Used for the
limit_menu_visibility
keyword argument tocreate_page()
. Limits menu visibility to anonymous (not authenticated) users.
-
cms.api.
create_page
(title, template, language, menu_title=None, slug=None, apphook=None, apphook_namespace=None, redirect=None, meta_description=None, created_by='python-api', parent=None, publication_date=None, publication_end_date=None, in_navigation=False, soft_root=False, reverse_id=None, navigation_extenders=None, published=False, site=None, login_required=False, limit_visibility_in_menu=VISIBILITY_ALL, position="last-child", overwrite_url=None, xframe_options=Page.X_FRAME_OPTIONS_INHERIT, with_revision=False)¶ Creates a
cms.models.pagemodel.Page
instance and returns it. Also creates acms.models.titlemodel.Title
instance for the specified language.Parameters: - title (string) – Title of the page
- template (string) – Template to use for this page. Must be in
CMS_TEMPLATES
- language (string) – Language code for this page. Must be in
LANGUAGES
- menu_title (string) – Menu title for this page
- slug (string) – Slug for the page, by default uses a slugified version of title
- apphook (string or
cms.app_base.CMSApp
sub-class) – Application to hook on this page, must be a valid apphook - apphook_namespace (string) – Name of the apphook namespace
- redirect (string) – URL redirect
- meta_description (string) – Description of this page for SEO
- created_by (string of
django.contrib.auth.models.User
instance) – User that is creating this page - parent (
cms.models.pagemodel.Page
instance) – Parent page of this page - publication_date (datetime) – Date to publish this page
- publication_end_date (datetime) – Date to unpublish this page
- in_navigation (bool) – Whether this page should be in the navigation or not
- soft_root (bool) – Whether this page is a soft root or not
- reverse_id (string) – Reverse ID of this page (for template tags)
- navigation_extenders (string) – Menu to attach to this page. Must be a valid menu
- published (bool) – Whether this page should be published or not
- site (
django.contrib.sites.models.Site
instance) – Site to put this page on - login_required (bool) – Whether users must be logged in or not to view this page
- limit_menu_visibility (
VISIBILITY_ALL
orVISIBILITY_USERS
orVISIBILITY_ANONYMOUS
) – Limits visibility of this page in the menu - position (string) – Where to insert this node if parent is given, must be
'first-child'
or'last-child'
- overwrite_url (string) – Overwritten path for this page
- xframe_options (integer) – X Frame Option value for Clickjacking protection
- with_revision (bool) – Whether to create a revision for the new page.
-
cms.api.
create_title
(language, title, page, menu_title=None, slug=None, redirect=None, meta_description=None, parent=None, overwrite_url=None, with_revision=False)¶ Creates a
cms.models.titlemodel.Title
instance and returns it.Parameters: - language (string) – Language code for this page. Must be in
LANGUAGES
- title (string) – Title of the page
- page (
cms.models.pagemodel.Page
instance) – The page for which to create this title - menu_title (string) – Menu title for this page
- slug (string) – Slug for the page, by default uses a slugified version of title
- redirect (string) – URL redirect
- meta_description (string) – Description of this page for SEO
- parent (
cms.models.pagemodel.Page
instance) – Used for automated slug generation - overwrite_url (string) – Overwritten path for this page
- with_revision (bool) – Whether to create a revision for the new page.
- language (string) – Language code for this page. Must be in
-
cms.api.
add_plugin
(placeholder, plugin_type, language, position='last-child', target=None, **data)¶ Adds a plugin to a placeholder and returns it.
Parameters: - placeholder (
cms.models.placeholdermodel.Placeholder
instance) – Placeholder to add the plugin to - plugin_type (string or
cms.plugin_base.CMSPluginBase
sub-class, must be a valid plugin) – What type of plugin to add - language (string) – Language code for this plugin, must be in
LANGUAGES
- position (string) – Position to add this plugin to the placeholder, must be a valid django-mptt position
- target – Parent plugin. Must be plugin instance
- data (kwargs) – Data for the plugin type instance
- placeholder (
-
cms.api.
create_page_user
(created_by, user, can_add_page=True, can_change_page=True, can_delete_page=True, can_recover_page=True, can_add_pageuser=True, can_change_pageuser=True, can_delete_pageuser=True, can_add_pagepermission=True, can_change_pagepermission=True, can_delete_pagepermission=True, grant_all=False)¶ Creates a page user for the user provided and returns that page user.
Parameters: - created_by (
django.contrib.auth.models.User
instance) – The user that creates the page user - user (
django.contrib.auth.models.User
instance) – The user to create the page user from - can_* (bool) – Permissions to give the user
- grant_all (bool) – Grant all permissions to the user
- created_by (
-
cms.api.
assign_user_to_page
(page, user, grant_on=ACCESS_PAGE_AND_DESCENDANTS, can_add=False, can_change=False, can_delete=False, can_change_advanced_settings=False, can_publish=False, can_change_permissions=False, can_move_page=False, grant_all=False)¶ Assigns a user to a page and gives them some permissions. Returns the
cms.models.permissionmodels.PagePermission
object that gets created.Parameters: - page (
cms.models.pagemodel.Page
instance) – The page to assign the user to - user (
django.contrib.auth.models.User
instance) – The user to assign to the page - grant_on (
cms.models.permissionmodels.ACCESS_PAGE
,cms.models.permissionmodels.ACCESS_CHILDREN
,cms.models.permissionmodels.ACCESS_DESCENDANTS
orcms.models.permissionmodels.ACCESS_PAGE_AND_DESCENDANTS
) – Controls which pages are affected - can_* – Permissions to grant
- grant_all (bool) – Grant all permissions to the user
- page (
-
cms.api.
publish_page
(page, user, language)¶ Publishes a page.
Parameters: - page (
cms.models.pagemodel.Page
instance) – The page to publish - user (
django.contrib.auth.models.User
instance) – The user that performs this action - language (string) – The target language to publish to
- page (
-
cms.api.
publish_pages
(include_unpublished=False, language=None, site=None)¶ Publishes multiple pages defined by parameters.
Parameters: - include_unpublished (bool) – Set to
True
to publish all drafts, including unpublished ones; otherwise, only already published pages will be republished - language (string) – If given, only pages in this language will be published; otherwise, all languages will be published
- site (
django.contrib.sites.models.Site
instance) – Specify a site to publish pages for specified site only; if not specified pages from all sites are published
- include_unpublished (bool) – Set to
-
get_page_draft(page):
Returns the draft version of a page, regardless if the passed in page is a published version or a draft version.
Parameters: page ( cms.models.pagemodel.Page
instance) – The page to get the draft versionReturn page: draft version of the page
-
copy_plugins_to_language(page, source_language, target_language, only_empty=True):
Copy the plugins to another language in the same page for all the page placeholders.
By default plugins are copied only if placeholder has no plugin for the target language; use
only_empty=False
to change this.Warning
This function skips permissions checks
Parameters: - page (
cms.models.pagemodel.Page
instance) – the page to copy - source_language (string) – The source language code, must be in
LANGUAGES
- target_language (string) – The source language code, must be in
LANGUAGES
- only_empty (bool) – if False, plugin are copied even if plugins exists in the target language (on a placeholder basis).
Return int: number of copied plugins
- page (
Example workflows¶
Create a page called 'My Page
using the template 'my_template.html'
and
add a text plugin with the content 'hello world'
. This is done in English:
from cms.api import create_page, add_plugin
page = create_page('My Page', 'my_template.html', 'en')
placeholder = page.placeholders.get(slot='body')
add_plugin(placeholder, 'TextPlugin', 'en', body='hello world')
cms.constants¶
-
cms.constants.
TEMPLATE_INHERITANCE_MAGIC
¶ The token used to identify when a user selects “inherit” as template for a page.
-
cms.constants.
LEFT
¶ Used as a position indicator in the toolbar.
-
cms.constants.
RIGHT
¶ Used as a position indicator in the toolbar.
-
cms.constants.
REFRESH
¶ Constant used by the toolbar.
-
cms.constants.
EXPIRE_NOW
¶ Constant of 0 (zero) used for cache control headers
-
cms.constants.
MAX_EXPIRATION_TTL
¶ Constant of 31536000 or 365 days in seconds used for cache control headers
cms.plugin_base¶
-
class
cms.plugin_base.
CMSPluginBase
¶ Inherits
django.contrib.admin.options.ModelAdmin
.-
admin_preview
¶ Defaults to
False
, ifTrue
, displays a preview in the admin.
-
cache
¶ 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 capableget_cache_expiration()
.
-
change_form_template
¶ Custom template to use to render the form to edit this plugin.
-
form
¶ Custom form class to be used to edit this plugin.
-
get_plugin_urls
(instance)¶ Returns URL patterns for which the plugin wants to register views for. They are included under django CMS PageAdmin in the plugin path (e.g.:
/admin/cms/page/plugin/<plugin-name>/
in the default case). Useful if your plugin needs to asynchronously talk to the admin.
-
model
¶ Is the
CMSPlugin
model we created earlier. If you don’t need model because you just want to display some template logic, useCMSPlugin
fromcms.models
as the model instead.
-
module
¶ Will group the plugin in the plugin editor. If module is
None
, plugin is grouped “Generic” group.
-
name
¶ Will be displayed in the plugin editor.
-
render_plugin
¶ If set to
False
, this plugin will not be rendered at all.
-
render_template
¶ Will be rendered with the context returned by the render function.
-
text_enabled
¶ Whether this plugin can be used in text plugins or not.
-
icon_alt
(instance)¶ Returns the alt text for the icon used in text plugins, see
icon_src()
.
-
icon_src
(instance)¶ Returns the URL to the icon to be used for the given instance when that instance is used inside a text plugin.
-
get_cache_expiration
(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
andMAX_EXPIRATION_TTL
.An integer value of
0
(zero) orEXPIRE_NOW
effectively means “do not cache”. Negative values will be treated asEXPIRE_NOW
. Values exceeding the valueMAX_EXPIRATION_TTL
will be set to that value.Negative
timedelta
values or those greater thanMAX_EXPIRATION_TTL
will also be ranged in the same manner.Similarly,
datetime
values earlier than now will be treated asEXPIRE_NOW
. Values greater thanMAX_EXPIRATION_TTL
seconds in the future will be treated asMAX_EXPIRATION_TTL
seconds in the future.Parameters: - request – Relevant
HTTPRequest
instance. - instance – The
CMSPlugin
instance that is being rendered.
Return type: None
ordatetime
orint
- request – Relevant
-
render
(context, instance, placeholder)¶ This method returns the context to be used to render the template specified in
render_template
.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
-
cms.toolbar¶
All methods taking a side
argument expect either
cms.constants.LEFT
or cms.constants.RIGHT
for that
argument.
Methods accepting the position
argument can insert items at a specific
position. This can be either None
to insert at the end, an integer
index at which to insert the item, a cms.toolbar.items.ItemSearchResult
to insert
it before that search result or a cms.toolbar.items.BaseItem
instance to insert
it before that item.
cms.toolbar.toolbar¶
-
class
cms.toolbar.toolbar.
CMSToolbar
¶ The toolbar class providing a Python API to manipulate the toolbar. Note that some internal attributes are not documented here.
All methods taking a
position
argument expect eithercms.constants.LEFT
orcms.constants.RIGHT
for that argument.This class inherits
cms.toolbar.items.ToolbarMixin
, so please check that reference as well.-
is_staff
¶ Whether the current user is a staff user or not.
-
edit_mode
¶ Whether the toolbar is in edit mode.
-
build_mode
¶ Whether the toolbar is in build mode.
-
show_toolbar
¶ Whether the toolbar should be shown or not.
-
csrf_token
¶ The CSRF token of this request
-
toolbar_language
¶ Language used by the toolbar.
-
watch_models
¶ A list of model this toolbar works on; used for redirection after editing (Detecting URL changes).
-
add_item
(item, position=None)¶ Low level API to add items.
Adds an item, which must be an instance of
cms.toolbar.items.BaseItem
, to the toolbar.This method should only be used for custom item classes, as all built-in item classes have higher level APIs.
Read above for information on
position
.
If a menu with
key
already exists, this method will return that menu. Otherwise it will create a menu for thatkey
with the givenverbose_name
onside
atposition
and return it.
Adds a button to the toolbar.
extra_wrapper_classes
will be applied to the wrappingdiv
whileextra_classes
are applied to the<a>
.
Adds an (empty) button list to the toolbar and returns it. See
cms.toolbar.items.ButtonList
for further information.
-
cms.toolbar.items¶
Important
Overlay and sideframe
Then django CMS sideframe has been replaced with an overlay mechanism. The API still refers
to the sideframe
, because it is invoked in the same way, and what has changed is merely the
behaviour in the user’s browser.
In other words, sideframe and the overlay refer to different versions of the same thing.
-
class
cms.toolbar.items.
ItemSearchResult
¶ Used for the find APIs in
ToolbarMixin
. Supports addition and subtraction of numbers. Can be cast to an integer.-
item
¶ The item found.
-
index
¶ The index of the item.
-
-
class
cms.toolbar.items.
ToolbarMixin
¶ Provides APIs shared between
cms.toolbar.toolbar.CMSToolbar
andMenu
.The
active
anddisabled
flags taken by all methods of this class specify the state of the item added.extra_classes
should be eitherNone
or a list of class names as strings.-
REFRESH_PAGE
¶ Constant to be used with
on_close
to refresh the current page when the frame is closed.
-
LEFT
¶ Constant to be used with
side
.
-
RIGHT
¶ Constant to be used with
side
.
-
get_item_count
()¶ Returns the number of items in the toolbar or menu.
-
add_item
(item, position=None)¶ Low level API to add items, adds the
item
to the toolbar or menu and makes it searchable.item
must be an instance ofBaseItem
. Read above for information about theposition
argument.
-
remove_item
(item)¶ Removes
item
from the toolbar or menu. If the item can’t be found, aKeyError
is raised.
-
find_items
(item_type, **attributes)¶ Returns a list of
ItemSearchResult
objects matching all items ofitem_type
, which must be a sub-class ofBaseItem
, where all attributes inattributes
match.
-
find_first
(item_type, **attributes)¶ Returns the first
ItemSearchResult
that matches the search orNone
. The search strategy is the same as infind_items()
. Since positional insertion allowsNone
, it’s safe to use the return value of this method as the position argument to insertion APIs.
-
add_sideframe_item
(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=LEFT, position=None)¶ Adds an item which opens
url
in the sideframe and returns it.on_close
can be set toNone
to do nothing when the sideframe closes,REFRESH_PAGE
to refresh the page when it closes or a URL to open once it closes.
-
add_modal_item
(name, url, active=False, disabled=False, extra_classes=None, on_close=REFRESH_PAGE, side=LEFT, position=None)¶ The same as
add_sideframe_item()
, but opens theurl
in a modal dialog instead of the sideframe.on_close
can be set toNone
to do nothing when the side modal closes,REFRESH_PAGE
to refresh the page when it closes or a URL to open once it closes.Note: The default value for
on_close
is different inadd_sideframe_item()
then inadd_modal_item()
-
add_link_item
(name, url, active=False, disabled=False, extra_classes=None, side=LEFT, position=None)¶ Adds an item that simply opens
url
and returns it.
-
add_ajax_item
(name, action, active=False, disabled=False, extra_classes=None, data=None, question=None, side=LEFT, position=None)¶ Adds an item which sends a POST request to
action
withdata
.data
should beNone
or a dictionary, the CSRF token will automatically be added to it.If
question
is set to a string, it will be asked before the request is sent to confirm the user wants to complete this action.
-
-
class
cms.toolbar.items.
BaseItem
(position)¶ Base item class.
-
template
¶ Must be set by sub-classes and point to a Django template
-
side
¶ Must be either
cms.constants.LEFT
orcms.constants.RIGHT
.
-
render
()¶ Renders the item and returns it as a string. By default calls
get_context()
and renderstemplate
with the context returned.
-
get_context
()¶ Returns the context (as dictionary) for this item.
-
-
class
cms.toolbar.items.
Menu
(name, csrf_token, side=LEFT, position=None)¶ The menu item class. Inherits
ToolbarMixin
and provides the APIs documented on it.The
csrf_token
must be set as this class provides high level APIs to add items to it.The same as
cms.toolbar.toolbar.CMSToolbar.get_or_create_menu()
but adds the menu as a sub menu and returns aSubMenu
.
-
add_break
(identifier=None, position=None)¶ Adds a visual break in the menu, useful for grouping items, and returns it.
identifier
may be used to make this item searchable.
-
class
cms.toolbar.items.
SubMenu
(name, csrf_token, side=LEFT, position=None)¶ Same as
Menu
but without theMenu.get_or_create_menu()
method.
-
class
cms.toolbar.items.
LinkItem
(name, url, active=False, disabled=False, extra_classes=None, side=LEFT)¶ Simple link item.
-
class
cms.toolbar.items.
SideframeItem
(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=LEFT)¶ Item that opens
url
in sideframe.
-
class
cms.toolbar.items.
AjaxItem
(name, action, csrf_token, data=None, active=False, disabled=False, extra_classes=None, question=None, side=LEFT)¶ An item which posts
data
toaction
.
-
class
cms.toolbar.items.
ModalItem
(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=LEFT)¶ Item that opens
url
in the modal.
-
class
cms.toolbar.items.
Break
(identifier=None)¶ A visual break for menus.
identifier
may be provided to make this item searchable. Since breaks can only be within menus, they have noside
attribute.
-
class
cms.toolbar.items.
ButtonList
(identifier=None, extra_classes=None, side=LEFT)¶ A list of one or more buttons.
The
identifier
may be provided to make this item searchable.Adds a
Button
to the list of buttons and returns it.
-
class
cms.toolbar.items.
Button
(name, url, active=False, disabled=False, extra_classes=None)¶ A button to be used with
ButtonList
. Opensurl
when selected.