Include custom permissions hook documentation

CHANGELOG.txt

@@ -29,7 +29,7 @@ Changelog
  * Add `label_format` attribute to customise the label shown for a collapsed StructBlock (Matt Westcott)
  * User Group permissions will now show all custom object permissions in one row instead of a separate table (Kamil Marut)User Group permissions editing in the admin will now show all custom object permissions in one row instead of a separate table (Kamil Marut)
  * Create `ImageFileMixin` to extract shared file handling methods from `AbstractImage` and `AbstractRendition` (Fabien Le Frapper)
- * Add `before_delete_page` example to Hooks documentation (Jane Liu)
+ * Add `before_delete_page` and `register_permissions` examples to Hooks documentation (Jane Liu, Daniel Fairhead)
  * Add clarity to modeladmin template override behaviour in the documentation (Joe Howard, Dan Swain)
  * Fix: Delete button is now correct colour on snippets and modeladmin listings (Brandon Murch)
  * Fix: Ensure that StreamBlock / ListBlock-level validation errors are counted towards error counts (Matt Westcott)

docs/reference/hooks.rst

@@ -389,6 +389,21 @@ More details about the options that are available can be found at :doc:`/extendi
 
   Return a QuerySet of ``Permission`` objects to be shown in the Groups administration area.
 
+  .. code-block:: python
+
+      from django.contrib.auth.models import Permission
+      from wagtail.core import hooks
+
+
+      @hooks.register('register_permissions')
+      def register_permissions():
+          app = 'blog'
+          model = 'extramodelset'
+
+          return Permission.objects.filter(content_type__app_label=app, codename__in=[
+              f"view_{model}", f"add_{model}", f"change_{model}", f"delete_{model}"
+          ])
+
 
 .. _filter_form_submissions_for_user:
 

docs/releases/2.15.rst

@@ -40,7 +40,7 @@ Other features
  * Add ``label_format`` attribute to customise the label shown for a collapsed StructBlock (Matt Westcott)
  * User Group permissions editing in the admin will now show all custom object permissions in one row instead of a separate table (Kamil Marut)
  * Create ``ImageFileMixin`` to extract shared file handling methods from ``AbstractImage`` and ``AbstractRendition`` (Fabien Le Frapper)
- * Add ``before_delete_page`` example to Hooks documentation (Jane Liu)
+ * Add ``before_delete_page`` and ``register_permissions`` examples to Hooks documentation (Jane Liu, Daniel Fairhead)
  * Add clarity to modeladmin template override behaviour in the documentation (Joe Howard, Dan Swain)
 
 Bug fixes

docs/topics/permissions.rst

@@ -44,3 +44,9 @@ The permission rules for images and documents work on a similar basis to pages.
 Access to specific sets of images and documents can be controlled by setting up *collections*. By default all images and documents belong to the 'root' collection, but new collections can be created through the Settings -> Collections area of the admin interface. Permissions set on 'root' apply to all collections, so a user with 'edit' permission for images on root can edit all images; permissions set on other collections apply to that collection only.
 
 The 'choose' permission for images and documents determines which collections are visible within the chooser interface used to select images and document links for insertion into pages (and other models, such as snippets). Typically, all users are granted choose permission for all collections, allowing them to use any uploaded image or document on pages they create, but this permission can be limited to allow creating collections that are only available for use by specific groups.
+
+
+Displaying custom permissions in the admin
+------------------------------------------
+
+Most permissions will automatically show up in the wagtail admin Group edit form, however, you can also add them using the ``register_permissions`` hook (see :ref:`register_permissions`).