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

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.

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.

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

Adds a plugin to a placeholder and returns it.

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.

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.permissionmodels.PagePermission object that gets created.

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

Publishes a page and optionally approves that publication.

cms.api.``approve_page(page, user)

Approves a page.

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

cms.constants.``TEMPLATE_INHERITANCE_MAGIC

The token used to identify when a user selects “inherit” as template for a page.

4.3. cms.plugin_base

class cms.plugin_base.``CMSPluginBase

Inherits django.contrib.admin.options.ModelAdmin.

• admin_preview

  Defaults to False, if True there will be a preview 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 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.4. 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.

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