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(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 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_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 opensurl
, 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 aModalItem
that opens theurl
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 opensurl
in the sideframe and returns it.
- 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.
- find_items(item_type, **attributes)#
Returns a list of
ItemSearchResult
objects matching all items ofitem_type
(e.g.LinkItem
).
- get_item_count()#
Returns the number of items in the menu.
Will return the
Menu
identified withkey
, orNone
.
If a
Menu
withkey
already exists, this method will return that menu. Otherwise it will create a menu with thekey
identifier.
- populate()#
Populates the toolbar with the CMS items.
- 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.
- class cms.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 aMenu
instance. Can be added toCMSToolbar
.- 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 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_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 opensurl
, 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 aModalItem
that opens theurl
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 opensurl
in the sideframe and returns it.
- 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.
- find_items(item_type, **attributes)#
Returns a list of
ItemSearchResult
objects matching all items ofitem_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 renderstemplate
with the context returned.
- template = 'cms/toolbar/items/menu.html'#
Must be set by subclasses and point to a Django template
- class cms.toolbar.items.SubMenu(name, csrf_token, disabled=False, side=<object object>)#
Bases:
ToolbarAPIMixin
,BaseItem
A child of a
Menu
. Use aMenu.get_or_create_menu
method to create aSubMenu
instance. Can be added toMenu
.- 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 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_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 opensurl
, 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 aModalItem
that opens theurl
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 opensurl
in the sideframe and returns it.
- 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.
- find_items(item_type, **attributes)#
Returns a list of
ItemSearchResult
objects matching all items ofitem_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 renderstemplate
with the context returned.
- template = 'cms/toolbar/items/menu.html'#
Must be set by subclasses and point to a Django template
- class cms.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 aLinkItem
instance. Can be added toCMSToolbar
,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
- class cms.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 aSideframeItem
instance. Can be added toCMSToolbar
,Menu
,SubMenu
.- template = 'cms/toolbar/items/item_sideframe.html'#
Must be set by subclasses and point to a Django template
- class cms.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 aModalItem
instance. Can be added toCMSToolbar
,Menu
,SubMenu
.- template = 'cms/toolbar/items/item_modal.html'#
Must be set by subclasses and point to a Django template
- class cms.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 aAjaxItem
instance. Can be added toCMSToolbar
,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
- class cms.toolbar.items.Break(identifier=None)#
Bases:
BaseItem
A visual break in a menu. Use an
add_break
method to create aBreak
instance. Can be added toMenu
,SubMenu
.- template = 'cms/toolbar/items/break.html'#
Must be set by subclasses and point to a Django template
- class cms.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 aButtonList
instance. Can be added toCMSToolbar
.- 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
- class cms.toolbar.items.Button(name, url, active=False, disabled=False, extra_classes=None)#
Bases:
BaseButton
Sends a GET request. Use a
CMSToolbar.add_button
orButtonList.add_button()
method to create aButton
instance. Can be added toCMSToolbar
,ButtonList
.
- class cms.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
orButtonList.add_sideframe_button()
method to create aSideframeButton
instance. Can be added toCMSToolbar
,ButtonList
.
- class cms.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
orButtonList.add_modal_button()
method to create aModalButton
instance. Can be added toCMSToolbar
,ButtonList
.
- class cms.toolbar.items.BaseItem(side=<object object>)#
Bases:
object
All toolbar items inherit from
BaseItem
. If you need to create a custom toolbar item, subclassBaseItem
.- 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 renderstemplate
with the context returned.
- template = None#
Must be set by subclasses and point to a Django template
- class cms.toolbar.items.ToolbarAPIMixin#
Provides APIs used by
CMSToolbar
andMenu
.- 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 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 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 opensurl
, 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 aModalItem
that opens theurl
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 opensurl
in the sideframe and returns it.
- 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.
- find_items(item_type, **attributes)#
Returns a list of
ItemSearchResult
objects matching all items ofitem_type
(e.g.LinkItem
).
- get_item_count()#
Returns the number of items in the menu.
- class cms.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 theposition
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 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.
- side#
Either
cms.constants.LEFT
orcms.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: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 usingcms.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 usingcms.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 usingcms.toolbar.toolbar.CMSToolbar.get_menu()
.