The Toolbar¶

Classes and methods¶

Common parameters (key, verbose_name, position, on_close, disabled, active) and options are described at the end of this document.

class cms.toolbar.toolbar.CMSToolbar¶

The toolbar is an instance of the cms.toolbar.toolbar.CMSToolbar class. This should not be confused with the CMSToolbar, the base class for toolbar modifier classes in other applications, that add items to and otherwise manipulates the toolbar.

It is strongly recommended that you only interact with the toolbar in your own code via:

• the APIs documented here

• toolbar modifier classes based on cms.toolbar_base.CMSToolbar

You will notice that some of the methods documented here do not include some arguments present in the code. This is the public reference documentation, while the code may be subject to change without warning.

Several of the following methods to create and add objects other objects to the toolbar are inherited from ToolbarAPIMixin.

add_link_item()¶

See ToolbarAPIMixin.add_link_item

add_sideframe_item()¶

See ToolbarAPIMixin.add_sideframe_item

add_modal_item()¶

See ToolbarAPIMixin.add_modal_item

add_ajax_item()¶

See ToolbarAPIMixin.add_ajax_item

add_item()¶

See ToolbarAPIMixin.add_item

get_or_create_menu(key, verbose_name, position=None, disabled=False)¶

If a Menu with key already exists, this method will return that menu. Otherwise it will create a menu with the key identifier.

get_menu(key)¶

Will return the Menu identified with key, or None.

add_button(name, url, active=False, disabled=False, position=None)¶

Adds a Button to the toolbar.

add_sideframe_button(name, url, active=False, disabled=False, on_close=None)¶

Adds a SideframeButton to the toolbar.

add_modal_button(name, url, active=False, disabled=False, on_close=REFRESH_PAGE)¶

Adds a ModalButton to the toolbar.

add_button_list(position=None)¶

Adds an (empty) ButtonList to the toolbar and returns it.

edit_mode_active()¶

Property; returns True if the content or structure board editing modes are active.

watch_models()¶

Property; a list of models that the toolbar watches for URL changes, so it can redirect to the new URL on saving.

class cms.toolbar.items.Menu¶

Provides a menu in the toolbar. Use a CMSToolbar.get_or_create_menu method to create a Menu instance. Can be added to CMSToolbar.

Inherits from SubMenu below, so shares all of its methods, but in addition has:

get_or_create_menu(key, verbose_name, disabled=False, position=None)¶

Adds a new sub-menu, at position, and returns a SubMenu.

class cms.toolbar.items.SubMenu¶

A child of a Menu. Use a Menu.get_or_create_menu method to create a SubMenu instance. Can be added to Menu.

Several of the following methods to create and add objects are inherited from ToolbarAPIMixin.

add_link_item()¶

See ToolbarAPIMixin.add_link_item

add_sideframe_item()¶

See ToolbarAPIMixin.add_sideframe_item

add_modal_item()¶

See ToolbarAPIMixin.add_modal_item

add_ajax_item()¶

See ToolbarAPIMixin.add_ajax_item

add_item()¶

See ToolbarAPIMixin.add_item

get_item_count()¶

Returns the number of items in the menu.

Other methods:

add_break(identifier=None, position=None)¶

Adds a visual break in the menu, at position, and returns it. identifier may be used to make this item searchable.

class cms.toolbar.items.LinkItem¶

Sends a GET request. Use an add_link_item method to create a LinkItem instance. Can be added to CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.SideframeItem¶

Sends a GET request; loads response in a sideframe. Use an add_sideframe_item method to create a SideframeItem instance. Can be added to CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.ModalItem¶

Sends a GET request; loads response in a modal window. Use an add_modal_item method to create a ModalItem instance. Can be added to CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.AjaxItem¶

Sends a POST request. Use an add_ajax_item method to create a AjaxItem instance. Can be added to CMSToolbar, Menu, SubMenu.

class cms.toolbar.items.Break¶

A visual break in a menu. Use an add_break method to create a Break instance. Can be added to Menu, SubMenu.

class cms.toolbar.items.ButtonList¶

A visually-connected list of one or more buttons. Use an add_button_list() method to create a Button instance. Can be added to CMSToolbar.

add_button(name, url, active=False, disabled=False)¶

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

add_sideframe_button(name, url, active=False, disabled=False, on_close=None)¶

Adds a ModalButton to the toolbar.

