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
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 thatkey
with the givenverbose_name
onside
atposition
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 wrappingdiv
whileextra_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 ofBaseItem
. Read above for information about theposition
argument.remove_item
(item)Removes
item
from the toolbar or menu. If the item can’t be found, aKeyError
is raised.find_items
(item_type, \*attributes*)Returns a list of
ItemSearchResult
objects matching all items ofitem_type
, which must be a sub-class ofBaseItem
, where all attributes inattributes
match.find_first
(item_type, \*attributes*)Returns the first
ItemSearchResult
that matches the search orNone
. The search strategy is the same as infind_items()
. Since positional insertion allowsNone
, 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 toNone
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 theurl
in a modal dialog instead of the sideframe.on_close
can be set toNone
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 inadd_sideframe_item()
then inadd_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
withdata
.data
should beNone
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
orcms.constants.RIGHT
.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.``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 aSubMenu
.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 ofButton
.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
()