Customising admin views for snippets

Additional customisations to the admin views for each snippet model can be achieved through a custom SnippetViewSet class. This allows you to customise the listing view (e.g. adding custom columns, filters), create a custom menu item, and more.

Before proceeding, ensure that you register the snippet model using register_snippet as a function instead of a decorator, as described in Registering snippets.

For demonstration, consider the following Member model and a MemberFilterSet class:

# 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)

    def get_shirt_size_display(self):
        return self.ShirtSize(self.shirt_size).label

    get_shirt_size_display.admin_order_field = "shirt_size"
    get_shirt_size_display.short_description = "Size description"


class MemberFilterSet(WagtailFilterSet):
    class Meta:
        model = Member
        fields = ["shirt_size"]

And the following is the snippet’s corresponding SnippetViewSet subclass:

from wagtail.admin.panels import FieldPanel
from wagtail.admin.ui.tables import UpdatedAtColumn
from wagtail.snippets.models import register_snippet
from wagtail.snippets.views.snippets import SnippetViewSet

from myapp.models import Member, MemberFilterSet


class MemberViewSet(SnippetViewSet):
    model = Member
    icon = "user"
    list_display = ["name", "shirt_size", "get_shirt_size_display", UpdatedAtColumn()]
    list_per_page = 50
    inspect_view_enabled = True
    admin_url_namespace = "member_views"
    base_url_path = "internal/member"
    filterset_class = MemberFilterSet
    # alternatively, you can use the following instead of filterset_class
    # list_filter = ["shirt_size"]
    # or
    # list_filter = {"shirt_size": ["exact"], "name": ["icontains"]}

    edit_handler = TabbedInterface([
        ObjectList([FieldPanel("name")], heading="Details"),
        ObjectList([FieldPanel("shirt_size")], heading="Preferences"),
    ])

register_snippet(MemberViewSet)

Icon

You can define an icon attribute on the SnippetViewSet to specify the icon that is used across the admin for this snippet type. The icon needs to be registered in the Wagtail icon library. If icon is not set, the default "snippet" icon is used.

URL namespace and base URL path

The admin_url_namespace attribute can be set to use a custom URL namespace for the URL patterns of the views. If unset, it defaults to wagtailsnippets_{app_label}_{model_name}. Meanwhile, setting base_url_path allows you to customise the base URL path relative to the Wagtail admin URL. If unset, it defaults to snippets/app_label/model_name.

If you need further customisations, you can also override the get_admin_url_namespace() and get_admin_base_path() methods to override the namespace and base URL path, respectively.

Similar URL customisations are also possible for the snippet chooser views through chooser_admin_url_namespace, chooser_base_url_path, get_chooser_admin_url_namespace(), and get_chooser_admin_base_path().

Listing view

The list_display attribute can be set to specify the columns shown on the listing view. To customise the number of items to be displayed per page, you can set the list_per_page attribute (or chooser_per_page for the chooser listing).

To customise the base queryset for the listing view, you could override the get_queryset() method. Additionally, the ordering attribute can be used to specify the default ordering of the listing view.

You can add the ability to filter the listing view by defining a list_filter attribute and specifying the list of fields to filter. Wagtail uses the django-filter package under the hood, and this attribute will be passed as django-filter’s FilterSet.Meta.fields attribute. This means you can also pass a dictionary that maps the field name to a list of lookups.

If you would like to make further customisations to the filtering mechanism, you can also use a custom wagtail.admin.filters.WagtailFilterSet subclass by overriding the filterset_class attribute. The list_filter attribute is ignored if filterset_class is set. For more details, refer to django-filter’s documentation.

You can add the ability to export the listing view to a spreadsheet by setting the list_export attribute to specify the columns to be exported. The export_filename attribute can be used to customise the file name of the exported spreadsheet.

New in version 5.1: The ability to export the listing view was added.

Inspect view

New in version 5.1: The ability to enable inspect view was added.

The inspect view is disabled by default, as it’s not often useful for most models. However, if you need a view that enables users to view more detailed information about an instance without the option to edit it, you can enable the inspect view by setting inspect_view_enabled on your SnippetViewSet class.

When inspect view is enabled, an ‘Inspect’ button will automatically appear for each row on the listing view, which takes you to a view that shows a list of field values for that particular snippet.

By default, all ‘concrete’ fields (where the field value is stored as a column in the database table for your model) will be shown. You can customise what values are displayed by specifying the inspect_view_fields or the inspect_view_fields_exclude attributes to your SnippetViewSet class.

Templates

For all views that are used for a snippet model, Wagtail looks for templates in the following directories within your project or app, before resorting to the defaults:

  1. templates/wagtailsnippets/snippets/{app_label}/{model_name}/

  2. templates/wagtailsnippets/snippets/{app_label}/

  3. templates/wagtailsnippets/snippets/

So, to override the template used by the IndexView for example, you could create a new index.html template and put it in one of those locations. For example, if you wanted to do this for a Shirt model in a shirts app, you could add your custom template as shirts/templates/wagtailsnippets/snippets/shirts/shirt/index.html. You could change the wagtailsnippets/snippets/ prefix for the templates by overriding the template_prefix attribute.

For some common views, Wagtail also allows you to override the template used by either specifying the {view_name}_template_name attribute or overriding the get_{view_name}_template() method on the viewset. The following is a list of customisation points for the views: