Add & edit forms are still defined by panels and edit_handlers

In Wagtail, controlling which fields appear in add/edit forms for your Model, and defining how they are grouped and ordered, is achieved by adding a panels attribute, or edit_handler to your Model class. This remains the same whether your model is a Page type, a snippet, or just a standard Django Model. Because of this, Wagtail’s ModelAdmin class is mostly concerned with ‘listing’ configuration. For example, list_display, list_filter and search_fields attributes are present and support largely the same values as Django’s ModelAdmin class, while fields, fieldsets, exclude and other attributes you may be used to using to configure Django’s add/edit views, simply aren’t supported by Wagtail’s version.

‘Page type’ models need to be treated differently from other models

While modeladmin’s listing view and it’s supported customisation options work in exactly the same way for all types of Model, when it comes to the other management views, the treatment differs depending on whether your ModelAdmin class is representing a page type model (that extends wagtailcore.models.Page) or not.

Pages in Wagtail have some unique properties, and require additional views, interface elements and general treatment in order to be managed effectively. For example, they have a tree structure that must be preserved properly as pages are added, deleted and moved around. They also have a revisions system, their own permission considerations, and the facility to preview changes before saving changes. Because of this added complexity, Wagtail provides its own specific views for managing any custom page types you might add to your project (whether you create a ModelAdmin class for them or not).

In order to deliver a consistent user experience, modeladmin simply redirects users to Wagtail’s existing page management views wherever possible. You should bear this in mind if you ever find yourself wanting to change what happens when pages of a certain type are added, deleted, published, or have some other action applied to them. Customising the CreateView or EditView for your page type Model (even if just to add an additional stylesheet or JavaScript), simply won’t have any effect, as those views are not used.

If you do find yourself needing to customise the add, edit or other behaviour for a page type model, you should take a look at the following part of the documentation: Hooks.

Wagtail’s ModelAdmin class is ‘modular’

Unlike Django’s class of the same name, wagtailadmin’s ModelAdmin acts primarily as a ‘controller’ class. While it does have a set of attributes and methods to enable you to configure how various components should treat your model, it has been deliberately designed to do as little work as possible by itself; it designates all of the real work to a set of separate, swappable components.

The theory is: If you want to do something differently, or add some functionality that modeladmin doesn’t already have, you can create new classes (or extend the ones provided by modeladmin) and easily configure your ModelAdmin class to use them instead of the defaults.

• Learn more about Overriding views
• Learn more about Overriding helper classes

ModelAdmin.url_helper_class

By default, the modeladmin.helpers.url.PageAdminURLHelper class is used when your model extends wagtailcore.models.Page, otherwise modeladmin.helpers.url.AdminURLHelper is used.

If you find that the above helper classes don’t work for your needs, you can easily create your own helper class by sub-classing AdminURLHelper or PageAdminURLHelper (if your model extends Wagtail’s Page model), and making any necessary additions/overrides.

Once your class is defined, set the url_helper_class attribute on your ModelAdmin class to use your custom URLHelper, like so:

    from wagtail.contrib.modeladmin.helpers import AdminURLHelper
    from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
    from .models import MyModel


    class MyURLHelper(AdminURLHelper):
        ...


    class MyModelAdmin(ModelAdmin):
        model = MyModel
        url_helper_class = MyURLHelper

    modeladmin_register(MyModelAdmin)

Or, if you have a more complicated use case, where simply setting that attribute isn’t possible (due to circular imports, for example) or doesn’t meet your needs, you can override the get_url_helper_class method, like so:

    class MyModelAdmin(ModelAdmin):
        model = MyModel

        def get_url_helper_class(self):
            if self.some_attribute is True:
                return MyURLHelper
            return AdminURLHelper

ModelAdmin.permission_helper_class

By default, the modeladmin.helpers.permission.PagePermissionHelper class is used when your model extends wagtailcore.models.Page, otherwise modeladmin.helpers.permission.PermissionHelper is used.

