Add better docs & cross-linking for how PanelGroup permission kwarg works

Adds more details on how to use the feature added in #8846

CHANGELOG.txt

@@ -593,6 +593,7 @@ Changelog
  * Docs: Document potential data loss for BaseLogEntry migration in 3.0 (Sage Abdullah)
  * Docs: Add documentation for the reference index mechanism (Daniel Kirkham)
  * Docs: Remove confusing `SettingsPanel` reference in the page editing `TabbedInterface` example as `SettingsPanel` no longer shows anything as of 4.1 (Kenny Wolf, Julian Bigler)
+ * Docs: Add more extensive documentation for the `permission` kwarg support in Panels (LB (Ben) Johnston)
  * Maintenance: Switch to using Willow instead of Pillow for images (Darrel O'Pry)
  * Maintenance: Remove unsquashed `testapp` migrations (Matt Westcott)
  * Maintenance: Upgrade to Node 18 for frontend build tooling (LB (Ben) Johnston)

docs/advanced_topics/customisation/page_editing_interface.md

@@ -29,6 +29,31 @@ class BlogPage(Page):
     ])
 ```
 
+Permissions can be set using `permission` on the `ObjectList` to restrict entire groups of panels to specific users.
+
+```python
+from wagtail.admin.panels import TabbedInterface, ObjectList
+
+class FundingPage(Page):
+    # field definitions omitted
+
+    shared_panels = [
+        FieldPanel('title', classname="title"),
+        FieldPanel('date'),
+        FieldPanel('body'),
+    ]
+    private_panels = [
+        FieldPanel('approval'),
+    ]
+
+    edit_handler = TabbedInterface([
+        ObjectList(shared_panels, heading='Details'),
+        ObjectList(private_panels, heading='Admin only', permission="superuser"),
+    ])
+```
+
+For more details on how to work with `Panel`s and `PanelGroup`, see [](forms_panels_overview).
+
 (rich_text)=
 
 ## Rich Text (HTML)

docs/extending/forms.md

@@ -56,6 +56,8 @@ class WagtailVideosAppConfig(AppConfig):
 
 Wagtail's edit views for pages, snippets and ModelAdmin use `WagtailAdminModelForm` as standard, so this change will take effect across the Wagtail admin; a foreign key to `Video` on a page model will automatically use the `VideoChooser` widget, with no need to specify this explicitly.
 
+(forms_panels_overview)=
+
 ## Panels
 
 Panels (also known as edit handlers until Wagtail 3.0) are Wagtail's mechanism for specifying the content and layout of a model form without having to write a template. They are used for the editing interface for pages and snippets, as well as the [ModelAdmin](/reference/contrib/modeladmin/index) and [site settings](/reference/contrib/settings) contrib modules.
@@ -66,6 +68,7 @@ A view performs the following steps to render a model form through the panels me
 
 -   The top-level panel object for the model is retrieved. Usually this is done by looking up the model's `edit_handler` property and falling back on an `ObjectList` consisting of children given by the model's `panels` property. However, it may come from elsewhere - for example, snippets can define their panels via the `SnippetViewSet` class.
 -   If the `PanelsGroup`s permissions do not allow a user to see this panel, then nothing more will be done.
+    -   This can be modified using the `permission` keyword argument, see examples of this usage in [](customising_the_tabbed_interface) and [](panels_permissions).
 -   The view calls `bind_to_model` on the top-level panel, passing the model class, and this returns a clone of the panel with a `model` property. As part of this process the `on_model_bound` method is invoked on each child panel, to allow it to perform additional initialisation that requires access to the model (for example, this is where `FieldPanel` retrieves the model field definition).
 -   The view then calls `get_form_class` on the top-level panel to retrieve a ModelForm subclass that can be used to edit the model. This proceeds as follows:
     -   Retrieve a base form class from the model's `base_form_class` property, falling back on `wagtail.admin.forms.WagtailAdminModelForm`

docs/reference/pages/panels.md

@@ -347,6 +347,31 @@ To make input or chooser selection mandatory for a field, add [`blank=False`](dj
 
 Without a top-level panel definition, a `FieldPanel` will be constructed for each field in your model. If you intend to hide a field on the Wagtail page editor, define the field with [`editable=False`](django.db.models.Field.editable). If a field is not present in the panels definition, it will also be hidden.
 
+(panels_permissions)=
+
+### Permissions
+
+Most panels can accept a `permission` kwarg, allowing the set of panels or specific panels to be restricted to a set permissions.
+See [](permissions_overview) for details about working with permissions in Wagtail.
+
+In this example, 'notes' will be visible to all editors, 'cost' and 'details' will only be visible to those with the `submit` permission, 'budget approval' will be visible to super users only. Note that super users will have access to all fields.
+
+```python
+    content_panels = [
+        FieldPanel("notes"),
+        MultiFieldPanel(
+            [
+                FieldPanel("cost"),
+                FieldPanel("details"),
+            ],
+            heading="Budget details",
+            classname="collapsed",
+            permission="submit"
+        ),
+        FieldPanel("budget_approval", permission="superuser"),
+    ]
+```
+
 (panels_attrs)=
 
 ### Additional HTML attributes

docs/releases/5.2.md

@@ -78,6 +78,7 @@ depth: 1
  * Mention the need to install `python3-venv` on Ubuntu (Brian Mugo)
  * Document the use of the Google developer documentation style guide in documentation (Damilola Oladele)
  * Fix Inconsistent URL Format in Getting Started tutorial (Olumide Micheal)
+ * Add more extensive documentation for the `permission` kwarg support in Panels (LB (Ben) Johnston)
 
 ### Maintenance
 

docs/topics/permissions.md

@@ -67,6 +67,8 @@ Custom permissions starting with `add_`, `change_` or `delete_` are not currentl
 
 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 [](register_permissions)).
 
-## `FieldPanel` permissions
+## `FieldPanel` and `PanelGroup` permissions
 
 Permissions can be used to restrict access to fields within the editor interface. See `permission` on [FieldPanel](field_panel).
+
+Permissions can be used to restrict groups of panels via the `permission` keyword argument on `PanelGroup` classes (`TabbedInterface`, `ObjectList`, `FieldRowPanel`, `MultiFieldPanel`). See how `PanelGroup` usage can be customised [](forms_panels_overview).