6. Extending the toolbar¶
django CMS allows you to control what appears in the toolbar. This allows you to integrate your application in the frontend editing mode of django CMS and provide your users with a streamlined editing experience.
In this section of the tutorial, we will add a new Polls menu to the toolbar.
6.1. Add a basic PollToolbar
class¶
We’ll add various controls to the toolbar, using a cms.toolbar_base.CMSToolbar
sub-class.
6.1.2. Add buttons to the toolbar¶
As well as menus, you can add buttons to the toolbar in a very similar way. Rewrite the
populate()
method, noting how closely the structure of this code matches that for adding menus.
def populate(self):
buttonlist = self.toolbar.add_button_list()
buttonlist.add_sideframe_button(
name='Poll list',
url=admin_reverse('polls_poll_changelist'),
)
buttonlist.add_modal_button(
name='Add a new poll',
url=admin_reverse('polls_poll_add'),
)
6.2. Further refinements¶
The buttons and menu for Polls appear in the toolbar everywhere in the site. It would be useful to restrict this to pages that are actually relevant.
The first thing to add is a test right at the start of the populate()
method:
def populate(self):
if not self.is_current_app:
return
[...]
The is_current_app
flag tells us if the function handling this view (e.g. the list of polls)
belongs to the same application as the one responsible for this toolbar menu.
Often, this can be detected automatically, but in this case, the view belongs to the polls
application, whereas the toolbar menu belongs to polls_cms_integration
. So, we need to tell the
PollToolbar
class explicitly that it’s actually associated with the polls
application:
class PollToolbar(CMSToolbar):
supported_apps = ['polls']
Now, the buttons/menu will only appear in relevant pages.
6.3. The complete cms_toolbars.py
¶
For completeness, here is the full example:
from cms.utils.urlutils import admin_reverse
from cms.toolbar_base import CMSToolbar
from cms.toolbar_pool import toolbar_pool
from polls.models import Poll
class PollToolbar(CMSToolbar):
supported_apps = ['polls']
def populate(self):
if not self.is_current_app:
return
menu = self.toolbar.get_or_create_menu('polls_cms_integration-polls', 'Polls')
menu.add_sideframe_item(
name='Poll list',
url=admin_reverse('polls_poll_changelist'),
)
menu.add_modal_item(
name=('Add a new poll'),
url=admin_reverse('polls_poll_add'),
)
buttonlist = self.toolbar.add_button_list()
buttonlist.add_sideframe_button(
name='Poll list',
url=admin_reverse('polls_poll_changelist'),
)
buttonlist.add_modal_button(
name='Add a new poll',
url=admin_reverse('polls_poll_add'),
)
toolbar_pool.register(PollToolbar) # register the toolbar
This is just a basic example, and there’s a lot more to django CMS toolbar classes than this - see How to extend the Toolbar for more.