APIs

APIs

Python APIs for creating and manipulating django CMS content.

These APIs are provided in order to provide a stable abstraction layer between internal django CMS functions and external code.

The APIs also make access to the functionality simpler, by providing more intuitive interface, with better input-checking.

Warning

None of the functions in this module make any security or permissions checks. They verify their input values for validity and make some basic sanity checks, but permissions checks should be implemented manually before calling any of these functions.

Warning

Due to potential circular dependency issues, we recommend that you import the APIs in the functions that use them. Use:

def my_function():
    from cms.api import api_function
    api_function(...)

rather than:

from cms.api import api_function
def my_function():
    api_function(...)

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.Page instance and returns it. Also creates a cms.models.Title instance for the specified language.

Parameters:

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`, `VISIBILITY_USERS` or `VISIBILITY_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 with_revision (bool) – Whether to create a revision for the new page.

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, VISIBILITY_USERS or VISIBILITY_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
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.Title instance and returns it.

Parameters:

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 with_revision (bool) – Whether to create a revision for the new page.

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
with_revision (bool) – Whether to create a revision for the new page.

cms.api.``add_plugin(placeholder, plugin_type, language, position=’last-child’, target=None, \*data*)

Adds a plugin to a placeholder and returns it.

Parameters:

Parameters:	placeholder (`cms.models.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 for `treebeard.models.Node.add_sibling()` target – Parent plugin. Must be plugin instance data – Data for the plugin type instance

placeholder (cms.models.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 for treebeard.models.Node.add_sibling()
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_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:	createdby (`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

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 granton (`ACCESS_PAGE`, `ACCESS_CHILDREN`, `ACCESS_DESCENDANTS` or `ACCESS_PAGE_AND_DESCENDANTS`) – Controls which pages are affected can* – Permissions to grant grant_all (bool) – Grant all permissions to the user

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

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

Publishes multiple pages defined by parameters.

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

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 version
Return 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

Examples of usage can be found in: