Skip to content

Commit

Permalink
Add docs for migrating to Wagtail's built-in features
Browse files Browse the repository at this point in the history
  • Loading branch information
@laymonage
laymonage committed Oct 28, 2024
1 parent e4b7982 commit 36dea06
Show file tree
Hide file tree
Showing 3 changed files with 187 additions and 2 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

Add any model in your project to the Wagtail admin. Formerly `wagtail.contrib.modeladmin`.

This package is in maintenance mode and will not receive new features. Consider [migrating to Snippets](https://docs.wagtail.org/en/v5.2.3/reference/contrib/modeladmin/migrating_to_snippets.html) and opening new feature requests in the [Wagtail issue tracker](https://github.com/wagtail/wagtail/issues).
This package is in maintenance mode and will not receive new features. Consider [migrating to Wagtail's built-in features](https://wagtail-modeladmin.readthedocs.io/en/latest/migrating.html) and opening new feature requests in the [Wagtail issue tracker](https://github.com/wagtail/wagtail/issues).

## Links

Expand Down
3 changes: 2 additions & 1 deletion docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
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.

```{note}
This package was originally incorporated into Wagtail as `wagtail.contrib.modeladmin`. To manage non-page models in Wagtail, we recommend using {ref}`wagtail:snippets` instead.
This package was originally incorporated into Wagtail as `wagtail.contrib.modeladmin`. Wagtail has since introduced new ways to manage Django models in the admin that are more integrated with its architecture. As a result, this package is in maintenance mode and will not receive new features. Consider [migrating to Wagtail's built-in features](./migrating) instead of using this package.
```

(modeladmin_feature_summary)=
Expand Down Expand Up @@ -36,4 +36,5 @@ create_edit_delete_views
inspectview
chooseparentview
tips_and_tricks/index
migrating
```
184 changes: 184 additions & 0 deletions docs/migrating.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
# Migrating from ModelAdmin to Wagtail's built-in features

The wagtail-modeladmin package is in maintenance mode and will not receive new features. Its functionalities have been replaced by the built-in `SnippetViewSet`, `ModelViewSet`, and `PageListingViewSet` in Wagtail. This page explains how to migrate from wagtail-modeladmin to those built-in features.

If you would rather not register the models as snippets, you can also use `ModelViewSet`. The migration explained with `SnippetViewSet` and `SnippetViewSetGroup` on this page can be substituted with `ModelViewSet` and `ModelViewSetGroup`. However, as of this writing, the `ModelViewSet` does not support the `get_queryset` method as described in [](modeladmin_get_queryset).

See [](generic_views) for more details on using {class}`~wagtail.admin.viewsets.model.ModelViewSet`.

For managing page models, see {ref}`wagtail:custom_page_listings`.

## Installation

Ensure `wagtail.snippets` is in your `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
...,
"wagtail.snippets",
...,
]
```

## Convert `ModelAdmin` class to `SnippetViewSet`

```{eval-rst}
.. module:: wagtail.snippets.views.snippets
:noindex:
```

The {class}`~wagtail.snippets.views.snippets.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:

```diff
- 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:

```diff
- 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}`~wagtail.admin.viewsets.base.ViewSet.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}`~wagtail.admin.viewsets.base.ViewSet.icon` | Same value, but different attribute name, as the icon is used throughout the admin and not just in the menu. |
| `list_display` | {attr}`~wagtail.admin.viewsets.model.ModelViewSet.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}`~wagtail.admin.viewsets.model.ModelViewSet.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}`~wagtail.admin.viewsets.model.ModelViewSet.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 [](wagtailsnippets_templates) for more details. |

### Boolean properties in `list_display`

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 `SnippetViewSet.list_display`:

```python
from wagtail.admin.ui.tables import BooleanColumn


class MySnippetViewSet(SnippetViewSet):
list_display = ("title", BooleanColumn("is_active"))
```

The `BooleanColumn` class works with both model fields and custom properties that return booleans.

## Convert `ModelAdminGroup` class to `SnippetViewSetGroup`

The {class}`~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 `ModelAdminGroup` to `SnippetViewSetGroup`:

```diff
- from wagtail.contrib.modeladmin.options import ModelAdminGroup
+ from wagtail.snippets.views.snippets import SnippetViewSetGroup
```

Change any references to `ModelAdminGroup` to `SnippetViewSetGroup`:

```diff
- class MyModelAdminGroup(ModelAdminGroup):
+ class MySnippetViewSetGroup(SnippetViewSetGroup):
...

- modeladmin_register(MyModelAdminGroup)
+ register_snippet(MySnippetViewSetGroup)
```

## Using ModelAdmin to manage Page models

Refer to {ref}`wagtail:custom_page_listings`.

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

### 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`](insert_global_admin_css) and [`insert_global_admin_js`](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`](register_snippet_listing_buttons) and [`construct_snippet_listing_buttons`](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}`~wagtail.admin.viewsets.model.ModelViewSet.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`](title_field_panel).

## Keep ModelAdmin usage

If you still rely on ModelAdmin, you can still use this package in the meantime. 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 {doc}`wagtail:contributing/issue_tracking`.

It is highly recommended to migrate to the built-in replacements for ModelAdmin as soon as possible to ensure compatibility with future versions of Wagtail.

0 comments on commit 36dea06

Please sign in to comment.