Additional documentation for next_url

CHANGELOG.txt

@@ -12,6 +12,7 @@ Changelog
  * Added filtering to locked pages report (Karl Hobley)
  * Adds ability to view a group's users via standalone admin URL and a link to this on the group edit view (Karran Besen)
  * Redirect to previous url when deleting/copying/unpublish a page and modify this url via the relevant hooks (Ascani Carlo)
+ * Added `next_url` keyword argument on `register_page_listing_buttons` and `register_page_listing_more_buttons` hooks (Ascani Carlo, Matt Westcott, LB (Ben Johnston))
  * `AbstractEmailForm` will use `SHORT_DATETIME_FORMAT` and `SHORT_DATE_FORMAT` Django settings to format date/time values in email (Haydn Greatnews)
  * `AbstractEmailForm` now has a separate method (`render_email`) to build up email content on submission emails (Haydn Greatnews)
  * Add `pre_page_move` and `post_page_move` signals (Andy Babic)

docs/reference/contrib/modeladmin/tips_and_tricks/reversing_urls.rst

@@ -54,7 +54,7 @@ to allow a single author to be specified for each post.
     author_modeladmin = AuthorModelAdmin()
 
     @hooks.register('register_page_listing_buttons')
-    def add_author_edit_buttons(page, page_perms, is_parent=False):
+    def add_author_edit_buttons(page, page_perms, is_parent=False, next_url=None):
         """
         For pages that have an author, add an additional button to the page listing,
         linking to the 'edit' page for that author.

docs/reference/hooks.rst

@@ -878,6 +878,13 @@ Page explorer
             priority=10
         )
 
+  The arguments passed to the hook are as follows:
+
+  * ``page`` - the page object to generate the button for
+  * ``page_perms`` - a ``PagePermissionTester`` object that can be queried to determine the current user's permissions on the given page
+  * ``is_parent`` - if true, this button is being rendered for the parent page being displayed at the top of the listing
+  * ``next_url`` - the URL that the linked action should redirect back to on completion of the action, if the view supports it
+
   The ``priority`` argument controls the order the buttons are displayed in. Buttons are ordered from low to high priority, so a button with ``priority=10`` will be displayed before a button with ``priority=20``.
 
 
@@ -902,6 +909,13 @@ Page explorer
             priority=60
         )
 
+  The arguments passed to the hook are as follows:
+
+  * ``page`` - the page object to generate the button for
+  * ``page_perms`` - a ``PagePermissionTester`` object that can be queried to determine the current user's permissions on the given page
+  * ``is_parent`` - if true, this button is being rendered for the parent page being displayed at the top of the listing
+  * ``next_url`` - the URL that the linked action should redirect back to on completion of the action, if the view supports it
+
   The ``priority`` argument controls the order the buttons are displayed in the dropdown. Buttons are ordered from low to high priority, so a button with ``priority=10`` will be displayed before a button with ``priority=60``.
 
 
@@ -920,18 +934,19 @@ Buttons with dropdown lists
     from wagtail.admin import widgets as wagtailadmin_widgets
 
     @hooks.register('register_page_listing_buttons')
-    def page_custom_listing_buttons(page, page_perms, is_parent=False):
+    def page_custom_listing_buttons(page, page_perms, is_parent=False, next_url=None):
         yield wagtailadmin_widgets.ButtonWithDropdownFromHook(
             'More actions',
             hook_name='my_button_dropdown_hook',
             page=page,
             page_perms=page_perms,
             is_parent=is_parent,
+            next_url=next_url,
             priority=50
         )
 
     @hooks.register('my_button_dropdown_hook')
-    def page_custom_listing_more_buttons(page, page_perms, is_parent=False):
+    def page_custom_listing_more_buttons(page, page_perms, is_parent=False, next_url=None):
         if page_perms.can_move():
             yield wagtailadmin_widgets.Button('Move', reverse('wagtailadmin_pages:move', args=[page.id]), priority=10)
         if page_perms.can_delete():

docs/releases/2.10.rst

@@ -30,6 +30,7 @@ Other features
  * Added filtering to locked pages report (Karl Hobley)
  * Adds ability to view a group's users via standalone admin URL and a link to this on the group edit view (Karran Besen)
  * Redirect to previous url when deleting/copying/unpublish a page and modify this url via the relevant hooks (Ascani Carlo)
+ * Added ``next_url`` keyword argument on ``register_page_listing_buttons`` and ``register_page_listing_more_buttons`` hooks (Ascani Carlo, Matt Westcott, LB (Ben Johnston))
  * ``AbstractEmailForm`` will use ``SHORT_DATETIME_FORMAT`` and ``SHORT_DATE_FORMAT`` Django settings to format date/time values in email (Haydn Greatnews)
  * ``AbstractEmailForm`` now has a separate method (``render_email``) to build up email content on submission emails. See :ref:`form_builder_render_email`. (Haydn Greatnews)
  * Add ``pre_page_move`` and ``post_page_move`` signals. (Andy Babic)
@@ -109,7 +110,27 @@ In previous releases, rich text values were enclosed in a ``<div class="rich-tex
 To restore the old behaviour, see :ref:`legacy_richtext`.
 
 
-Hooks functions ``register_page_listing_buttons`` & ``register_page_listing_more_buttons``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+New ``next_url`` keyword argument on ``register_page_listing_buttons`` and ``register_page_listing_more_buttons`` hooks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Page listing button hook functions now accept an additional kwarg ``next_url``. Please update your hook function definitions to accept the new ``next_url`` kwarg.
+Functions registered through the hooks ``register_page_listing_buttons`` and ``register_page_listing_more_buttons`` now accept an additional keyword argument ``next_url``. A hook function currently written as:
+
+.. code-block:: python
+
+    @hooks.register('register_page_listing_buttons')
+    def page_listing_more_buttons(page, page_perms, is_parent=False):
+        yield wagtailadmin_widgets.Button(
+            'My button', '/goes/to/a/url/', priority=60
+        )
+
+should now become:
+
+.. code-block:: python
+
+    @hooks.register('register_page_listing_buttons')
+    def page_listing_more_buttons(page, page_perms, is_parent=False, next_url=None):
+        yield wagtailadmin_widgets.Button(
+            'My button', '/goes/to/a/url/', priority=60
+        )
+
+The ``next_url`` argument specifies a URL to redirect back to after the action is complete, and can be passed as a query parameter to the linked URL, if the view supports it.