Toolbar¶

The toolbar can contain various items, some of which in turn can contain other items. These items are represented by the classes listed in cms.toolbar.items, and created using the various APIs described below.

Do not instantiate these classes manually

These classes are described here for reference purposes only. It is strongly recommended that you do not create instances yourself, but use the methods listed here.

Classes and methods¶

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

classcms.toolbar.toolbar.CMSToolbar(request, request_path=None, _async=False)¶

Bases: CMSToolbarBase

add_ajax_item(name, action, active=False, disabled=False, extra_classes=None, data=None, question=None, side=<object object>, position=None, on_success=None, method='POST')¶

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_button(name, url, active=False, disabled=False, extra_classes=None, extra_wrapper_classes=None, side=<object object>, position=None)¶: Adds a Button to the toolbar.

add_button_list(identifier=None, extra_classes=None, side=<object object>, position=None)¶: Adds an (empty) ButtonList to the toolbar and returns it.

add_item(item, position=None)¶: Adds an item (which must be a subclass 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.

add_link_item(name, url, active=False, disabled=False, extra_classes=None, side=<object object>, position=None)¶: Adds a LinkItem that opens url, and returns it.

add_modal_button(name, url, active=False, disabled=False, extra_classes=None, extra_wrapper_classes=None, side=<object object>, position=None, on_close='REFRESH_PAGE')¶: Adds a ModalButton to the toolbar.

add_modal_item(name, url, active=False, disabled=False, extra_classes=None, on_close='REFRESH_PAGE', side=<object object>, position=None)¶: Similar to add_sideframe_item(), but adds a ModalItem that opens the url in a modal dialog instead of the sideframe, and returns it.

add_sideframe_button(name, url, active=False, disabled=False, extra_classes=None, extra_wrapper_classes=None, side=<object object>, position=None, on_close=None)¶: Adds a SideframeButton to the toolbar.

add_sideframe_item(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=<object object>, position=None)¶: Adds a SideframeItem that opens url in the sideframe and returns it.

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.

find_items(item_type, **attributes)¶: Returns a list of ItemSearchResult objects matching all items of item_type (e.g. LinkItem).

get_item_count()¶: Returns the number of items in the menu.

get_menu(key, verbose_name=None, side=<object object>, position=None)¶: Will return the Menu identified with key, or None.

get_object()¶

Returns the object currently associated with the toolbar.

This returns the object that was previously set using set_object(), or None if no object has been associated with the toolbar.

Returns:: The object associated with the toolbar, or None
Return type:: django.db.models.Model or None

get_or_create_menu(key, verbose_name=None, disabled=False, side=<object object>, position=None)¶: If a Menu with key already exists, this method will return that menu. Otherwise it will create a menu with the key identifier.

populate()¶: Populates the toolbar with the CMS items.

set_object(obj)¶

Associates an object with the toolbar.

Sets the toolbar’s object if one has not already been set. This object is typically a Django model instance that the toolbar should operate on, such as a PageContent object or any other model that supports editable placeholders through a PlaceholderRelationField.

The object is used by other toolbar methods like get_object_edit_url(), get_object_preview_url(), and get_object_structure_url() to generate appropriate URLs for the object.

Parameters:: obj (django.db.models.Model) – The object to associate with the toolbar

content_mode_active¶: True if content mode is active.

edit_mode_active¶: True if the structure board editing mode is active.

preview_mode_active¶: True if preview mode is 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.

classcms.toolbar.items.Menu(name, csrf_token, disabled=False, side=<object object>)¶

Bases: SubMenu

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

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

add_item(item, position=None)¶: Adds an item (which must be a subclass 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.

add_link_item(name, url, active=False, disabled=False, extra_classes=None, side=<object object>, position=None)¶: Adds a LinkItem that opens url, and returns it.

add_modal_item(name, url, active=False, disabled=False, extra_classes=None, on_close='REFRESH_PAGE', side=<object object>, position=None)¶: Similar to add_sideframe_item(), but adds a ModalItem that opens the url in a modal dialog instead of the sideframe, and returns it.

add_sideframe_item(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=<object object>, position=None)¶: Adds a SideframeItem that opens url in the sideframe and returns it.

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.

find_items(item_type, **attributes)¶: Returns a list of ItemSearchResult objects matching all items of item_type (e.g. LinkItem).

get_context()¶: Returns the context (as dictionary) for this item.

get_item_count()¶: Returns the number of items in the menu.

get_or_create_menu(key, verbose_name, disabled=False, side=<object object>, position=None)¶: Adds a new sub-menu, at position, and returns a SubMenu.

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

template='cms/toolbar/items/menu.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.SubMenu(name, csrf_token, disabled=False, side=<object object>)¶

Bases: ToolbarAPIMixin, BaseItem

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

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

add_item(item, position=None)¶: Adds an item (which must be a subclass 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.

add_link_item(name, url, active=False, disabled=False, extra_classes=None, side=<object object>, position=None)¶: Adds a LinkItem that opens url, and returns it.

add_modal_item(name, url, active=False, disabled=False, extra_classes=None, on_close='REFRESH_PAGE', side=<object object>, position=None)¶: Similar to add_sideframe_item(), but adds a ModalItem that opens the url in a modal dialog instead of the sideframe, and returns it.

add_sideframe_item(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=<object object>, position=None)¶: Adds a SideframeItem that opens url in the sideframe and returns it.

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.

find_items(item_type, **attributes)¶: Returns a list of ItemSearchResult objects matching all items of item_type (e.g. LinkItem).

get_context()¶: Returns the context (as dictionary) for this item.

get_item_count()¶: Returns the number of items in the menu.

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

template='cms/toolbar/items/menu.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.LinkItem(name, url, active=False, disabled=False, extra_classes=None, side=<object object>)¶

Bases: BaseItem

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

get_context()¶: Returns the context (as dictionary) for this item.

template='cms/toolbar/items/item_link.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.SideframeItem(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=<object object>)¶

Bases: FrameItem

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.

template='cms/toolbar/items/item_sideframe.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.ModalItem(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=<object object>)¶

Bases: FrameItem

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.

template='cms/toolbar/items/item_modal.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.AjaxItem(name, action, csrf_token, data=None, active=False, disabled=False, extra_classes=None, question=None, side=<object object>, on_success=None, method='POST')¶

Bases: BaseItem

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

get_context()¶: Returns the context (as dictionary) for this item.

template='cms/toolbar/items/item_ajax.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.Break(identifier=None)¶

Bases: BaseItem

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

template='cms/toolbar/items/break.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.ButtonList(identifier=None, extra_classes=None, side=<object object>)¶

Bases: BaseItem

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

add_button(name, url, active=False, disabled=False, extra_classes=None)¶: Adds a Button to the list of buttons and returns it.

add_modal_button(name, url, active=False, disabled=False, extra_classes=None, on_close='REFRESH_PAGE')¶: Adds a ModalButton to the button list and returns it.

add_sideframe_button(name, url, active=False, disabled=False, extra_classes=None, on_close=None)¶: Adds a SideframeButton to the button list and returns it.

get_buttons()¶: Yields all buttons in the button list

get_context()¶: Returns the context (as dictionary) for this item.

template='cms/toolbar/items/button_list.html'¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.Button(name, url, active=False, disabled=False, extra_classes=None)¶

Bases: BaseButton

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.

classcms.toolbar.items.SideframeButton(name, url, active=False, disabled=False, extra_classes=None, on_close=None)¶

Bases: ModalButton

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.

classcms.toolbar.items.ModalButton(name, url, active=False, disabled=False, extra_classes=None, on_close=None)¶

Bases: Button

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.

classcms.toolbar.items.BaseItem(side=<object object>)¶

Bases: object

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

get_context()¶: Returns the context (as dictionary) for this item.

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

template=None¶: Must be set by subclasses and point to a Django template

classcms.toolbar.items.ToolbarAPIMixin¶

Provides APIs used by CMSToolbar and Menu.

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

add_link_item(name, url, active=False, disabled=False, extra_classes=None, side=<object object>, position=None)¶: Adds a LinkItem that opens url, and returns it.

add_modal_item(name, url, active=False, disabled=False, extra_classes=None, on_close='REFRESH_PAGE', side=<object object>, position=None)¶: Similar to add_sideframe_item(), but adds a ModalItem that opens the url in a modal dialog instead of the sideframe, and returns it.

add_sideframe_item(name, url, active=False, disabled=False, extra_classes=None, on_close=None, side=<object object>, position=None)¶: Adds a SideframeItem that opens url in the sideframe and returns it.

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.

find_items(item_type, **attributes)¶: Returns a list of ItemSearchResult objects matching all items of item_type (e.g. LinkItem).

get_item_count()¶: Returns the number of items in the menu.

classcms.toolbar.items.ItemSearchResult(item, index)¶

Bases: object

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.

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.

side¶: Either cms.constants.LEFT or cms.constants.RIGHT (both unique objects denoted above as <object object>). Decides to which side of the toolbar the item should be added.

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:

fromcms.constantsimport 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 using cms.toolbar.toolbar.CMSToolbar.get_menu().

cms.cms_toolbars.LANGUAGE_MENU_IDENTIFIER¶: The Language menu. LANGUAGE_MENU_IDENTIFIER allows you to get hold of this object easily using cms.toolbar.toolbar.CMSToolbar.get_menu().

cms.cms_toolbars.PAGE_MENU_IDENTIFIER¶: The Page menu. PAGE_MENU_IDENTIFIER allows you to get hold of this object easily using cms.toolbar.toolbar.CMSToolbar.get_menu().