Merge branch 'takeflight-feature/admin-hook-decorator'

CHANGELOG.txt

@@ -1,6 +1,10 @@
 Changelog
 =========
 
+0.5 (xx.xx.20xx)
+~~~~~~~~~~~~~~~~
+ * Added decorator syntax for hooks
+
 0.4.1 (14.07.2014)
 ~~~~~~~~~~~~~~~~~~
  * ElasticSearch backend now respects the backward-compatible URLS configuration setting, in addition to HOSTS

docs/editing_api.rst

@@ -392,15 +392,28 @@ Admin Hooks
 
 On loading, Wagtail will search for any app with the file ``wagtail_hooks.py`` and execute the contents. This provides a way to register your own functions to execute at certain points in Wagtail's execution, such as when a ``Page`` object is saved or when the main menu is constructed.
 
-Registering functions with a Wagtail hook follows the following pattern:
+.. versionadded:: 0.5
+  Decorator syntax was added in 0.5; earlier versions only supported ``hooks.register`` as an ordinary function call.
+
+Registering functions with a Wagtail hook is done through the ``@hooks.register`` decorator:
 
 .. code-block:: python
 
   from wagtail.wagtailcore import hooks
 
-  hooks.register('hook', function)
+  @hooks.register('name_of_hook')
+  def my_hook_function(arg1, arg2...)
+      # your code here
 
-Where ``'hook'`` is one of the following hook strings and ``function`` is a function you've defined to handle the hook.
+
+Alternatively, ``hooks.register`` can be called as an ordinary function, passing in the name of the hook and a handler function defined elsewhere:
+
+.. code-block:: python
+
+  hooks.register('name_of_hook', my_hook_function)
+
+
+The available hooks are:
 
 .. _before_serve_page:
 
@@ -413,11 +426,11 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
 
     from wagtail.wagtailcore import hooks
 
+    @hooks.register('before_serve_page')
     def block_googlebot(page, request, serve_args, serve_kwargs):
         if request.META.get('HTTP_USER_AGENT') == 'GoogleBot':
             return HttpResponse("<h1>bad googlebot no cookie</h1>")
 
-    hooks.register('before_serve_page', block_googlebot)
 
 .. _construct_wagtail_edit_bird:
 
@@ -433,10 +446,10 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
         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')
     def add_puppy_link_item(request, items):
       return items.append( UserbarPuppyLinkItem() )
 
-    hooks.register('construct_wagtail_edit_bird', add_puppy_link_item)
 
 .. _construct_homepage_panels:
 
@@ -459,10 +472,10 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
         </section>
         """)
 
+    @hooks.register('construct_homepage_panels')
     def add_another_welcome_panel(request, panels):
       return panels.append( WelcomePanel() )
 
-    hooks.register('construct_homepage_panels', add_another_welcome_panel)
 
 .. _after_create_page:
 
@@ -475,9 +488,10 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
 
     from wagtail.wagtailcore import hooks
 
+    @hooks.register('after_create_page')
     def do_after_page_create(request, page):
       return HttpResponse("Congrats on making content!", content_type="text/plain")
-    hooks.register('after_create_page', do_after_page_create)
+
 
 .. _after_edit_page:
 
@@ -508,11 +522,11 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
         "I have approximate knowledge of many things!", \
         content_type="text/plain")
 
+    @hooks.register('register_admin_urls')
     def urlconf_time():
       return [
         url(r'^how_did_you_almost_know_my_name/$', admin_view, name='frank' ),
       ]
-    hooks.register('register_admin_urls', urlconf_time)
 
 .. _construct_main_menu:
 
@@ -526,11 +540,11 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
     from wagtail.wagtailcore import hooks
     from wagtail.wagtailadmin.menu import MenuItem
 
+    @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)
       )
-    hooks.register('construct_main_menu', construct_main_menu)
 
 
 .. _insert_editor_js:
@@ -545,6 +559,7 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
 
     from wagtail.wagtailcore import hooks
 
+    @hooks.register('insert_editor_js')
     def editor_js():
       js_files = [
         'demo/js/hallo-plugins/hallo-demo-plugin.js',
@@ -559,7 +574,7 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
         </script>
         """
       )
-    hooks.register('insert_editor_js', editor_js)
+
 
 .. _insert_editor_css:
 
@@ -573,11 +588,11 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
 
     from wagtail.wagtailcore import hooks
 
+    @hooks.register('insert_editor_css')
     def editor_css():
       return format_html('<link rel="stylesheet" href="' \
       + settings.STATIC_URL \
       + 'demo/css/vendor/font-awesome/css/font-awesome.min.css">')
-    hooks.register('insert_editor_css', editor_css)
 
 .. _construct_whitelister_element_rules:
 
@@ -595,12 +610,12 @@ Where ``'hook'`` is one of the following hook strings and ``function`` is a func
     from wagtail.wagtailcore import hooks
     from wagtail.wagtailcore.whitelist import attribute_rule, check_url, allow_without_attributes
 
