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
wagtail.snippets is in your
INSTALLED_APPS = [
ModelAdmin class to
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
- 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
- class MyModelAdmin(ModelAdmin):
+ class MySnippetViewSet(SnippetViewSet):
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:
Same attribute name, but the value defaults to
Same value, but different attribute name, as the icon is used throughout the admin and not just in the menu.
Same attribute name, but the list/tuple of strings must refer to existing attributes or methods on the model, not the
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
Same value, but different attribute name to better align with
New attribute. Set to the name of a template directory to override the
Boolean properties in
In ModelAdmin, boolean fields in
list_display are rendered as tick/cross icons. To achieve the same behavior in SnippetViewSet, you need to use a
wagtail.admin.ui.tables.BooleanColumn instance in
from wagtail.admin.ui.tables import BooleanColumn
list_display = ("title", BooleanColumn("is_active"))
BooleanColumn class works with both model fields and custom properties that return booleans.
New in version 5.1.1: The
BooleanColumn class was added.
ModelAdminGroup class to
SnippetViewSetGroup class is the snippets-equivalent to the
ModelAdminGroup class. To migrate a
ModelAdminGroup class to a
SnippetViewSetGroup class, follow these instructions.
Change any imports of
- from wagtail.contrib.modeladmin.options import ModelAdminGroup
+ from wagtail.snippets.views.snippets import SnippetViewSetGroup
Change any references to
- class MyModelAdminGroup(ModelAdminGroup):
+ class MySnippetViewSetGroup(SnippetViewSetGroup):
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 and the Universal Listings discussion. 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:
This can be achieved by creating a custom
wagtail.admin.ui.tables.Tablesubclass and using it as the
This can be achieved using a custom
By default, the first column specified in
list_displayis the one that contains the buttons. Using custom
SnippetViewSet.list_displayallows you to specify a different column.
This mixin is used to show a thumbnail in the index view. A similar functionality can be achieved using a custom
SnippetViewSet.list_display. Hence, the following attributes are not supported:
Custom CSS and JS¶
ModelAdmin supports inserting custom extra CSS and JS files into the admin via the following attributes on the ModelAdmin class:
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_js hooks can also be used.
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.
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.
Wagtail uses an internal permission policy system to manage permissions across the admin. The
SnippetViewSetclass has a
permission_policyattribute, which is an instance of a permission policy class.
construct_snippet_listing_buttonshooks 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.
When searching snippets, Wagtail’s default search backend is used. To use a different backend, the
search_backend_nameattribute can be overridden. If the attribute is set to
None, the search uses the Django ORM instead.
search_handler_classattribute is not supported in snippets, the
ModelAdmin.extra_search_kwargsattribute is also not supported.
This can be replaced by the Django-standard
get_FOO_display()method on the model.
SnippetViewSet.orderingattribute is responsible for the default ordering of the index view, before falling back to the model’s
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
This is not supported in favor of
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 Issue tracking.