Migrating from ModelAdmin to Snippets

To provide a single, unified way to manage non-page Django models, the modeladmin contrib module has been deprecated in favor of the snippets module. This page explains how to migrate from modeladmin to snippets.

Installation

Ensure wagtail.snippets is in your INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    'wagtail.snippets',
    ...,
]

Convert `ModelAdmin` class to `SnippetViewSet`

.. module:: wagtail.snippets.views.snippets
    :noindex:

The {class}~SnippetViewSet class is the snippets-equivalent to the ModelAdmin class. To migrate a ModelAdmin class to a SnippetViewSet class, follow these instructions.

Change any imports of ModelAdmin and modeladmin_register to SnippetViewSet and register_snippet, respectively:

- from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
+ from wagtail.snippets.models import register_snippet
+ from wagtail.snippets.views.snippets import SnippetViewSet

Change any references to ModelAdmin and modeladmin_register to SnippetViewSet and register_snippet, respectively:

- class MyModelAdmin(ModelAdmin):
+ class MySnippetViewSet(SnippetViewSet):
      ...

- modeladmin_register(MyModelAdmin)
+ register_snippet(MySnippetViewSet)

There are a few attributes of ModelAdmin that need to be renamed/adjusted for SnippetViewSet. The following is a table of such attributes and the changes that need to be made:

`ModelAdmin` attribute	`SnippetViewSet` attribute	Notes
`add_to_admin_menu`	{attr}`~SnippetViewSet.add_to_admin_menu`	Same attribute name, but the value defaults to `False` instead of `True`. Set to `True` to add a top-level menu item for the model.
`menu_icon`	{attr}`~SnippetViewSet.icon`	Same value, but different attribute name, as the icon is used throughout the admin and not just in the menu.
`list_display`	{attr}`~SnippetViewSet.list_display`	Same attribute name, but the list/tuple of strings must refer to existing attributes or methods on the model, not the `SnippetViewSet` class. If you have specified a string that refers to an attribute or method on the `ModelAdmin` class, you need to move it to the model. In addition, `list_display` now also supports instances of the `wagtail.admin.ui.tables.Column` component class.
`list_filter`	{attr}`~SnippetViewSet.list_filter`	Same attribute name and value, but filtering is built on top of the django-filter package under the hood, which behaves differently to ModelAdmin's filters. See documentation for `SnippetViewSet.list_filter` and {attr}`~SnippetViewSet.filterset_class` for more details.
`form_fields_exclude`	{attr}`~wagtail.admin.viewsets.model.ModelViewSet.exclude_form_fields`	Same value, but different attribute name to better align with `ModelViewSet`.
-	{attr}`~SnippetViewSet.template_prefix`	New attribute. Set to the name of a template directory to override the `"wagtailsnippets/snippets/"` default. If set to `"modeladmin/"`, the template directory structure will be equal to what ModelAdmin uses. Make sure any custom templates are placed in the correct directory according to this prefix. See for more details.

Unsupported features and customizations

Some features and customizations in ModelAdmin are not directly supported via SnippetViewSet, but may be achievable via other means that are more in line with Wagtail's architecture.

Using ModelAdmin to manage Page models

ModelAdmin allows the registration of Page models, but the main use case is to create custom page listing views. The create and edit views are not supported by ModelAdmin, as there are page-specific operations in those views that are best handled by Wagtail's page views. For this reason, registering a Page model as a snippet is not supported.

