8000 Improved toolbar tutorial (#6400) · django-cms/django-cms@4205eca · GitHub
[go: up one dir, main page]
Skip to content

Commit 4205eca

Browse files
evildmpevildmp
authored
Improved toolbar tutorial (#6400)
* Improved toolbar tutorial
1 parent d5e25f4 commit 4205eca

File tree

3 files changed

+137
-48
lines changed

3 files changed

+137
-48
lines changed

‎docs/introduction/06-toolbar.rst

Lines changed: 136 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -8,82 +8,171 @@ django CMS allows you to control what appears in the toolbar. This allows you
88
to integrate your application in the frontend editing mode of django CMS and
99
provide your users with a streamlined editing experience.
1010

11+
In this section of the tutorial, we will add a new *Polls* menu to the toolbar.
1112

12-
******************
13-
Create the toolbar
14-
******************
1513

16-
We'll create a toolbar using a ``cms.toolbar_base.CMSToolbar`` sub-class.
14+
*********************************
15+
Add a basic ``PollToolbar`` class
16+
*********************************
1717

18-
Create a new ``cms_toolbars.py`` file in your Polls/CMS Integration application. Here's a basic example:
18+
We'll create a toolbar menu using a ``cms.toolbar_base.CMSToolbar`` sub-class.
1919

20-
.. code-block:: python
20+
Start by adding a new ``cms_toolbars.py`` file to your Polls/CMS Integration application, and
21+
create the ``CMSToolbar``:
22+
23+
.. code-block:: python
2124
22-
from django.utils.translation import ugettext_lazy as _
23-
from cms.toolbar_pool import toolbar_pool
2425
from cms.toolbar_base import CMSToolbar
25-
from cms.utils.urlutils import admin_reverse
26+
from cms.toolbar_pool import toolbar_pool
2627
from polls.models import Poll
2728
2829
2930
class PollToolbar(CMSToolbar):
30-
supported_apps = (
31-
'polls',
32-
'polls_cms_integration',
33-
)
34-
35-
watch_models = [Poll]
3631
3732
def populate(self):
38-
if not self.is_current_app:
39-
return
33+
self.toolbar.get_or_create_menu(
34+
'polls_cms_integration-polls', # a unique key for this menu
35+
'Polls', # the text that should appear in the menu
36+
)
37+
38+
39+
# register the toolbar
40+
toolbar_pool.register(PollToolbar)
41+
42+
43+
.. note::
44+
45+
Don't forget to restart the runserver to have your new ``cms_toolbars.py`` file recognised.
46+
47+
You will now find, in every page of the site, a new item in the toolbar:
48+
49+
.. image:: /introduction/images/toolbar-polls.png
50+
:alt: The Polls menu in the toolbars
51+
:width: 630
52+
53+
The ``populate()`` method is what gets called when the toolbar is built. In it, we're using
54+
:meth:`get_or_create_menu() <cms.toolbar.toolbar.CMSToolbar.get_or_create_menu()>` to add a *Polls*
55+
item to the toolbar.
56+
57+
58+
*****************************
59+
Add nodes to the *Polls* menu
60+
*****************************
4061

41-
menu = self.toolbar.get_or_create_menu('poll-app', _('Polls'))
62+
So far, the *Polls* menu is empty. We can extend ``populate()`` to add some items.
63+
``get_or_create_menu`` returns a menu that we can manipulate, so let's change the ``populate()``
64+
method to add an item that allows us to see the full list of polls in the sideframe, with
65+
:meth:`add_sideframe_item() <cms.toolbar.items.ToolbarMixin.add_sideframe_item()>`.
66+
67+
.. code-block:: python
68+
:emphasize-lines: 1, 8, 10-13
69+
70+
from cms.utils.urlutils import admin_reverse
71+
[...]
72+
73+
74+
class PollToolbar(CMSToolbar):
75+
76+
def populate(self):
77+
menu = self.toolbar.get_or_create_menu('polls_cms_integration-polls', 'Polls')
4278
4379
menu.add_sideframe_item(
44-
name=_('Poll list'),
80+
name='Poll list',
4581
url=admin_reverse('polls_poll_changelist'),
46-
)
82+
)
83+
84+
After refreshing the page to load the changes, you can now add see the list of polls directly from
85+
the menu.
86+
87+
Also useful would be an option to create new polls. We'll use a modal window for this, invoked with
88+
:meth:`add_modal_item() <cms.toolbar.items.ToolbarMixin.add_modal_item()>`. Add the new code to the
89+
end of the ``populate()`` method:
90+
91+
.. code-block:: python
92+
:emphasize-lines: 6-9
93+
94+
class PollToolbar(CMSToolbar):
95+
96+
def populate(self):
97+
[...]
4798
4899
menu.add_modal_item(
49-
name=_('Add new poll'),
50-
url=admin_reverse('polls_poll_add'),
51-
)
100+
name=('Add a new poll'), # name of the new menu item
101+
url=admin_reverse('polls_poll_add'), # the URL it should open with
102+
)
52103
53104
54-
toolbar_pool.register(PollToolbar) # register the toolbar
105+
*******************
106+
Further refinements
107+
*******************
108+
109+
The *Polls* menu appears in the toolbar everywhere in the site. It would be useful to restrict this
110+
to pages that are actually relevant.
55111

