Installation

Add wagtail.contrib.modeladmin to your INSTALLED_APPS:

    INSTALLED_APPS = [
       ...
       'wagtail.contrib.modeladmin',
    ]

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')
        ]

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

    from wagtail.contrib.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.contrib.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)