ru
Language: en

3.7.x
Documentation version: 3.9

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_visibility_in_menu keyword argument to create_page(). Does not limit menu visibility.

cms.api.VISIBILITY_USERS¶: Used for the limit_visibility_in_menu keyword argument to create_page(). Limits menu visibility to authenticated users.

cms.api.VISIBILITY_ANONYMOUS¶: Used for the limit_visibility_in_menu keyword argument to create_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 a cms.models.Title instance for the specified language.

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
publication_date (datetime.datetime) – Date to publish this page
publication_end_date (datetime.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 (str) – Reverse ID of this page (for template tags)
navigation_extenders (str) – 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_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_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 (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.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, 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

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

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 or cms.models.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 (str) – The target language to publish to

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 (str) – 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 (str) – The source language code, must be in LANGUAGES
target_language (str) – 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

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

_menus¶: 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)

get_menus(page, language, **kwargs)¶

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

Reference

Command Line Interface

Django CMS - content management system 3.9

Contents

Extra

API References¶

cms.api¶

Functions and constants¶

Example workflows¶

cms.constants¶

cms.app_base¶