In a future release, Wagtail will introduce a new "treeless" listing view for pages, as outlined in [RFC 082: Treeless page listings](https://github.com/wagtail/rfcs/pull/82) and the [Universal Listings discussion](https://github.com/wagtail/wagtail/discussions/10446). This feature will allow for custom page listing views and will be the recommended way to achieve this use case. Feedback to this upcoming feature is welcome.

Customization of index view table rows and columns

ModelAdmin has a number of APIs that allow customization of the index view table rows and columns. Meanwhile, Wagtail has an internal generic tables UI framework that is used throughout the admin, including snippets. This table framework will become the standard way to build table elements in index views within the admin. As a result, the following APIs are not supported in snippets:

ModelAdmin.get_extra_attrs_for_row

This can be achieved by creating a custom wagtail.admin.ui.tables.Table subclass and using it as the IndexView.table_class.
ModelAdmin.get_extra_class_names_for_field_col

This can be achieved using a custom wagtail.admin.ui.tables.Column instance in SnippetViewSet.list_display.
ModelAdmin.list_display_add_buttons

By default, the first column specified in list_display is the one that contains the buttons. Using custom wagtail.admin.ui.tables.Column instances in SnippetViewSet.list_display allows you to specify a different column.
Attributes for wagtail.contrib.modeladmin.mixins.ThumbnailMixin

This mixin is used to show a thumbnail in the index view. A similar functionality can be achieved using a custom wagtail.admin.ui.tables.Column instance in SnippetViewSet.list_display. Hence, the following attributes are not supported:
- ModelAdmin.thumb_image_field_name
- ModelAdmin.thumb_image_width
- ModelAdmin.thumb_classname
- ModelAdmin.thumb_col_header_text
- ModelAdmin.thumb_default

Custom CSS and JS

ModelAdmin supports inserting custom extra CSS and JS files into the admin via the following attributes on the ModelAdmin class:

ModelAdmin.index_view_extra_css
ModelAdmin.index_view_extra_js
ModelAdmin.form_view_extra_css
ModelAdmin.form_view_extra_js
ModelAdmin.inspect_view_extra_css
ModelAdmin.inspect_view_extra_js

This is not supported in snippets, but custom CSS and JS files can be inserted by overriding the respective view's template. Alternatively, the insert_global_admin_css and insert_global_admin_js hooks can also be used.

Helper classes

Helper classes encapsulate the logic that is commonly used across views in ModelAdmin. These classes do not exist for snippets, as the similar logic now relies on generic patterns used across Wagtail.

ModelAdmin.url_helper_class

The base {class}~wagtail.admin.viewsets.base.ViewSet class has {meth}~wagtail.admin.viewsets.base.ViewSet.get_urlpatterns() and {meth}~wagtail.admin.viewsets.base.ViewSet.get_url_name() methods that can be used to manage the URLs of snippets views. The URL names can be used with Django's reverse() function to generate URLs.
ModelAdmin.permission_helper_class

Wagtail uses an internal permission policy system to manage permissions across the admin. The {class}~SnippetViewSet class has a {attr}~SnippetViewSet.permission_policy attribute, which is an instance of a permission policy class.
ModelAdmin.button_helper_class

The pre-existing register_snippet_listing_buttons and construct_snippet_listing_buttons hooks can be used to customize the buttons in the listing view. For other views, custom buttons can be added by overriding the respective view's template.
ModelAdmin.search_handler_class

When searching snippets, Wagtail's default search backend is used. To use a different backend, the {attr}~SnippetViewSet.search_backend_name attribute can be overridden. If the attribute is set to None, the search uses the Django ORM instead.

As the search_handler_class attribute is not supported in snippets, the ModelAdmin.extra_search_kwargs attribute is also not supported.

Other customizations

ModelAdmin.empty_value_display and ModelAdmin.get_empty_value_display()

This can be replaced by the Django-standard {meth}~django.db.models.Model.get_FOO_display method on the model.
ModelAdmin.get_ordering(request)

The {attr}SnippetViewSet.ordering attribute is responsible for the default ordering of the index view, before falling back to the model's {attr}~django.db.models.Options.ordering. The index view handles per-request ordering based on the columns that are specified in list_display. For more advanced customization, you can override the {attr}~SnippetViewSet.index_view_class.
ModelAdmin.prepopulated_fields

This is not supported in favor of TitleFieldPanel.

Keep ModelAdmin usage

If you still rely on ModelAdmin, it is still available as a separate wagtail-modeladmin package. The package is in maintenance mode and will not receive new features. If you have a use case that is not supported by SnippetViewSet and not described above, consider opening a feature request in the Wagtail issue tracker. For more details, see .

9.4 KiB Raw Blame History