The Toolbar

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.

cms.toolbar.toolbar

class cms.toolbar.toolbar.CMSToolbar

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.

is_staff

Whether the current user is a staff user or not.

edit_mode_active

Whether the toolbar is in edit mode.

build_mode

Whether the toolbar is in build mode.

show_toolbar

Whether the toolbar should be shown or not.

csrf_token

The CSRF token of this request

toolbar_language

Language used by the toolbar.

watch_models

A list of models this toolbar works on; used for redirection after editing (Detecting URL changes).

add_item(item, position=None)

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 built-in item classes have higher level APIs.

Read above for information on position.

remove_item(item)

Removes an item from the toolbar or raises a KeyError if it’s not found.

get_or_create_menu(key. verbose_name, side=LEFT, position=None)

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.

get_menu(self, key, verbose_name=None, side=LEFT, position=None)

If a menu with key already exists, this method will return that menu.

add_button(name, url, active=False, disabled=False, extra_classes=None, extra_wrapper_classes=None, side=LEFT, position=None)

Adds a button to the toolbar. extra_wrapper_classes will be applied to the wrapping div while extra_classes are applied to the <a>.

add_button_list(extra_classes=None, side=LEFT, position=None)

Adds an (empty) button list to the toolbar and returns it. See cms.toolbar.items.ButtonList for further information.

cms.toolbar.items

Important

Overlay and sideframe

Then django CMS sideframe has been replaced with an overlay mechanism. The API still refers to the sideframe, because it is invoked in the same way, and what has changed is merely the behaviour in the user’s browser.

In other words, sideframe and the overlay refer to different versions of the same thing.

class cms.toolbar.items.ItemSearchResult

Used for the find APIs in ToolbarMixin. Supports addition and subtraction of numbers. Can be cast to an integer.

item

The item found.

index

The index of the item.

class cms.toolbar.items.ToolbarMixin

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.

REFRESH_PAGE

Constant to be used with on_close to refresh the current page when the frame is closed.

LEFT

Constant to be used with side.

RIGHT

Constant to be used with side.

get_item_count()

Returns the number of items in the toolbar or menu.

get_alphabetical_insert_position(self, new_menu_name, item_type, default=0)

add_item(item, position=None)

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.

remove_item(item)

Removes item from the toolbar or menu. If the item can’t be found, a KeyError is raised.

find_items(item_type, **attributes)

Returns a list of ItemSearchResult objects matching all items of item_type, which must be a sub-class of BaseItem, where all attributes in attributes match.

find_first(item_type, **attributes)

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.

add_sideframe_item(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=LEFT, position=None)

Adds an item which opens url in the sideframe and returns it.

on_close can be set to None to do nothing when the sideframe closes, REFRESH_PAGE to refresh the page when it closes or a URL to open once it closes.

add_modal_item(name, url, active=False, disabled=False, extra_classes=None, on_close=REFRESH_PAGE, side=LEFT, position=None)

The same as add_sideframe_item(), but opens the url in a modal dialog instead of the sideframe.

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

add_link_item(name, url, active=False, disabled=False, extra_classes=None, side=LEFT, position=None)

Adds an item that simply opens url and returns it.

add_ajax_item(name, action, active=False, disabled=False, extra_classes=None, data=None, question=None, side=LEFT, position=None)

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.

class cms.toolbar.items.BaseItem(position)

Base item class.

template

Must be set by sub-classes and point to a Django template

side

Must be either cms.constants.LEFT or cms.constants.RIGHT.

render()

Renders the item and returns it as a string. By default calls get_context() and renders template with the context returned.

get_context()

Returns the context (as dictionary) for this item.

class cms.toolbar.items.Menu(name, csrf_token, side=LEFT, position=None)

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.

get_or_create_menu(key, verbose_name, side=LEFT, position=None)

The same as cms.toolbar.toolbar.CMSToolbar.get_or_create_menu() but adds the menu as a sub menu and returns a SubMenu.

add_break(identifier=None, position=None)

Adds a visual break in the menu, useful for grouping items, and returns it. identifier may be used to make this item searchable.

class cms.toolbar.items.SubMenu(name, csrf_token, side=LEFT, position=None)

Same as Menu but without the Menu.get_or_create_menu() method.

class cms.toolbar.items.LinkItem(name, url, active=False, disabled=False, extra_classes=None, side=LEFT)

Simple link item.

class cms.toolbar.items.SideframeItem(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=LEFT)

Item that opens url in sideframe.

class cms.toolbar.items.AjaxItem(name, action, csrf_token, data=None, active=False, disabled=False, extra_classes=None, question=None, side=LEFT)

An item which posts data to action.

class cms.toolbar.items.ModalItem(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=LEFT)

Item that opens url in the modal.

class cms.toolbar.items.Break(identifier=None)

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.

class cms.toolbar.items.ButtonList(identifier=None, extra_classes=None, side=LEFT)

A list of one or more buttons.

The identifier may be provided to make this item searchable.

add_item(item)

Adds item to the list of buttons. item must be an instance of Button.

add_button(name, url, active=False, disabled=False, extra_classes=None)

Adds a Button to the list of buttons and returns it.

class cms.toolbar.items.Button(name, url, active=False, disabled=False, extra_classes=None)

A button to be used with ButtonList. Opens url when selected.

class cms.toolbar_pool.ToolbarPool

register(self, toolbar)

Register this toolbar.

class cms.extensions.toolbar.ExtensionToolbar

get_page_extension_admin()

_setup_extension_toolbar()

get_title_extension_admin()