If you find that the above helper classes don’t work for your needs, you can easily create your own helper class, by sub-classing PermissionHelper (or PagePermissionHelper if your model extends Wagtail’s Page model), and making any necessary additions/overrides. Once defined, you set the permission_helper_class attribute on your ModelAdmin class to use your custom class instead of the default, like so:

    from wagtail.contrib.modeladmin.helpers import PermissionHelper
    from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
    from .models import MyModel


    class MyPermissionHelper(PermissionHelper):
        ...


    class MyModelAdmin(ModelAdmin):
        model = MyModel
        permission_helper_class = MyPermissionHelper

    modeladmin_register(MyModelAdmin)

Or, if you have a more complicated use case, where simply setting an attribute isn’t possible or doesn’t meet your needs, you can override the get_permission_helper_class method, like so:

    class MyModelAdmin(ModelAdmin):
        model = MyModel

        def get_permission_helper_class(self):
            if self.some_attribute is True:
                return MyPermissionHelper
            return PermissionHelper

ModelAdmin.button_helper_class

By default, the modeladmin.helpers.button.PageButtonHelper class is used when your model extends wagtailcore.models.Page, otherwise modeladmin.helpers.button.ButtonHelper is used.

If you wish to add or change buttons for your model’s IndexView, you’ll need to create your own button helper class by sub-classing ButtonHelper or PageButtonHelper (if your model extend’s Wagtail’s Page model), and make any necessary additions/overrides. Once defined, you set the button_helper_class attribute on your ModelAdmin class to use your custom class instead of the default, like so:

    from wagtail.contrib.modeladmin.helpers import ButtonHelper
    from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
    from .models import MyModel


    class MyButtonHelper(ButtonHelper):
        def add_button(self, classnames_add=None, classnames_exclude=None):
            if classnames_add is None:
                classnames_add = []
            if classnames_exclude is None:
                classnames_exclude = []
            classnames = self.add_button_classnames + classnames_add
            cn = self.finalise_classname(classnames, classnames_exclude)
            return {
                'url': self.url_helper.create_url,
                'label': _('Add %s') % self.verbose_name,
                'classname': cn,
                'title': _('Add a new %s') % self.verbose_name,
            }

        def inspect_button(self, pk, classnames_add=None, classnames_exclude=None):
            ...

        def edit_button(self, pk, classnames_add=None, classnames_exclude=None):
            ...

        def delete_button(self, pk, classnames_add=None, classnames_exclude=None):
            ...


    class MyModelAdmin(ModelAdmin):
        model = MyModel
        button_helper_class = MyButtonHelper

    modeladmin_register(MyModelAdmin)

To customise the buttons found in the ModelAdmin List View you can change the returned dictionary in the add_button, delete_button, edit_button or inspect_button methods. For example if you wanted to change the Delete button you could modify the delete_button method in your ButtonHelper like so:

    class MyButtonHelper(ButtonHelper):
        ...
        def delete_button(self, pk, classnames_add=None, classnames_exclude=None):
            ...
            return {
                'url': reverse("your_custom_url"),
                'label': _('Delete'),
                'classname': "custom-css-class",
                'title': _('Delete this item')
            }

Or, if you have a more complicated use case, where simply setting an attribute isn’t possible or doesn’t meet your needs, you can override the get_button_helper_class method, like so:

    class MyModelAdmin(ModelAdmin):
        model = MyModel

        def get_button_helper_class(self):
            if self.some_attribute is True:
                return MyButtonHelper
            return ButtonHelper

Using helpers in your custom views

As long as you sub-class modeladmin.views.WMABaseView (or one of the more ‘specific’ view classes) to create your custom view, instances of each helper should be available on instances of your class as:

• self.url_helper
• self.permission_helper
• self.button_helper

Unlike the other two, self.button_helper isn’t populated right away when the view is instantiated. In order to show the right buttons for the right users, ButtonHelper instances need to be ‘request aware’, so self.button_helper is only set once the view’s dispatch() method has run, which takes a HttpRequest object as an argument, from which the current user can be identified.