+    @hooks.register('construct_whitelister_element_rules')
     def whitelister_element_rules():
         return {
             'blockquote': allow_without_attributes,
             'a': attribute_rule({'href': check_url, 'target': True}),
         }
-    hooks.register('construct_whitelister_element_rules', whitelister_element_rules)
 
 
 Image Formats in the Rich Text Editor

docs/releases/0.5.rst

@@ -14,6 +14,19 @@ Whats new
 Minor features
 ~~~~~~~~~~~~~~
 
+Core
+----
+
+ * Hooks can now be defined using decorator syntax:
+
+  .. code-block:: python
+
+    @hooks.register('construct_main_menu')
+    def construct_main_menu(request, menu_items):
+        menu_items.append(
+            MenuItem('Kittens!', '/kittens/', classnames='icon icon-folder-inverse', order=1000)
+        )
+
 
 Bug fixes
 ~~~~~~~~~

wagtail/contrib/wagtailstyleguide/wagtail_hooks.py

@@ -8,15 +8,15 @@ from wagtail.wagtailadmin.menu import MenuItem
 from . import views
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^styleguide/$', views.index, name='wagtailstyleguide'),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     menu_items.append(
         MenuItem(_('Styleguide'), urlresolvers.reverse('wagtailstyleguide'), classnames='icon icon-image', order=1000)
     )
-hooks.register('construct_main_menu', construct_main_menu)

wagtail/tests/wagtail_hooks.py

@@ -3,14 +3,17 @@ from django.http import HttpResponse
 from wagtail.wagtailcore import hooks
 from wagtail.wagtailcore.whitelist import attribute_rule, check_url, allow_without_attributes
 
+
+# Register one hook using decorators...
+@hooks.register('insert_editor_css')
 def editor_css():
     return """<link rel="stylesheet" href="/path/to/my/custom.css">"""
-hooks.register('insert_editor_css', editor_css)
 
 
 def editor_js():
     return """<script src="/path/to/my/custom.js"></script>"""
 hooks.register('insert_editor_js', editor_js)
+# And the other using old-style function calls
 
 
 def whitelister_element_rules():

wagtail/wagtailcore/hooks.py

@@ -7,13 +7,26 @@ except ImportError:
 
 _hooks = {}
 
-# TODO: support 'register' as a decorator:
-#    @hooks.register('construct_main_menu')
-#    def construct_main_menu(menu_items):
-#        ...
 
+def register(hook_name, fn=None):
+    """
+    Register hook for ``hook_name``. Can be used as a decorator::
+
+        @register('hook_name')
+        def my_hook(...):
+            pass
+
+    or as a function call::
+
+        def my_hook(...):
+            pass
+        register('hook_name', my_hook)
+    """
+
+    # Pretend to be a decorator if fn is not supplied
+    if fn is None:
+        return lambda fn: register(hook_name, fn)
 
-def register(hook_name, fn):
     if hook_name not in _hooks:
         _hooks[hook_name] = []
     _hooks[hook_name].append(fn)

wagtail/wagtailcore/wagtail_hooks.py

@@ -2,6 +2,7 @@ from django.core.urlresolvers import reverse
 
 from wagtail.wagtailcore import hooks
 
+@hooks.register('before_serve_page')
 def check_view_restrictions(page, request, serve_args, serve_kwargs):
     """
     Check whether there are any view restrictions on this page which are
@@ -21,5 +22,3 @@ def check_view_restrictions(page, request, serve_args, serve_kwargs):
                     initial={'return_url': request.get_full_path()})
                 action_url = reverse('wagtailcore_authenticate_with_password', args=[restriction.id, page.id])
                 return page.serve_password_required_response(request, form, action_url)
-
-hooks.register('before_serve_page', check_view_restrictions)

wagtail/wagtaildocs/wagtail_hooks.py

@@ -10,21 +10,22 @@ from wagtail.wagtailadmin.menu import MenuItem
 from wagtail.wagtaildocs import admin_urls
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^documents/', include(admin_urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     if request.user.has_perm('wagtaildocs.add_document'):
         menu_items.append(
             MenuItem(_('Documents'), urlresolvers.reverse('wagtaildocs_index'), classnames='icon icon-doc-full-inverse', order=400)
         )
-hooks.register('construct_main_menu', construct_main_menu)
 
 
+@hooks.register('insert_editor_js')
 def editor_js():
     js_files = [
         'wagtaildocs/js/hallo-plugins/hallo-wagtaildoclink.js',
@@ -42,4 +43,3 @@ def editor_js():
         """,
         urlresolvers.reverse('wagtaildocs_chooser')
     )
-hooks.register('insert_editor_js', editor_js)

wagtail/wagtailembeds/wagtail_hooks.py

