documentation/toolbar: add toolbar permission and extension documentation

Repository: documentation
Branch: refs/heads/toolbar
Date: 2017-07-13T17:21:21+02:00
Author: Peter Holzer (agitator) <peter.holzer-2KzcThb1VtpWk0Htik3J/[email protected]>
Commit: https://github.com/plone/documentation/commit/645752486f8476ac3b9b79fcdfc0c0fdd0e1c988

add toolbar permission and extension documentation

Files changed:
A develop/plone/functionality/toolbar.rst
M develop/plone/functionality/index.rst

diff --git a/develop/plone/functionality/index.rst b/develop/plone/functionality/index.rst
index d6f11338..5f3191f4 100644
--- a/develop/plone/functionality/index.rst
+++ b/develop/plone/functionality/index.rst
@@ -21,4 +21,5 @@
     breadcrumbs
     sitemap
     discussion
-    contactform
\ No newline at end of file
+    contactform
+    toolbar
\ No newline at end of file
diff --git a/develop/plone/functionality/toolbar.rst b/develop/plone/functionality/toolbar.rst
new file mode 100644
index 00000000..24ca755d
--- /dev/null
+++ b/develop/plone/functionality/toolbar.rst
@@ -0,0 +1,96 @@
+=======
+Toolbar
+=======
+
+.. admonition:: Description
+
+    How to deal with permissions making your code permission-aware in Plone
+
+
+Visibility of the default toolbar
+=================================
+
+By default the toolbar is shown to the logged in user.
+
+There are some usecases where a user, for example one just logs in to view content that otherwise would be hidden, doesn't need the default toolbar.
+For those users the full featured toolbar, as it is by default, is not necessary and only takes up space on the screen.
+
+From Plone 5.1b4 on there is the ``Show Toolbar`` permission available. This allows you to show the default toolbar only to certain roles. If the users role isn't configured to show the default toolbar, a smaller member toolbar with the users personal actions (Personal Preferences, Logout,...) will be displayed at the logation where the login links is.
+
+You can set the visibility on the security tab within the ZMI or you add *rolemap.xml* file to the profile of your site. See :doc:`Custom permission </develop/plone/security/custom_permission>` for more information.
+
+
+How to add a custom toolbar menu
+================================
+
+Please evaluate first if the extra toolbar entry is really necessary, or if it could fit in one of the existing ones, to not overload the toolbar with entries.
+
+Below is an example on how to extend the toolbar with a custom menu entry.
+
+
+Python::
+
+    from plone.app.contentmenu.interfaces import IActionsMenu
+    from plone.app.contentmenu.interfaces import IActionsSubMenuItem
+    from plone.app.contentmenu.menu import BrowserMenu
+    from plone.app.contentmenu.menu import BrowserSubMenuItem
+
+    @implementer(IActionsSubMenuItem)
+    class MyGroupSubMenuItem(BrowserSubMenuItem):
+
+        title = 'Title of menu'
+        submenuId = 'my_id'
+
+        extra = {
+            'id': 'plone-mymenuid',
+            'li_class': 'plonetoolbar-myclass'
+        }
+
+        order = 70
+
+        @property
+        def action(self):
+            return 'url-for-action'
+
+        def available(self):
+            if checkPermission('cmf.ModifyPortalContent', self.context):
+                return True
+            return False
+
+        def selected(self):
+            return False
+
+
+    @implementer(IActionsMenu)
+    class MyGroupMenu(BrowserMenu):
+
+        def getMenuItems(self, context, request):
+            return [{
+                'title': 'Sub menu item',
+                'description': '',
+                'action': 'url-to-do-something',
+                'selected': False,
+                'icons': None,
+                'extra': {
+                    'id': 'some-id',
+                    'separator': None,
+                    'class': ''
+                },
+                'submenu': None
+            }]
+
+ZCML::
+
+    <browser:menu
+        id="my_id"
+        title=""
+        class=".menu.MyGroupMenu"
+        />
+
+    <adapter for="* *"
+             name="my_name"
+             factory=".menu.MyGroupSubMenuItem"
+             provides="plone.app.contentmenu.interfaces.IContentMenuItem" />
+
+
+For more examples and better understanding please see the ``plone.app.contentmenu`` package.



------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot