The 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.
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()
add_sideframe_item()
add_modal_item()
add_ajax_item()
add_item()
get_or_create_menu(key, verbose_name, position=None, disabled=False)
If a
Menu
withkey
already exists, this method will return that menu. Otherwise it will create a menu with thekey
identifier.get_menu(key)
Will return the
Menu
identified withkey
, orNone
.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)
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()
add_sideframe_item()
add_modal_item()
add_ajax_item()
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 renderstemplate
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 opensurl
, and returns it.add_sideframe_item(name, url, active=False, disabled=False, on_close=None, position=None)
Adds a
SideframeItem
that opensurl
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 aModalItem
that opens opens theurl
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 toaction
withdata
, and returns it.data
should beNone
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 ofitem_type
(e.g.LinkItem
).find_first(item_type, \*attributes*)
Returns the first
ItemSearchResult
that matches the search, orNone
. The search strategy is the same as infind_items()
. The return value of this method is safe to use as theposition
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 listan 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 listan
ItemSearchResult
- inserts the item into the list immediately before theItemSearchResult
.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 closesREFRESH_PAGE
- refreshes the page when the frame closesa 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.