From 9917d7d2e99d0f0ec90fa0a7b04f149bab2d0792 Mon Sep 17 00:00:00 2001
From: Matt Westcott <matt@west.co.tt>
Date: Tue, 14 Jul 2020 13:31:07 +0100
Subject: [PATCH] Additional documentation for next_url
---
CHANGELOG.txt | 1 +
.../tips_and_tricks/reversing_urls.rst | 2 +-
docs/reference/hooks.rst | 19 +++++++++++--
docs/releases/2.10.rst | 27 ++++++++++++++++---
4 files changed, 43 insertions(+), 6 deletions(-)
diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index 938a099bba..11419c1f63 100644
--- a/CHANGELOG.txt
+++ b/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)
diff --git a/docs/reference/contrib/modeladmin/tips_and_tricks/reversing_urls.rst b/docs/reference/contrib/modeladmin/tips_and_tricks/reversing_urls.rst
index ec403f942d..5417c7eccb 100644
--- a/docs/reference/contrib/modeladmin/tips_and_tricks/reversing_urls.rst
+++ b/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.
diff --git a/docs/reference/hooks.rst b/docs/reference/hooks.rst
index b46ee8bfed..3ef4bf4960 100644
--- a/docs/reference/hooks.rst
+++ b/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():
diff --git a/docs/releases/2.10.rst b/docs/releases/2.10.rst
index 7e093fef0e..0b2e53ede4 100644
--- a/docs/releases/2.10.rst
+++ b/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.