Added requested changes

docs/reference/pages/panels.md

@@ -78,12 +78,14 @@ Here are some Wagtail-specific types that you might include as fields in your mo
         Allows a panel to be selectively shown to users with sufficient permission. Accepts a permission codename such as ``'myapp.change_blog_category'`` - if the logged-in user does not have that permission, the panel will be omitted from the form. Similar to ``FieldPanel.permission``.
 ```
 
+(inline_panels)=
+
 ### InlinePanel
 
 ```{eval-rst}
 .. class:: InlinePanel(relation_name, panels=None, classname='', heading='', label='', help_text='', min_num=None, max_num=None)
 
-    This panel allows for the creation of a "cluster" of related objects over a join to a separate model, such as a list of related links or slides to an image carousel.
+    This panel allows for the creation of a "cluster" of related objects over a join to a separate model, such as a list of related links or slides to an image carousel. For a full explanation on the usage of ``InlinePanel``, see :ref:`inline_models`.
 
     .. attribute:: InlinePanel.relation_name
 
@@ -123,6 +125,47 @@ Here are some Wagtail-specific types that you might include as fields in your mo
 
 Note that you can use `classname="collapsed"` to load the panel collapsed under its heading in order to save space in the Wagtail admin.
 
+
+(multiple_chooser_panel)=
+
+### MultipleChooserPanel
+
+```{versionadded} 4.2
+The `MultipleChooserPanel` panel type was added.
+```
+
+```{eval-rst}
+.. class:: MultipleChooserPanel(relation_name, chooser_field_name=None, panels=None, classname='', heading='', label='', help_text='', min_num=None, max_num=None)
+```
+
+This is a variant of `InlinePanel` that improves the editing experience when the main feature of the child panel is a chooser for a `ForeignKey` relation (usually to an image, document, snippet or another page). Rather than the "Add" button inserting a new form to be filled in individually, it immediately opens up the chooser interface for that related object, in a mode that allows multiple items to be selected. The user is then returned to the main edit form with the appropriate number of child panels added and pre-filled.
+
+`MultipleChooserPanel` accepts an additional required argument `chooser_field_name`, specifying the name of the `ForeignKey` relation that the chooser is linked to.
+
+For example, given a child model that provies a gallery of images on `BlogPage`:
+
+```python
+class BlogPageGalleryImage(Orderable):
+    page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name='gallery_images')
+    image = models.ForeignKey(
+        'wagtailimages.Image', on_delete=models.CASCADE, related_name='+'
+    )
+    caption = models.CharField(blank=True, max_length=250)
+
+    panels = [
+        FieldPanel('image'),
+        FieldPanel('caption'),
+    ]
+```
+
+The `MultipleChooserPanel` definition on `BlogPage` would be:
+
+```python
+        MultipleChooserPanel(
+            'gallery_images', label="Gallery images", chooser_field_name="image"
+        )
+```
+
 ### FieldRowPanel
 
 ```{eval-rst}
@@ -300,43 +343,3 @@ To make input or chooser selection mandatory for a field, add [`blank=False`](dj
 
 Without a panel definition, a default form field (without label) will be used to represent your fields. If you intend to hide a field on the Wagtail page editor, define the field with [`editable=False`](django.db.models.Field.editable).
 
-
-(multiple_chooser_panel)=
-
-### MultipleChooserPanel
-
-```{versionadded} 4.2
-The `MultipleChooserPanel` panel type was added.
-```
-
-```{eval-rst}
-.. class:: MultipleChooserPanel(relation_name, chooser_field_name=None, panels=None, classname='', heading='', label='', help_text='', min_num=None, max_num=None)
-```
-
-This is a variant of `InlinePanel` that improves the editing experience when the main feature of the child panel is a chooser for a `ForeignKey` relation (usually to an image, document, snippet or another page). Rather than the "Add" button inserting a new form to be filled in individually, it immediately opens up the chooser interface for that related object, in a mode that allows multiple items to be selected. The user is then returned to the main edit form with the appropriate number of child panels added and pre-filled.
-
-`MultipleChooserPanel` accepts an additional required argument `chooser_field_name`, specifying the name of the `ForeignKey` relation that the chooser is linked to.
-
-For example, given a child model that provies a gallery of images on `BlogPage`:
-
-```python
-class BlogPageGalleryImage(Orderable):
-    page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name='gallery_images')
-    image = models.ForeignKey(
-        'wagtailimages.Image', on_delete=models.CASCADE, related_name='+'
-    )
-    caption = models.CharField(blank=True, max_length=250)
-
-    panels = [
-        FieldPanel('image'),
-        FieldPanel('caption'),
-    ]
-```
-
-the `MultipleChooserPanel` definition on `BlogPage` would be:
-
-```python
-        MultipleChooserPanel(
-            'gallery_images', label="Gallery images", chooser_field_name="image"
-        )
-```

docs/topics/pages.md

@@ -327,6 +327,8 @@ class BlogPage(Page):
         })
 ```
 
