How to use

A simple example

Let’s say your website is for a local library. They have a model called Book that appears across the site in many places. You can define a normal Django model for it, then use ModelAdmin to create a menu in Wagtail’s admin to create, view, and edit Book entries.

models.py looks like this:

from django.db import models
from wagtail.admin.panels import FieldPanel


class Book(models.Model):
    title = models.CharField(max_length=255)
    author = models.CharField(max_length=255)
    cover_photo = models.ForeignKey(
        "wagtailimages.Image",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
    )

    panels = [FieldPanel("title"), FieldPanel("author"), FieldPanel("cover_photo")]

Note

You can specify panels like MultiFieldPanel within the panels attribute of the model. This lets you use Wagtail-specific layouts in an otherwise traditional Django model.

wagtail_hooks.py in your app directory would look something like this:

from wagtail_modeladmin.options import ModelAdmin, modeladmin_register
from .models import Book


class BookAdmin(ModelAdmin):
    model = Book
    base_url_path = "bookadmin"  # customise the URL from default to admin/bookadmin
    menu_label = "Book"  # ditch this to use verbose_name_plural from model
    menu_icon = "pilcrow"  # change as required
    menu_order = 200  # will put in 3rd place (000 being 1st, 100 2nd)
    add_to_settings_menu = False  # or True to add your model to the Settings sub-menu
    exclude_from_explorer = (
        False  # or True to exclude pages of this type from Wagtail's explorer view
    )
    add_to_admin_menu = True  # or False to exclude your model from the menu
    list_display = ("title", "author")
    list_filter = ("author",)
    search_fields = ("title", "author")


# Now you just need to register your customised ModelAdmin class with Wagtail
modeladmin_register(BookAdmin)

A more complicated example

In addition to Book, perhaps we also want to add Author and Genre models to our app and display a menu item for each of them, too. Creating lots of menus can add up quickly, so it might be a good idea to group related menus together. This section show you how to create one menu called Library which expands to show submenus for Book, Author, and Genre.

Assume we’ve defined Book, Author, and Genre models in models.py.

wagtail_hooks.py in your app directory would look something like this:

from wagtail_modeladmin.options import (
    ModelAdmin,
    ModelAdminGroup,
    modeladmin_register,
)
from .models import Book, Author, Genre


class BookAdmin(ModelAdmin):
    model = Book
    menu_label = "Book"  # ditch this to use verbose_name_plural from model
    menu_icon = "pilcrow"  # change as required
    list_display = ("title", "author")
    list_filter = ("genre", "author")
    search_fields = ("title", "author")


class AuthorAdmin(ModelAdmin):
    model = Author
    menu_label = "Author"  # ditch this to use verbose_name_plural from model
    menu_icon = "user"  # change as required
    list_display = ("first_name", "last_name")
    list_filter = ("first_name", "last_name")
    search_fields = ("first_name", "last_name")


class GenreAdmin(ModelAdmin):
    model = Genre
    menu_label = "Genre"  # ditch this to use verbose_name_plural from model
    menu_icon = "group"  # change as required
    list_display = ("name",)
    list_filter = ("name",)
    search_fields = ("name",)


class LibraryGroup(ModelAdminGroup):
    menu_label = "Library"
    menu_icon = "folder-open-inverse"  # change as required
    menu_order = 200  # will put in 3rd place (000 being 1st, 100 2nd)
    items = (BookAdmin, AuthorAdmin, GenreAdmin)


# When using a ModelAdminGroup class to group several ModelAdmin classes together,
# you only need to register the ModelAdminGroup class with Wagtail:
modeladmin_register(LibraryGroup)

Registering multiple classes in one wagtail_hooks.py file

Each time you call modeladmin_register(MyAdmin) it creates a new top-level menu item in Wagtail’s left sidebar. You can call this multiple times within the same wagtail_hooks.py file if you want. The example below will create 3 top-level menus.

class BookAdmin(ModelAdmin):
    model = Book
    ...


class MovieAdmin(ModelAdmin):
    model = MovieModel
    ...


class MusicAdminGroup(ModelAdminGroup):
    menu_label = _("Music")
    items = (AlbumAdmin, ArtistAdmin)
    ...


modeladmin_register(BookAdmin)
modeladmin_register(MovieAdmin)
modeladmin_register(MusicAdminGroup)