From 07d2851e37422b8dbfd5ef811820535c37560c24 Mon Sep 17 00:00:00 2001
From: Matt Westcott <matt@west.co.tt>
Date: Tue, 12 Aug 2014 12:06:01 +0100
Subject: [PATCH] documentation for register_admin_menu_item

---
 docs/core_components/pages/editing_api.rst | 35 +++++++++++++++++-----
 wagtail/wagtailadmin/menu.py               | 10 +++++++
 2 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/docs/core_components/pages/editing_api.rst b/docs/core_components/pages/editing_api.rst
index 4d346a8150..7910d9f37a 100644
--- a/docs/core_components/pages/editing_api.rst
+++ b/docs/core_components/pages/editing_api.rst
@@ -528,10 +528,19 @@ The available hooks are:
         url(r'^how_did_you_almost_know_my_name/$', admin_view, name='frank' ),
       ]
 
-.. _construct_main_menu:
+.. _register_admin_menu_item:
 
-``construct_main_menu``
-  Add, remove, or alter ``MenuItem`` objects from the Wagtail admin menu. The callable passed to this hook must take a ``request`` object and a list of ``menu_items``; it must return a list of menu items. New items can be constructed from the ``MenuItem`` class by passing in: a ``label`` which will be the text in the menu item, the URL of the admin page you want the menu item to link to (usually by calling ``reverse()`` on the admin view you've set up), CSS class ``name`` applied to the wrapping ``<li>`` of the menu item as ``"menu-{name}"``, CSS ``classnames`` which are used to give the link an icon, and an ``order`` integer which determine's the item's place in the menu.
+``register_admin_menu_item``
+  .. versionadded:: 0.6
+
+  Add an item to the Wagtail admin menu. The callable passed to this hook must return an instance of ``wagtail.wagtailadmin.menu.MenuItem``. New items can be constructed from the ``MenuItem`` class by passing in a ``label`` which will be the text in the menu item, and the URL of the admin page you want the menu item to link to (usually by calling ``reverse()`` on the admin view you've set up). Additionally, the following keyword arguments are accepted:
+
+  :name: an internal name used to identify the menu item; defaults to the slugified form of the label. Also applied as a CSS class to the wrapping ``<li>``, as ``"menu-{name}"``.
+  :classnames: additional classnames applied to the link, used to give it an icon
+  :attrs: additional HTML attributes to apply to the link
+  :order: an integer which determines the item's position in the menu
+
+  ``MenuItem`` can be subclassed to customise the HTML output, specify Javascript files required by the menu item, or conditionally show or hide the item for specific requests (for example, to apply permission checks); see the source code (``wagtail/wagtailadmin/menu.py``) for details.
 
   .. code-block:: python
 
@@ -540,11 +549,23 @@ The available hooks are:
     from wagtail.wagtailcore import hooks
     from wagtail.wagtailadmin.menu import MenuItem
 
+    @hooks.register('register_admin_menu_item')
+    def register_frank_menu_item():
+      return MenuItem('Frank', reverse('frank'), classnames='icon icon-folder-inverse', order=10000)
+
+.. _construct_main_menu:
+
+``construct_main_menu``
+  Called just before the Wagtail admin menu is output, to allow the list of menu items to be modified. The callable passed to this hook will receive a ``request`` object and a list of ``menu_items``, and should modify ``menu_items`` in-place as required. Adding menu items should generally be done through the ``register_admin_menu_item`` hook instead - items added through ``construct_main_menu`` will be missing any associated Javascript includes, and their ``is_shown`` check will not be applied.
+
+  .. code-block:: python
+
+    from wagtail.wagtailcore import hooks
+
     @hooks.register('construct_main_menu')
-    def construct_main_menu(request, menu_items):
-      menu_items.append(
-        MenuItem( 'Frank', reverse('frank'), classnames='icon icon-folder-inverse', order=10000)
-      )
+    def hide_explorer_menu_item_from_frank(request, menu_items):
+      if request.user.username == 'frank':
+        menu_items[:] = [item for item in menu_items if item.name != 'explorer']
 
 
 .. _insert_editor_js:
diff --git a/wagtail/wagtailadmin/menu.py b/wagtail/wagtailadmin/menu.py
index 27afcda445..dc109da564 100644
--- a/wagtail/wagtailadmin/menu.py
+++ b/wagtail/wagtailadmin/menu.py
@@ -30,12 +30,22 @@ class MenuItem(object):
 
     js_files = []
     def render_js(self):
+        """
+        Return a string of any Javascript declarations required by this menu item.
+        These will be included on all admin pages, regardless of whether the menu item
+        is actually shown or not - this allows us to cache/compress the JS globally.
+        By default this returns a script tag for every file listed in self.js_files.
+        """
         if self.js_files:
             return format_html_join('\n', '<script src="{0}{1}"></script>',
                     ((settings.STATIC_URL, filename) for filename in self.js_files)
                 )
 
     def is_shown(self, request):
+        """
+        Whether this menu item should be shown for the given request; permission
+        checks etc should go here. By default, menu items are shown all the time
+        """
         return True
 
     def render_html(self):