+(inline_models)=
+
 ## Inline models
 
 Wagtail allows the nesting of other models within a page. This is useful for creating repeated fields, such as related links or items to display in a carousel. Inline model content is also versioned with the rest of the page.
@@ -366,7 +368,21 @@ class BlogPageRelatedLink(Orderable):
     ]
 ```
 
-In the above example, the `BlogPageRelatedLink` model can also be refactored into an abstract model:
+To add this to the admin interface, use the `InlinePanel` edit panel class:
+
+```python
+content_panels = [
+    ...
+
+    InlinePanel('related_links', label="Related links"),
+]
+```
+
+The first argument must match the value of the `related_name` attribute of the `ParentalKey`.
+For a brief description of parameters taken by `InlinePanel`, see {ref}`inline_panels`.
+
+## Re-using inline models across multiple page types
+In the above example, related links are defined as a child object on the `BlogPage` page type. Often, the same kind of inline child object will appear on several page types, and in these cases, it's undesirable to repeat the entire model definition. This can be avoided by refactoring the common fields into an abstract model:
 
 ```python
 from django.db import models
@@ -386,26 +402,28 @@ class RelatedLink(models.Model):
     class Meta:
         abstract = True
 
-# The real model which combines the abstract model
+# The real model which extends the abstract model with a ParentalKey relation back to the page model.
+# This can be repeated for each page type where the relation is to be added
+# (for example, NewsPageRelatedLink, PublicationPageRelatedLink and so on).
 class BlogPageRelatedLink(Orderable,RelatedLink):
-    page = ParentalKey("wagtailcore.Page", on_delete=models.CASCADE, related_name='related_links')
-
+    page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name='related_links')
 ```
 
-Notice the change of `ParentalKey` to `"wagtailcore.Page"` model. The `related_links` relation will be set up on the base Page model, which means it will be available on all page types. Most likely we don't want to use it on all page types (for example, related links are not very useful on a homepage).
-
-To add this to the admin interface, use the {class}`~wagtail.admin.panels.InlinePanel` edit panel class:
+Alternatively, if RelatedLink is going to appear on a significant number of the page types defined in your project, it may be more appropriate to set up a single `RelatedLink` model pointing to the base `wagtailcore.Page` model:
 
 ```python
-content_panels = [
-    ...
-
-    InlinePanel('related_links', label="Related links"),
-]
+class RelatedLink(Orderable):
+    page = ParentalKey("wagtailcore.Page", on_delete=models.CASCADE, related_name='related_links')
+    name = models.CharField(max_length=255)
+    url = models.URLField()
+    panels = [
+        FieldPanel('name'),
+        FieldPanel('url'),
+    ]
 ```
 
-The first argument must match the value of the `related_name` attribute of the `ParentalKey`.
-For a brief description of parameters taken by `InlinePanel`, see [Inline Panel](https://docs.wagtail.org/en/latest/reference/pages/panels.html#inlinepanel) 
+This will then make `related_links` available as a relation across all page types, although it will still only be editable on page types that include the `InlinePanel` in their panel definitions - for other page types, the set of related links will remain empty.
+
 
 ## Working with pages