4. API References

4.1. cms.api

Python APIs for creating CMS contents. 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 modules do 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.

4.1.1. Functions and constants

cms.api.VISIBILITY_ALL

Used for the limit_menu_visibility keyword argument to create_page(). Does not limit menu visibility.

cms.api.VISIBILITY_USERS

Used for the limit_menu_visibility keyword argument to create_page(). Limits menu visibility to authenticated users.

cms.api.VISIBILITY_STAFF

Used for the limit_menu_visibility keyword argument to create_page(). Limits menu visibility to staff users.

cms.api.create_page(title, template, language, menu_title=None, slug=None, apphook=None, redirect=None, meta_description=None, meta_keywords=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")

Creates a cms.models.pagemodel.Page instance and returns it. Also creates a cms.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 :setting:`CMS_TEMPLATES`
• language (string) – Language code for this page. Must be in :setting:`django: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 subclass) – Application to hook on this page, must be a valid apphook
• redirect (string) – URL redirect (only applicable if :setting:`CMS_REDIRECTS` is True)
• meta_description (string) – Description of this page for SEO
• meta_keywords (string) – Keywords for this page for SEO
• created_by (string of django.contrib.auth.models.User instance) – User that creates 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 (boolean) – Whether this page should be in the navigation or not
• soft_root (boolean) – Whether this page is a softroot 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 (boolean) – Whether this page should be published or not
• site (django.contrib.sites.models.Site instance) – Site to put this page on
• login_required (boolean) – Whether users must be logged in or not to view this page
• limit_menu_visibility (VISIBILITY_ALL or VISIBILITY_USERS or VISIBILITY_STAFF) – 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

cms.api.create_title(language, title, page, menu_title=None, slug=None, apphook=None, redirect=None, meta_description=None, meta_keywords=None, parent=None)

Creates a cms.models.titlemodel.Title instance and returns it.

Parameters:

• language (string) – Language code for this page. Must be in :setting:`django: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
• apphook (string or cms.app_base.CMSApp subclass) – Application to hook on this page, must be a valid apphook
• redirect (string) – URL redirect (only applicable if :setting:`CMS_REDIRECTS` is True)
• meta_description (string) – Description of this page for SEO
• meta_keywords (string) – Keywords for this page for SEO
• parent (cms.models.pagemodel.Page instance) – Used for automated slug generation
• overwrite_url (string) – Overwritten path for this page

cms.api.add_plugin(placeholder, plugin_type, language, position='last-child', **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 subclass, must be a valid plugin) – What type of plugin to add
• language (string) – Language code for this plugin, must be in :setting:`django:LANGUAGES`
• position (string) – Position to add this plugin to the placeholder, must be a valid django-mptt position
• data (kwargs) – 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_* (boolean) – Permissions to give the user
• grant_all (boolean) – 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, can_moderate=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.moderatormodels.ACCESS_PAGE, cms.models.moderatormodels.ACCESS_CHILDREN, cms.models.moderatormodels.ACCESS_DESCENDANTS or cms.models.moderatormodels.ACCESS_PAGE_AND_DESCENDANTS) – Controls which pages are affected
• can_* – Permissions to grant
• grant_all (boolean) – Grant all permissions to the user

cms.api.publish_page(page, user, approve=False)

Publishes a page and optionally approves that publication.

Parameters:

• page (cms.models.pagemodel.Page instance) – The page to publish
• user (django.contrib.auth.models.User instance) – The user that performs this action
• approve (boolean) – Whether to approve the publication or not

cms.api.approve_page(page, user)

Approves a page.

Parameters:

• page (cms.models.pagemodel.Page instance) – The page to approve
• user (django.contrib.auth.models.User instance) – The user that performs this action

4.1.2. 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')

4.2. cms.plugin_base

class cms.plugin_base.CMSPluginBase

Inherits django.contrib.admin.options.ModelAdmin.

admin_preview

Defaults to True, if False no preview is done in the admin.

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.

model

Is the CMSPlugin model we created earlier. If you don’t need model because you just want to display some template logic, use CMSPlugin from cms.models as the model instead.

module

Will be 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.

render(context, instance, placeholder)

This method returns the context to be used to render the template specified in render_template.

Parameters:

• context – Current template context.
• instance – Plugin instance that is being rendered.
• placeholder – Name of the placeholder the plugin is in.

Return type:

dict

4.3. menus.base

class menus.base.NavigationNode(title, url, id[, parent_id=None][, parent_namespace=None][, attr=None][, visible=True])

A navigation node in a menu tree.

Parameters:

• title (string) – The title to display this menu item with.
• url (string) – The URL associated with this menu item.
• id – Unique (for the current tree) ID of this item.
• parent_id – Optional, ID of the parent item.
• parent_namespace – Optional, namespace of the parent.
• attr (dict) – Optional, dictionary of additional information to store on this node.
• visible (bool) – Optional, defaults to True, whether this item is visible or not.

get_descendants()

Returns a list of all children beneath the current menu item.

get_ancestors()

Returns a list of all parent items, excluding the current menu item.

get_absolute_url()

Utility method to return the URL associated with this menu item, primarily to follow naming convention asserted by Django.

get_menu_title()

Utility method to return the associated title, using the same naming convention used by cms.models.pagemodel.Page.