Custom page listings¶
Normally, editors navigate through the Wagtail admin interface by following the structure of the page tree. However, this can make it slow to locate a specific page for editing, especially on large sites where pages are organised into a deep hierarchy.
Custom page listings are a way to present a flat list of all pages of a given type, accessed from a menu item in the Wagtail admin menu, with the ability for editors to search and filter this list to find the pages they are interested in. To define a custom page listing, create a subclass of PageListingViewSet
and register it using the register_admin_viewset
hook.
For example, if your site implemented the page type BlogPage
, you could provide a “Blog pages” listing in the Wagtail admin by adding the following definitions to a wagtail_hooks.py
file within the app:
# myapp/wagtail_hooks.py
from wagtail import hooks
from wagtail.admin.viewsets.pages import PageListingViewSet
from myapp.models import BlogPage
class BlogPageListingViewSet(PageListingViewSet):
icon = "globe"
menu_label = "Blog Pages"
add_to_admin_menu = True
model = BlogPage
blog_page_listing_viewset = BlogPageListingViewSet("blog_pages")
@hooks.register("register_admin_viewset")
def register_blog_page_listing_viewset():
return blog_page_listing_viewset
The columns of the listing can be customised by overriding the columns
attribute on the viewset. This should be a list of wagtail.admin.ui.tables.Column
instances:
from wagtail import hooks
from wagtail.admin.ui.tables import Column
from wagtail.admin.viewsets.pages import PageListingViewSet
from myapp.models import BlogPage
class BlogPageListingViewSet(PageListingViewSet):
# ...
columns = PageListingViewSet.columns + [
Column("blog_category", label="Category", sort_key="blog_category"),
]
The filtering options for the listing can be customised by overriding the filterset_class
attribute on the viewset:
from wagtail import hooks
from wagtail.admin.viewsets.pages import PageListingViewSet
from myapp.models import BlogPage
class BlogPageFilterSet(PageListingViewSet.filterset_class):
class Meta:
model = BlogPage
fields = ["blog_category"]
class BlogPageListingViewSet(PageListingViewSet):
# ...
filterset_class = BlogPageFilterSet