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.
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(...)
Used for the limit_menu_visibility keyword argument to create_page(). Does not limit menu visibility.
Used for the limit_menu_visibility keyword argument to create_page(). Limits menu visibility to authenticated users.
Used for the limit_menu_visibility keyword argument to create_page(). Limits menu visibility to staff users.
Creates a cms.models.pagemodel.Page instance and returns it. Also creates a cms.models.titlemodel.Title instance for the specified language.
Parameters: |
|
---|
Creates a cms.models.titlemodel.Title instance and returns it.
Parameters: |
|
---|
Adds a plugin to a placeholder and returns it.
Parameters: |
|
---|
Creates a page user for the user provided and returns that page user.
Parameters: |
|
---|
Assigns a user to a page and gives them some permissions. Returns the cms.models.permissionmodels.PagePermission object that gets created.
Parameters: |
|
---|
Publishes a page.
Parameters: |
|
---|
Publishes multiple pages defined by parameters.
Parameters: |
|
---|
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.pagemodel.Page instance) – The page to get the draft version |
---|---|
Return page: | draft version of the page |
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: |
|
---|---|
Return int: | number of copied plugins |
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')
The token used to identify when a user selects “inherit” as template for a page.
Used as a position indicator in the toolbar.
Used as a position indicator in the toolbar.
Constant used by the toolbar.
Inherits django.contrib.admin.options.ModelAdmin.
Defaults to False, if True there will be a preview in the admin.
Custom template to use to render the form to edit this plugin.
Custom form class to be used to edit this plugin.
Returns URL patterns for which the plugin wants to register views for. They are included under django CMS PageAdmin in the plugin path (e.g.: /admin/cms/page/plugin/<plugin-name>/ in the default case). Useful if your plugin needs to asynchronously talk to the admin.
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.
Will group the plugin in the plugin editor. If module is None, plugin is grouped “Generic” group.
Will be displayed in the plugin editor.
If set to False, this plugin will not be rendered at all.
Will be rendered with the context returned by the render function.
Whether this plugin can be used in text plugins or not.
Returns the alt text for the icon used in text plugins, see icon_src().
Returns the url to the icon to be used for the given instance when that instance is used inside a text plugin.
This method returns the context to be used to render the template specified in render_template.
Parameters: |
|
---|---|
Return type: | dict |
All methods taking a side argument expect either cms.constants.LEFT or cms.constants.RIGHT for that argument.
Methods accepting the position argument can insert items at a specific position. This can be either None to insert at the end, an integer index at which to insert the item, a cms.toolbar.items.ItemSearchResult to insert it before that search result or a cms.toolbar.items.BaseItem instance to insert it before that item.
The toolbar class providing a Python API to manipulate the toolbar. Note that some internal attributes are not documented here.
All methods taking a position argument expect either cms.constants.LEFT or cms.constants.RIGHT for that argument.
This class inherits cms.toolbar.items.ToolbarMixin, so please check that reference as well.
Whether the current user is a staff user or not.
Whether the toolbar is in edit mode.
Whether the toolbar is in build mode.
Whether the toolbar should be shown or not.
The CSRF token of this request
Language used by the toolbar.
A list of model this toolbar works on; used for redirections after editing (Detecting url changes).
Low level API to add items.
Adds an item, which must be an instance of cms.toolbar.items.BaseItem, to the toolbar.
This method should only be used for custom item classes, as all builtin item classes have higher level APIs.
Read above for information on position.
Removes an item from the toolbar or raises a KeyError if it’s not found.
If a menu with key already exists, this method will return that menu. Otherwise it will create a menu for that key with the given verbose_name on side at position and return it.
Adds a button to the toolbar. extra_wrapper_classes will be applied to the wrapping div while extra_classes are applied to the <a>.
Adds an (empty) button list to the toolbar and returns it. See cms.toolbar.items.ButtonList for further information.
Used for the find APIs in ToolbarMixin. Supports addition and subtraction of numbers. Can be cast to an integer.
The item found.
The index of the item.
Provides APIs shared between cms.toolbar.toolbar.CMSToolbar and Menu.
The active and disabled flags taken by all methods of this class specify the state of the item added.
extra_classes should be either None or a list of class names as strings.
Constant to be used with on_close to refresh the current page when the frame is closed.
Constant to be used with side.
Constant to be used with side.
Returns the number of items in the toolbar or menu.
Low level API to add items, adds the item to the toolbar or menu and makes it searchable. item must be an instance of BaseItem. Read above for information about the position argument.
Removes item from the toolbar or menu. If the item can’t be found, a KeyError is raised.
Returns a list of ItemSearchResult objects matching all items of item_type, which must be a subclass of BaseItem, where all attributes in attributes match.
Returns the first ItemSearchResult that matches the search or None. The search strategy is the same as in find_items(). Since positional insertion allows None, it’s safe to use the return value of this method as the position argument to insertion APIs.
Adds an item which opens url in the side frame and returns it.
on_close can be set to None to do nothing when the side frame closes, REFRESH_PAGE to refresh the page when it closes or a URL to open once it closes.
The same as add_sideframe_item(), but opens the url in a modal dialog instead of the side frame.
on_close can be set to None to do nothing when the side modal closes, REFRESH_PAGE to refresh the page when it closes or a URL to open once it closes.
Note: The default value for on_close is different in add_sideframe_item() then in add_modal_item()
Adds an item that simply opens url and returns it.
Adds an item which sends a POST request to action with data. data should be None or a dictionary, the CSRF token will automatically be added to it.
If question is set to a string, it will be asked before the request is sent to confirm the user wants to complete this action.
Base item class.
Must be set by subclasses and point to a Django template
Must be either cms.constants.LEFT or cms.constants.RIGHT.
Renders the item and returns it as a string. By default calls get_context() and renders template with the context returned.
Returns the context (as dictionary) for this item.
The menu item class. Inherits ToolbarMixin and provides the APIs documented on it.
The csrf_token must be set as this class provides high level APIs to add items to it.
The same as cms.toolbar.toolbar.CMSToolbar.get_or_create_menu() but adds the menu as a sub menu and returns a SubMenu.
Adds a visual break in the menu, useful for grouping items, and returns it. identifier may be used to make this item searchable.
Same as Menu but without the Menu.get_or_create_menu() method.
Simple link item.
Item that opens url in side frame.
An item which posts data to action.
Item that opens url in the modal.
A visual break for menus. identifier may be provided to make this item searchable. Since breaks can only be within menus, they have no side attribute.
A list of one or more buttons.
The identifier may be provided to make this item searchable.
Adds a Button to the list of buttons and returns it.
A button to be used with ButtonList. Opens url when clicked.