Merge branch 'zerolab-update-hook-names'

CHANGELOG.txt

@@ -42,6 +42,7 @@ Changelog
  * Added hook `construct_homepage_summary_items` for customising the site summary panel on the admin homepage
  * No longer automatically tries to use Celery for sending notification emails
  * Added "Add child page" button to admin userbar (Eric Drechsel)
+ * Renamed the `construct_wagtail_edit_bird` hook to `construct_wagtail_userbar`
  * Fix: Prevent logout on changing password when SessionAuthenticationMiddleware is in use
 
 

docs/reference/hooks.rst

@@ -46,9 +46,15 @@ The available hooks are:
             return HttpResponse("<h1>bad googlebot no cookie</h1>")
 
 
-.. _construct_wagtail_edit_bird:
+.. _construct_wagtail_userbar:
 
-``construct_wagtail_edit_bird``
+.. versionadded:: 0.3
+
+.. versionchanged:: 1.0
+
+   The hook was renamed from ``construct_wagtail_edit_bird``
+
+``construct_wagtail_userbar``
   Add or remove items from the wagtail userbar. Add, edit, and moderation tools are provided by default. The callable passed into the hook must take the ``request`` object and a list of menu objects, ``items``. The menu item objects must have a ``render`` method which can take a ``request`` object and return the HTML string representing the menu item. See the userbar templates and menu item classes for more information.
 
   .. code-block:: python
@@ -60,7 +66,7 @@ The available hooks are:
         return '<li><a href="http://cuteoverload.com/tag/puppehs/" ' \
         + 'target="_parent" class="action icon icon-wagtail">Puppies!</a></li>'
 
-    @hooks.register('construct_wagtail_edit_bird')
+    @hooks.register('construct_wagtail_userbar')
     def add_puppy_link_item(request, items):
       return items.append( UserbarPuppyLinkItem() )
 

docs/releases/1.0.rst

@@ -87,6 +87,8 @@ Admin
  * Added cache-control headers to all admin views. This allows Varnish/Squid/CDN to run on vanilla settings in front of a Wagtail site
  * Date / time pickers now consistently use times without seconds, to prevent Javascript behaviour glitches when focusing / unfocusing fields
  * Added hook ``construct_homepage_summary_items`` for customising the site summary panel on the admin homepage
+ * Renamed the ``construct_wagtail_edit_bird`` hook to ``construct_wagtail_userbar``
+
 
 
 Project template
@@ -292,3 +294,11 @@ Wagtail organises panels into three tabs: 'Content', 'Promote' and 'Settings'. D
         ObjectList(BlogPage.promote_panels, heading='Promote'),
         ObjectList(BlogPage.settings_panels, heading='Settings', classname="settings"),
     ])
+
+``construct_wagtail_edit_bird`` hook has been renamed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously you could customize the Wagtail userbar using the ``construct_wagtail_edit_bird`` hook.
+The hook has been renamed to ``construct_wagtail_userbar``.
+
+The old hook is now deprecated; all existing ``construct_wagtail_edit_bird`` declarations should be updated to the new hook.

wagtail/wagtailadmin/views/userbar.py

@@ -1,3 +1,5 @@
+import warnings
+
 from django.shortcuts import render
 from django.contrib.auth.decorators import permission_required
 
@@ -5,6 +7,8 @@ from wagtail.wagtailadmin.userbar import EditPageItem, AddPageItem, ApproveModer
 from wagtail.wagtailcore import hooks
 from wagtail.wagtailcore.models import Page, PageRevision
 
+from wagtail.utils.deprecation import RemovedInWagtail11Warning
+
 
 @permission_required('wagtailadmin.access_admin', raise_exception=True)
 def for_frontend(request, page_id):
@@ -13,7 +17,10 @@ def for_frontend(request, page_id):
         AddPageItem(Page.objects.get(id=page_id)),
     ]
 
-    for fn in hooks.get_hooks('construct_wagtail_edit_bird'):
+    # TODO: Remove in 1.1 release
+    run_deprecated_edit_bird_hook(request, items)
+
+    for fn in hooks.get_hooks('construct_wagtail_userbar'):
         fn(request, items)
 
     # Render the items
@@ -37,7 +44,10 @@ def for_moderation(request, revision_id):
         RejectModerationEditPageItem(PageRevision.objects.get(id=revision_id)),
     ]
 
-    for fn in hooks.get_hooks('construct_wagtail_edit_bird'):
+    # TODO: Remove in 1.1 release
+    run_deprecated_edit_bird_hook(request, items)
+
+    for fn in hooks.get_hooks('construct_wagtail_userbar'):
         fn(request, items)
 
     # Render the items
@@ -50,3 +60,13 @@ def for_moderation(request, revision_id):
     return render(request, 'wagtailadmin/userbar/base.html', {
         'items': rendered_items,
     })
+
+
+def run_deprecated_edit_bird_hook(request, items):
+    for fn in hooks.get_hooks('construct_wagtail_edit_bird'):
+        fn(request, items)
+
+        warnings.warn(
+            "The 'construct_wagtail_edit_bird' hook has been renamed to 'construct_wagtail_userbar'."
+            "Please update function '%s' in '%s'." % (fn.__name__, fn.__module__), RemovedInWagtail11Warning
+        )