Document SnippetViewSet and how to customise it

docs/reference/viewsets.md

@@ -71,3 +71,23 @@ Viewsets are Wagtail's mechanism for defining a group of related admin views wit
    .. autoattribute:: creation_tab_label
    .. autoattribute:: search_tab_label
 ```
+
+## SnippetViewSet
+
+```{eval-rst}
+.. autoclass:: wagtail.snippets.views.snippets.SnippetViewSet
+
+   .. autoattribute:: filterset_class
+   .. autoattribute:: index_view_class
+   .. autoattribute:: add_view_class
+   .. autoattribute:: edit_view_class
+   .. autoattribute:: delete_view_class
+   .. autoattribute:: usage_view_class
+   .. autoattribute:: history_view_class
+   .. autoattribute:: revisions_view_class
+   .. autoattribute:: revisions_revert_view_class
+   .. autoattribute:: revisions_compare_view_class
+   .. autoattribute:: unpublish_view_class
+   .. autoattribute:: preview_on_add_view_class
+   .. autoattribute:: preview_on_edit_view_class
+```

docs/topics/snippets.md

@@ -386,3 +386,69 @@ class Advert(ClusterableModel):
 ```
 
 The [documentation on tagging pages](tagging) has more information on how to use tags in views.
+
+
+## Customising snippets admin views
+
+You can customise the admin views for snippets by specifying a custom subclass of {class}`~wagtail.snippets.views.snippets.SnippetViewSet` to `register_snippet`.
+
+This can be done by removing the `@register_snippet` decorator on your model class and calling `register_snippet` (as a function, not a decorator) in your `wagtail_hooks.py` file instead as follows:
+
+```
+register_snippet(MyModel, viewset=MyModelViewSet)
+```
+
+For example, with the following `Member` model:
+
+```python
+# models.py
+from django.db import models
+from wagtail.admin.filters import WagtailFilterSet
+
+
+class Member(models.Model):
+    class ShirtSize(models.TextChoices):
+        SMALL = "S", "Small"
+        MEDIUM = "M", "Medium"
+        LARGE = "L", "Large"
+        EXTRA_LARGE = "XL", "Extra Large"
+
+    name = models.CharField(max_length=255)
+    shirt_size = models.CharField(max_length=5, choices=ShirtSize.choices, default=ShirtSize.MEDIUM)
+
+
+class MemberFilterSet(WagtailFilterSet):
+    class Meta:
+        model = Member
+        fields = ["shirt_size"]
+```
+
+You can add a `filterset_class` to the listing view by defining a subclass of `SnippetViewSet` as below:
+
+```python
+# views.py
+from wagtail.snippets.views.snippets import SnippetViewSet
+
+from myapp.models import MemberFilterSet
+
+
+class MemberViewSet(SnippetViewSet):
+    filterset_class = MemberFilterSet
+```
+
+Then, pass the viewset to the `register_snippet` call.
+
+```python
+# wagtail_hooks.py
+from wagtail.snippets.model import register_snippet
+
+from myapp.models import Member
+from myapp.views import MemberViewSet
+
+
+register_snippet(Member, viewset=MemberViewSet)
+```
+
+The `viewset` parameter of `register_snippet` also accepts a dotted module path to the subclass, e.g. `"myapp.views.MemberViewSet"`.
+
+Various additional attributes are available to customise the viewset - see {class}`~wagtail.snippets.views.snippets.SnippetViewSet`.

wagtail/snippets/views/snippets.py

@@ -676,21 +676,56 @@ class Unpublish(PermissionCheckedMixin, UnpublishView):
 
 
 class SnippetViewSet(ViewSet):
+    """
+    A viewset that instantiates the admin views for snippets.
+    """
+
+    #: A subclass of ``wagtail.admin.filters.WagtailFilterSet``, which is a subclass of `django_filters.FilterSet <https://django-filter.readthedocs.io/en/stable/ref/filterset.html>`_. This will be passed to the ``filterset_class`` attribute of the index view.
     filterset_class = None
+
+    #: The view class to use for the list view; must be a subclass of ``wagtail.snippet.views.snippets.List``.
     index_view_class = List
+
+    #: The view class to use for the create view; must be a subclass of ``wagtail.snippet.views.snippets.Create``.
     add_view_class = Create
+
+    #: The view class to use for the edit view; must be a subclass of ``wagtail.snippet.views.snippets.Edit``.
     edit_view_class = Edit
+
+    #: The view class to use for the delete view; must be a subclass of ``wagtail.snippet.views.snippets.Delete``.
     delete_view_class = Delete
+
+    #: The view class to use for the usage view; must be a subclass of ``wagtail.snippet.views.snippets.Usage``.
     usage_view_class = Usage
+
+    #: The view class to use for the history view; must be a subclass of ``wagtail.snippet.views.snippets.History``.
     history_view_class = History
+
+    #: The view class to use for previewing revisions; must be a subclass of ``wagtail.snippet.views.snippets.RevisionsView``.
     revisions_view_class = RevisionsView
+
+    #: The view class to use for comparing revisions; must be a subclass of ``wagtail.snippet.views.snippets.RevisionsCompare``.
     revisions_compare_view_class = RevisionsCompare
+
+    #: The view class to use for unpublishing a snippet; must be a subclass of ``wagtail.snippet.views.snippets.Unpublish``.
     unpublish_view_class = Unpublish
+
+    #: The view class to use for previewing on the create view; must be a subclass of ``wagtail.snippet.views.snippets.PreviewOnCreate``.
     preview_on_add_view_class = PreviewOnCreate
+
+    #: The view class to use for previewing on the edit view; must be a subclass of ``wagtail.snippet.views.snippets.PreviewOnEdit``.
     preview_on_edit_view_class = PreviewOnEdit
 
     @property
     def revisions_revert_view_class(self):
+        """
+        The view class to use for reverting to a previous revision.
+
+        By default, this class is generated by combining the edit view with
+        ``wagtail.admin.views.generic.mixins.RevisionsRevertMixin``. As a result,
+        this class must be a subclass of ``wagtail.snippet.views.snippets.Edit``
+        and must handle the reversion correctly.
+        """
         revisions_revert_view_class = type(
             "_RevisionsRevert",
             (RevisionsRevertMixin, self.edit_view_class),