@@ -7,13 +7,14 @@ from wagtail.wagtailcore import hooks
 from wagtail.wagtailembeds import urls
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^embeds/', include(urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('insert_editor_js')
 def editor_js():
     return format_html("""
             <script src="{0}{1}"></script>
@@ -26,4 +27,3 @@ def editor_js():
         'wagtailembeds/js/hallo-plugins/hallo-wagtailembeds.js',
         urlresolvers.reverse('wagtailembeds_chooser')
     )
-hooks.register('insert_editor_js', editor_js)

wagtail/wagtailforms/wagtail_hooks.py

@@ -9,20 +9,20 @@ from wagtail.wagtailadmin.menu import MenuItem
 from wagtail.wagtailforms import urls
 from wagtail.wagtailforms.models import get_forms_for_user
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^forms/', include(urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     # show this only if the user has permission to retrieve submissions for at least one form
     if get_forms_for_user(request.user).exists():
         menu_items.append(
             MenuItem(_('Forms'), urlresolvers.reverse('wagtailforms_index'), classnames='icon icon-form', order=700)
         )
-hooks.register('construct_main_menu', construct_main_menu)
 
+@hooks.register('insert_editor_js')
 def editor_js():
     return """<script src="%swagtailforms/js/page-editor.js"></script>""" % settings.STATIC_URL
-hooks.register('insert_editor_js', editor_js)

wagtail/wagtailimages/wagtail_hooks.py

@@ -10,21 +10,22 @@ from wagtail.wagtailadmin.menu import MenuItem
 from wagtail.wagtailimages import urls
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^images/', include(urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     if request.user.has_perm('wagtailimages.add_image'):
         menu_items.append(
             MenuItem(_('Images'), urlresolvers.reverse('wagtailimages_index'), classnames='icon icon-image', order=300)
         )
-hooks.register('construct_main_menu', construct_main_menu)
 
 
+@hooks.register('insert_editor_js')
 def editor_js():
     js_files = [
         'wagtailimages/js/hallo-plugins/hallo-wagtailimage.js',
@@ -42,4 +43,3 @@ def editor_js():
         """,
         urlresolvers.reverse('wagtailimages_chooser')
     )
-hooks.register('insert_editor_js', editor_js)

wagtail/wagtailredirects/wagtail_hooks.py

@@ -8,17 +8,17 @@ from wagtail.wagtailredirects import urls
 from wagtail.wagtailadmin.menu import MenuItem
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^redirects/', include(urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     # TEMPORARY: Only show if the user is a superuser
     if request.user.is_superuser:
         menu_items.append(
             MenuItem(_('Redirects'), urlresolvers.reverse('wagtailredirects_index'), classnames='icon icon-redirect', order=800)
         )
-hooks.register('construct_main_menu', construct_main_menu)

wagtail/wagtailsearch/wagtail_hooks.py

@@ -8,17 +8,17 @@ from wagtail.wagtailsearch.urls import admin as admin_urls
 from wagtail.wagtailadmin.menu import MenuItem
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^search/', include(admin_urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     # TEMPORARY: Only show if the user is a superuser
     if request.user.is_superuser:
         menu_items.append(
             MenuItem(_('Editors picks'), urlresolvers.reverse('wagtailsearch_editorspicks_index'), classnames='icon icon-pick', order=900)
         )
-hooks.register('construct_main_menu', construct_main_menu)

wagtail/wagtailsnippets/wagtail_hooks.py

@@ -11,21 +11,22 @@ from wagtail.wagtailsnippets import urls
 from wagtail.wagtailsnippets.permissions import user_can_edit_snippets
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^snippets/', include(urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     if user_can_edit_snippets(request.user):
         menu_items.append(
             MenuItem(_('Snippets'), urlresolvers.reverse('wagtailsnippets_index'), classnames='icon icon-snippet', order=500)
         )
-hooks.register('construct_main_menu', construct_main_menu)
 
 
+@hooks.register('insert_editor_js')
 def editor_js():
     return format_html("""
             <script src="{0}{1}"></script>
@@ -35,4 +36,3 @@ def editor_js():
         'wagtailsnippets/js/snippet-chooser.js',
         urlresolvers.reverse('wagtailsnippets_choose_generic')
     )
-hooks.register('insert_editor_js', editor_js)

wagtail/wagtailusers/wagtail_hooks.py

@@ -8,16 +8,16 @@ from wagtail.wagtailadmin.menu import MenuItem
 from wagtail.wagtailusers import urls
 
 
+@hooks.register('register_admin_urls')
 def register_admin_urls():
     return [
         url(r'^users/', include(urls)),
     ]
-hooks.register('register_admin_urls', register_admin_urls)
 
 
+@hooks.register('construct_main_menu')
 def construct_main_menu(request, menu_items):
     if request.user.has_module_perms('auth'):
         menu_items.append(
             MenuItem(_('Users'), urlresolvers.reverse('wagtailusers_index'), classnames='icon icon-user', order=600)
         )
-hooks.register('construct_main_menu', construct_main_menu)