112+
The first thing to add is a test right at the start of the ``populate()`` method:
56113

57-
.. note:: Don't forget to restart the runserver to have your new toolbar item recognised.
114+
.. code-block:: python
115+
:emphasize-lines: 3-4
58116
117+
def populate(self):
59118
60-
What this all means
61-
===================
119+
if not self.is_current_app:
120+
return
62121
63-
* ``supported_apps`` is a list of application names in which the toolbar should be active. Usually you don't need to set
64-
``supported_apps`` - the appropriate application will be detected automatically. In this case (since the views for
65-
the Polls application are in ``polls``, while our ``cms_toolbars.py`` is in the ``polls_cms_integration``
66-
application) we need to specify both explicitly.
67-
* ``watch_models`` allows the frontend editor to redirect the user to the model instance
68-
``get_absolute_url`` whenever an instance of this model is created or saved through the frontend editor
69-
(se 97AE e :ref:`url_changes` for details).
70-
* The ``populate()`` method, which populates the toolbar menu with nodes, will only be called if the current user is a
71-
staff user. In this case it:
122+
[...]
123+
124+
The ``is_current_app`` flag tells us if the function handling this view (e.g. the list of polls)
125+
belongs to the same application as the one responsible for this toolbar menu. Often, this can be
126+
detected automatically, but in this case, the view belongs to the ``polls`` application, whereas
127+
the toolbar menu belongs to ``polls_cms_integration``. So, we need to tell the ``PollToolbar``
128+
class explicitly that it's actually associated with the ``polls`` application:
129+
130+
.. code-block:: python
131+
:emphasize-lines: 3
132+
133+
class PollToolbar(CMSToolbar):
72134
73-
* checks whether we're in a page belonging to this application, using ``self.is_current_app``
74-
* ... if so, it creates a menu, if one's not already there (``self.toolbar.get_or_create_menu()``)
75-
* adds a menu item to list all polls in the overlay (``add_sideframe_item()``)
76-
* adds a menu item to add a new poll as a modal window (``add_modal_item()``)
135+
supported_apps = ['polls']
77136
137+
Now, the menu will only appear in relevant pages.
78138

79-
**************
80-
See it at work
81-
**************
82139

83-
Visit your Polls page on your site, and you'll see a new *Polls* item in the toolbar.
140+
********************************
141+
The complete ``cms_toolbars.py``
142+
********************************
143+
144+
For completeness, here is the full example:
145+
146+
.. code-block:: python
147+
148+
from cms.utils.urlutils import admin_reverse
149+
from cms.toolbar_base import CMSToolbar
150+
from cms.toolbar_pool import toolbar_pool
151+
from polls.models import Poll
152+
84153
85-
It gives you quick access to the list of Polls in the Admin, and gives you a shortcut for
86-
creating a new Poll.
154+
class PollToolbar(CMSToolbar):
155+
supported_apps = ['polls']
156+
157+
def populate(self):
158+
159+
if not self.is_current_app:
160+
return
161+
162+
menu = self.toolbar.get_or_create_menu('polls_cms_integration-polls', 'Polls')
163+
164+
menu.add_sideframe_item(
165+
name='Poll list',
166+
url=admin_reverse('polls_poll_changelist'),
167+
)
168+
169+
menu.add_modal_item(
170+
name=('Add a new poll'), # name of the new menu item
171+
url=admin_reverse('polls_poll_add'), # the URL it should open with
172+
)
173+
174+
175+
toolbar_pool.register(PollToolbar) # register the toolbar
87176
88-
There's a lot more to django CMS toolbar classes than this - see
177+
This is just a basic example, and there's a lot more to django CMS toolbar classes than this - see
89178
:ref:`toolbar_how_to` for more.

‎docs/introduction/images/toolbar-polls.png

23.8 KB
Loading

‎docs/reference/toolbar.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ cms.toolbar.toolbar
7979
Removes an item from the toolbar or raises a :exc:`KeyError` if it's
8080
not found.
8181

82-
.. method:: get_or_create_menu(key. verbose_name, side=LEFT, position=None)
82+
.. method:: get_or_create_menu(key, verbose_name, side=LEFT, position=None)
8383

8484
If a menu with ``key`` already exists, this method will return that
8585
menu. Otherwise it will create a menu for that ``key`` with the given

0 commit comments

Comments
 (0)
0