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)¶ Creates a
cms.models.Page
instance and returns it. Also creates acms.models.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.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 (int) – X Frame Option value for Clickjacking protection
-
cms.api.
create_title
(language, title, page, menu_title=None, slug=None, redirect=None, meta_description=None, parent=None, overwrite_url=None)¶ Creates a
cms.models.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.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.Page
instance) – Used for automated slug generation - overwrite_url (string) – Overwritten path for this 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-treebeard
pos
value fortreebeard.models.Node.add_sibling()
- target – Parent plugin. Must be plugin instance
- data – 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.PagePermission
object that gets created.Parameters: - page (
cms.models.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.ACCESS_PAGE
,cms.models.ACCESS_CHILDREN
,cms.models.ACCESS_DESCENDANTS
orcms.models.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.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.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.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.app_base¶
-
class
cms.app_base.
CMSApp
¶ -
_urls
¶ list of urlconfs: example:
_urls = ["myapp.urls"]
list of menu classes: example:
_menus = [MyAppMenu]
-
name = None
name of the apphook (required)
-
app_name = None
name of the app, this enables Django namespaces support (optional)
-
app_config = None
configuration model (optional)
-
permissions = True
if set to true, apphook inherits permissions from the current page
-
exclude_permissions = []
list of application names to exclude from inheriting CMS permissions
-
get_configs
()¶ Returns all the apphook configuration instances.
-
get_config
(namespace)¶ Returns the apphook configuration instance linked to the given namespace
-
get_config_add_url
()¶ Returns the url to add a new apphook configuration instance (usually the model admin add view)
New in version 3.3:
CMSApp.get_menus
accepts page, language and generic keyword arguments: you can customize this function to return different list of menu classes according to the given arguments.Returns the menus for the apphook instance, selected according to the given arguments.
By default it returns the menus assigned to
_menus
If no page and language are provided, this method must return all the menus used by this apphook. Example:
if page and page.reverse_id == 'page1': return [Menu1] elif page and page.reverse_id == 'page2': return [Menu2] else: return [Menu1, Menu2]
param page: page the apphook is attached to param language: current site language return: list of menu classes
-
get_urls
(page, language, **kwargs)¶ New in version 3.3.
Returns the URL configurations for the apphook instance, selected according to the given arguments.
By default it returns the urls assigned to
_urls
This method must return a non empty list of URL configurations, even if no arguments are passed.
Parameters: - page – page the apphook is attached to
- language – current site language
Returns: list of strings representing URL configurations
-