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.

Note

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.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=None, site=None, login_required=False, limit_visibility_in_menu=None, position='last-child', overwrite_url=None, xframe_options=0)#

Creates a cms.models.Page instance and returns it. Also creates a cms.models.Title instance for the specified language.

Warning

Since version 4 the parameters published, publication_date, and publication_end_date do not change the behaviour of this function. If they are supplied a warning is raised.

Parameters:

  • title (str) – Title of the page

  • template (str) – Template to use for this page. Must be in CMS_TEMPLATES

  • language (str) – Language code for this page. Must be in LANGUAGES

  • menu_title (str) – Menu title for this page

  • slug (str) – Slug for the page, by default uses a slugified version of title

  • apphook (str or cms.app_base.CMSApp sub-class) – Application to hook on this page, must be a valid apphook

  • apphook_namespace (str) – Name of the apphook namespace

  • redirect (str) – URL redirect

  • meta_description (str) – Description of this page for SEO

  • created_by (str of django.contrib.auth.models.User instance) – User that is creating this page

  • parent (cms.models.Page instance) – Parent page of 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 (str) – Reverse ID of this page (for template tags)

  • navigation_extenders (str) – Menu to attach to this page. Must be a valid menu

  • 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_visibility_in_menu (VISIBILITY_ALL or VISIBILITY_USERS or VISIBILITY_ANONYMOUS) – Limits visibility of this page in the menu

  • position (str) – Where to insert this node if parent is given, must be 'first-child' or 'last-child'

  • overwrite_url (str) – Overwritten path for this page

  • xframe_options (int) – X Frame Option value for Clickjacking protection

  • page_title (str) – Overridden page title for HTML title tag

cms.api.create_page_content(language, title, page, menu_title=None, slug=None, redirect=None, meta_description=None, parent=None, overwrite_url=None, page_title=None, path=None, created_by='python-api', soft_root=False, in_navigation=False, template='INHERIT', limit_visibility_in_menu=None, xframe_options=0)#

Creates a cms.models.PageContent instance and returns it.

parent is only used if slug=None.

Parameters:

  • language (str) – Language code for this page. Must be in LANGUAGES

  • title (str) – Title of the page

  • page (cms.models.Page instance) – The page for which to create this title

  • menu_title (str) – Menu title for this page

  • slug (str) – Slug for the page, by default uses a slugified version of title

  • redirect (str) – URL redirect

  • meta_description (str) – Description of this page for SEO

  • parent (cms.models.Page instance) – Used for automated slug generation

  • overwrite_url (str) – Overwritten path for this page

  • page_title (str) – Overridden page title for HTML title tag

cms.api.create_title(language, title, page, menu_title=None, slug=None, redirect=None, meta_description=None, parent=None, overwrite_url=None, page_title=None, path=None, created_by='python-api', soft_root=False, in_navigation=False, template='INHERIT', limit_visibility_in_menu=None, xframe_options=0)#

Warning

create_title has been renamed to create_page_content as of django CMS version 4.

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 (str or cms.plugin_base.CMSPluginBase sub-class, must be a valid plugin) – What type of plugin to add

  • language (str) – Language code for this plugin, must be in LANGUAGES

  • position (str) – Position to add this plugin to the placeholder. Allowed positions are "last-child" (default), "first-child", "left", "right".

  • target – Parent plugin. Must be plugin instance

  • data – Data for the plugin type instance

cms.api.create_page_user(created_by, user, can_add_page=True, can_view_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:
cms.api.assign_user_to_page(page, user, grant_on=5, can_add=False, can_change=False, can_delete=False, can_change_advanced_settings=False, can_publish=None, can_change_permissions=False, can_move_page=False, can_recover_page=True, can_view=False, grant_all=False, global_permission=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,) – Controls which pages are affected

cms.models.ACCESS_DESCENDANTS or cms.models.ACCESS_PAGE_AND_DESCENDANTS :param can_*: Permissions to grant :param bool grant_all: Grant all permissions to the user

cms.api.publish_page(page, user, language)#

Warning

Publishing pages has been removed from django CMS core in version 4 onward.

For publishing functionality see djangocms-versioning:

cms.api.publish_pages(include_unpublished=False, language=None, site=None)#

Warning

Publishing pages has been removed from django CMS core in version 4 onward.

For publishing functionality see djangocms-versioning:

cms.api.get_page_draft(page)#

Warning

The concept of draft pages has been removed from django CMS core in version 4 onward.

For draft functionality see djangocms-versioning:

cms.api.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.

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

cms.api.can_change_page(request)#

Check whether a user has the permission to change the page.

This will work across all permission-related setting, with a unified interface to permission checking.

Parameters:

request (HttpRequest instance) – The request object from which the user will be taken.

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.VISIBILITY_ALL = None#

Used for the limit_visibility_in_menu keyword argument to :func: create_page.Does not limit menu visibility.

cms.constants.VISIBILITY_USERS = 1#

Used for the limit_visibility_in_menu keyword argument to :func: create_page. Limits menu visibility to authenticated users.

cms.constants.VISIBILITY_ANONYMOUS = 2#

Used for the limit_visibility_in_menu keyword argument to :func: create_page. Limits menu visibility to anonymous(not authenticated) users.

cms.constants.TEMPLATE_INHERITANCE_MAGIC = 'INHERIT'#

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: On the left side.

cms.constants.RIGHT#

Used as a position indicator in the toolbar: On the right side.

cms.constants.EXPIRE_NOW = 0#

Used for cache control headers: 0 seconds, i.e. now.

cms.constants.MAX_EXPIRATION_TTL = 31536000#

Used for cache control headers: 365 * 24 * 3600 seconds, i.e. one year. HTTP specification says max caching should only be up to one year.