wagtail/docs/reference/contrib/modeladmin/index.md

ModelAdmin

The modeladmin module allows you to add any model in your project to the Wagtail admin. You can create customisable listing pages for a model, including plain Django models, and add navigation elements so that a model can be accessed directly from the Wagtail admin. Simply extend the ModelAdmin class, override a few attributes to suit your needs, register it with Wagtail using an easy one-line modeladmin_register method (you can copy and paste from the examples below), and you're good to go. Your model doesn’t need to extend Page or be registered as a Snippet, and it won’t interfere with any of the existing admin functionality that Wagtail provides.

(modeladmin_feature_summary)=

Summary of features

• A customisable list view, allowing you to control what values are displayed for each row, available options for result filtering, default ordering, spreadsheet downloads and more.
• Access your list views from the Wagtail admin menu easily with automatically generated menu items, with automatic 'active item' highlighting. Control the label text and icons used with easy-to-change attributes on your class.
• An additional ModelAdminGroup class, that allows you to group your related models, and list them together in their own submenu, for a more logical user experience.
• Simple, robust add and edit views for your non-Page models that use the panel configurations defined on your model using Wagtail's edit panels.
• For Page models, the system directs to Wagtail's existing add and edit views, and returns you back to the correct list page, for a seamless experience.
• Full respect for permissions assigned to your Wagtail users and groups. Users will only be able to do what you want them to!
• All you need to easily hook your ModelAdmin classes into Wagtail, taking care of URL registration, menu changes, and registering any missing model permissions, so that you can assign them to Groups.
• Built to be customisable - While modeladmin provides a solid experience out of the box, you can easily use your own templates, and the ModelAdmin class has a large number of methods that you can override or extend, allowing you to customise the behaviour to a greater degree.

Want to know more about customising ModelAdmin?

---
maxdepth: 1
titlesonly:
---
primer
base_url
menu_item
indexview
create_edit_delete_views
inspectview
chooseparentview
tips_and_tricks/index

(modeladmin_usage)=

Installation

Add wagtail.contrib.modeladmin to your INSTALLED_APPS:

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

How to use

(modeladmin_example_simple)=

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

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

(modeladmin_example_complex)=

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)

(modeladmin_multi_registration)=

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)