add_modal_button(name, url, active=False, disabled=False, on_close=REFRESH_PAGE)¶

Adds an (empty) ButtonList to the toolbar and returns it.

get_buttons()¶

class cms.toolbar.items.Button¶

Sends a GET request. Use a CMSToolbar.add_button or ButtonList.add_button() method to create a Button instance. Can be added to CMSToolbar, ButtonList.

class cms.toolbar.items.SideframeButton¶

Sends a GET request. Use a CMSToolbar.add_sideframe_button or ButtonList.add_sideframe_button() method to create a SideframeButton instance. Can be added to CMSToolbar, ButtonList.

class cms.toolbar.items.ModalButton¶

Sends a GET request. Use a CMSToolbar.add_modal_button or ButtonList.add_modal_button() method to create a ModalButton instance. Can be added to CMSToolbar, ButtonList.

class cms.toolbar.items.BaseItem¶

All toolbar items inherit from BaseItem. If you need to create a custom toolbar item, sub-class BaseItem.

template¶

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

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

Provides APIs used by CMSToolbar and Menu.

add_link_item(name, url, active=False, disabled=False, position=None)¶

Adds a LinkItem that opens url, and returns it.

add_sideframe_item(name, url, active=False, disabled=False, on_close=None, position=None)¶

Adds a SideframeItem that opens url in the sideframe and returns it.

add_modal_item(name, url, active=False, disabled=False, on_close=REFRESH_PAGE, position=None)¶

Similar to add_sideframe_item(), but adds a ModalItem that opens opens the url in a modal dialog instead of the sideframe, and returns it.

add_ajax_item(name, action, active=False, disabled=False, data=None, question=None, position=None)¶

Adds AjaxItem that sends a POST request to action with data, and returns it. data should be None or a dictionary. The CSRF token will automatically be added to the item.

If a string is provided for question, it will be presented to the user to allow confirmation before the request is sent.

add_item(item, position=None)¶

Adds an item (which must be a sub-class of BaseItem), and returns it. This is a low-level API, and you should always use one of the built-in object-specific methods to add items in preference if possible, using this method only for custom item classes.

find_items(item_type)¶

Returns a list of ItemSearchResult objects matching all items of item_type (e.g. LinkItem).

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(). The return value of this method is safe to use as the position argument of the various APIs to add items.

class cms.toolbar.items.ItemSearchResult¶

Returned by the find APIs in ToolbarAPIMixin.

An ItemSearchResult will have two useful attributes:

item¶

The item found.

index¶

The index of the item (its position amongst the other items).

The ItemSearchResult itself can be cast to an integer, and supports addition and subtraction of numbers. See the position parameter for more details, and Control the position of items in the toolbar for examples.

class cms.toolbar_base.CMSToolbar.CMSToolbar¶

The base class for toolbar modifiers.

See How to extend the Toolbar for more information.

Parameters¶

The methods described below for creating/modifying toolbar items share a number of common parameters:

key¶

a unique identifier (typically a string)

verbose_name¶

the displayed text in the item

position¶

The position index of the new item in the list of items. May be:

• None - appends the item to the list

• an integer - inserts the item at that index in the list

• an object already in the list - Inserts the item into the list immediately before the object; must be a sub-class of BaseItem, and must exist in the list

• an ItemSearchResult - inserts the item into the list immediately before the ItemSearchResult. ItemSearchResult may be treated as an integer.

on_close:¶

Determines what happens after closing a frame (sideframe or modal) that has been opened by a menu item. May be:

• None - does nothing when the sideframe closes

• REFRESH_PAGE - refreshes the page when the frame closes

• a URL - opens the URLS when the frame is closed.

disabled¶

Greys out the item and renders it inoperable.

active¶

Applies to buttons only; renders the button it its ‘activated’ state.

django CMS constants used in toolbars¶

cms.constants.REFRESH_PAGE¶

Supplied to on_close arguments to refresh the current page when the frame is closed, for example:

from cms.constants import REFRESH_PAGE

self.toolbar.add_modal_item(
    'Modal item',
    url=modal_url,
    on_close=REFRESH_PAGE
    )

cms.cms_toolbars.ADMIN_MENU_IDENTIFIER¶

The Site menu (that usually shows the project’s domain name, example.com by default). ADMIN_MENU_IDENTIFIER allows you to get hold of this object easily. See Finding existing toolbar items for an example of usage.