What is wagtailmodeladmin?

It's an extension for Torchbox's Wagtail CMS that allows you create customisable listing pages for any model in your Wagtail project, and have them appear in the navigation when you log into the admin area. Simply extend the ModelAdmin class, override a few attributes to suit your needs, link it into Wagtail using a few hooks (you can copy and paste from the examples below), and you're good to go.

NOTE: wagtailmodeladmin is now part of Wagtail (from v1.5)

As of version 1.5, Wagtail now comes packaged with wagtailmodeladmin as a contrib app, wagtail.contrib.modeladmin, so you no longer need to install it separately. However, the versions are not identical. Some underlying components/classes have been re-factored, so there will likely be upgrade considerations for projects with more customised `ModelAdmin` implementations (where views and helpers have been extended and overridden).

On the plus side, the new version is better integrated, and provides a more consistent experience, as a developer and user. It also includes bug fixes, performance improvements, and tests, making this standalone version redundant. For these reasons, this version will no longer be maintained.

View the documentation here: http://docs.wagtail.io/en/latest/reference/contrib/modeladmin.html

Upgrading from wagtailmodeladmin to wagtail.contrib.modeladmin

If you only used the core ModelAdmin and ModelAdminGroup classes in your projects, and made use of standard attributes/methods for customisation, migrating to the new version should be as simple as:

  1. Follow the installation instructions outlined in the Wagtail docs: http://docs.wagtail.io/en/latest/reference/contrib/modeladmin.html.
  2. In wagtail_hooks.py, for each of your custom apps, import the core classes from their new locations in wagtail.contrib.modeladmin.options instead of wagtailmodeladmin.options.
  3. Import the wagtail.contrib.modeladmin.options.modeladmin_register method instead of wagtailmodeladmin.options.wagtailmodeladmin_register, and use that to register your classes instead.
  4. Remove the old app from your project, by removing wagtailmodeladmin from INSTALLED_APPS, and wagtailmodeladmin.middleware.ModelAdminMiddleware from MIDDLEWARE_CLASSES in your project's settings.

A full list of features:

  • A customisable list view, allowing you to control what values are displayed for each item, available filter options, default ordering, and more.
  • Access your list views from the CMS 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 cleverly 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 wagtailmodeladmin 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.

Supported list options:

With the exception of bulk actions and date hierarchy, the ModelAdmin class offers similar list functionality to Django's ModelAdmin class, providing:

  • control over what values are displayed (via the list_display attribute)
  • control over default ordering (via the ordering attribute)
  • customisable model-specific text search (via the search_fields attribute)
  • customisable filters (via the list_filter attribue)

list_display supports the same fields and methods as Django's ModelAdmin class (including short_description and admin_order_field on custom methods), giving you lots of flexibility when it comes to output. Read more about list_display in the Django docs.

list_filter supports the same field types as Django's ModelAdmin class, giving your users an easy way to find what they're looking for. Read more about list_filter in the Django docs.

Adding functionality, not taking it away

wagtailmodeladmin doesn't interfere with what Wagtail does. If your model extends Wagtail's Page model, or is registered as a Snippet, they'll still be appear in Wagtail's Snippet and Page views within the admin centre. wagtailmodeladmin simply adds an additional, alternative set of views, which you're in control of.

How to install

  1. Install the package using pip: pip install wagtailmodeladmin
  2. Add wagtailmodeladmin to INSTALLED_APPS in your project settings
  3. Add the wagtailmodeladmin.middleware.ModelAdminMiddleware class to MIDDLEWARE_CLASSES in your project settings (it should be fine at the end)
  4. Add a wagtail_hooks.py file to your app's folder and extend the ModelAdmin, and ModelAdminGroup classes to produce the desired effect

A simple example

You have a model in your app, and you want a listing page specifically for that model, with a menu item added to the menu in Wagtail's CMS so that you can get to it.

wagtail_hooks.py in your app directory would look something like this:

from wagtailmodeladmin.options import ModelAdmin, wagtailmodeladmin_register
from .models import MyPageModel


class MyPageModelAdmin(ModelAdmin):
    model = MyPageModel
    menu_label = 'Page Model' # ditch this to use verbose_name_plural from model
    menu_icon = 'date' # 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
    list_display = ('title', 'example_field2', 'example_field3', 'live')
    list_filter = ('live', 'example_field2', 'example_field3')
    search_fields = ('title',)

# Now you just need to register your customised ModelAdmin class with Wagtail
wagtailmodeladmin_register(MyPageModelAdmin)

The Wagtail CMS menu would look something like this:

Simple example menu preview

Simple example menu preview

A more complicated example

You have an app with several models that you want to show grouped together in Wagtail's admin menu. Some of the models might extend Page, and others might be simpler models, perhaps registered as Snippets, perhaps not. No problem! ModelAdminGroup allows you to group them all together nicely.

wagtail_hooks.py in your app directory would look something like this:

from wagtailmodeladmin.options import (
    ModelAdmin, ModelAdminGroup, wagtailmodeladmin_register)
from .models import (
    MyPageModel, MyOtherPageModel, MySnippetModel, SomeOtherModel)


class MyPageModelAdmin(ModelAdmin):
    model = MyPageModel
    menu_label = 'Page Model' # ditch this to use verbose_name_plural from model
    menu_icon = 'doc-full-inverse' # change as required
    list_display = ('title', 'example_field2', 'example_field3', 'live')
    list_filter = ('live', 'example_field2', 'example_field3')
    search_fields = ('title',)


class MyOtherPageModelAdmin(ModelAdmin):
    model = MyOtherPageModel
    menu_label = 'Other Page Model' # ditch this to use verbose_name_plural from model
    menu_icon = 'doc-full-inverse' # change as required
    list_display = ('title', 'example_field2', 'example_field3', 'live')
    list_filter = ('live', 'example_field2', 'example_field3')
    search_fields = ('title',)


class MySnippetModelAdmin(ModelAdmin):
    model = MySnippetModel
    menu_label = 'Snippet Model' # ditch this to use verbose_name_plural from model
    menu_icon = 'snippet' # change as required
    list_display = ('title', 'example_field2', 'example_field3')
    list_filter = ('example_field2', 'example_field3')
    search_fields = ('title',)


class SomeOtherModelAdmin(ModelAdmin):
    model = SomeOtherModel
    menu_label = 'Some other model' # ditch this to use verbose_name_plural from model
    menu_icon = 'snippet' # change as required
    list_display = ('title', 'example_field2', 'example_field3')
    list_filter = ('example_field2', 'example_field3')
    search_fields = ('title',)


class MyModelAdminGroup(ModelAdminGroup):
    menu_label = 'My App'
    menu_icon = 'folder-open-inverse' # change as required
    menu_order = 200 # will put in 3rd place (000 being 1st, 100 2nd)
    items = (MyPageModelAdmin, MyOtherPageModelAdmin, MySnippetModelAdmin, SomeOtherModelAdmin)

# When using a ModelAdminGroup class to group several ModelAdmin classes together,
# you only need to register the ModelAdminGroup class with Wagtail:
wagtailmodeladmin_register(MyModelAdminGroup)

The Wagtail CMS menu would look something like this:

Complex example menu preview

Complex example menu preview

Notes



What is wagtailmodeladmin?

它是Torchbox的 Wagtail的扩展 CMS ,允许您创建 Wagtail项目中任何型号的可定制列表页面,以及 当您登录到管理区域时,将它们显示在导航中。 简单地扩展 ModelAdmin 类,覆盖一些属性 适合您的需要,使用几个钩子链接到Wagtail(您可以复制) 并从下面的示例中粘贴),你很好。

注意: wagtailmodeladmin 现在是Wagtail的一部分(从v1.5)

从版本 1.5 起,Wagtail现在与 wagtailmodeladmin 一起作为contrib应用程序 wagtail.contrib.modeladmin 打包,所以你不再需要单独安装。但是,版本不一样。一些基础组件/类已被重新考虑,因此,对于具有更多自定义的ModelAdmin实现(其中视图和帮助器已被扩展和覆盖)的项目,可能会有升级注意事项。

从另一方面来说,新版本更好地集成,并且作为开发者和用户提供了更一致的体验。它还包括错误修复,性能改进和测试,使此独立版本冗余。由于这些原因,此版本将不再被维护

在此查看文档: http://docs.wagtail.io/en/latest/ reference / contrib / modeladmin.html

wagtailmodeladmin 升级到 wagtail.contrib.modeladmin

如果您仅在项目中使用核心的 ModelAdmin ModelAdminGroup 类,并使用标准属性/方法进行自定义,那么迁移到新版本应该是简单如下:

  1. Follow the installation instructions outlined in the Wagtail docs: http://docs.wagtail.io/en/latest/reference/contrib/modeladmin.html.
  2. In wagtail_hooks.py, for each of your custom apps, import the core classes from their new locations in wagtail.contrib.modeladmin.options instead of wagtailmodeladmin.options.
  3. Import the wagtail.contrib.modeladmin.options.modeladmin_register method instead of wagtailmodeladmin.options.wagtailmodeladmin_register, and use that to register your classes instead.
  4. Remove the old app from your project, by removing wagtailmodeladmin from INSTALLED_APPS, and wagtailmodeladmin.middleware.ModelAdminMiddleware from MIDDLEWARE_CLASSES in your project's settings.

功能的完整列表:

  • 可自定义的列表视图,允许您控制什么值 显示每个项目,可用的过滤器选项,默认排序, 和/或更多
  • 自动从CMS轻松访问您的列表视图 生成的菜单项,具有自动活动项突出显示。 控制使用易于更改属性的标签文本和图标 在你的班上。
  • 一个额外的 ModelAdminGroup 类,允许您进行分组 您的相关模型,并将它们列在自己的子菜单中 更合乎逻辑的用户体验。
  • 为非页面模型简单,强大的添加修改视图 使用您模型上定义的面板配置 Wagtail的编辑面板。
  • 对于页面模型,系统巧妙地指向了Wagtail现有的 添加和编辑视图,并返回到正确的列表页面, 无缝体验。
  • 完全尊重分配给您的Wagtail用户的权限 团体用户只能做你想要的!
  • 所有你需要轻松地将你的 ModelAdmin 类钩入Wagtail, 注意URL注册,菜单更改和注册 缺少模型权限,以便您可以将其分配给组。
  • 建立可定制 - 当wagtailmodeladmin提供一个 坚实的体验开箱即用,您可以轻松使用自己的 模板和 ModelAdmin 类有很多方法 您可以覆盖或扩展,允许您自定义 行为更大。

支持的列表选项:

除了批量操作和日期层次结构之外, ModelAdmin 类为Django提供了类似的列表功能 ModelAdmin类,提供:

  • 控制显示的值(通过 list_display 属性)
  • 控制默认排序(通过排序属性)
  • 可定制的模型特定文本搜索(通过 search_fields 属性)
  • 可定制过滤器(通过 list_filter attribue)

list_display 支持与Django相同的字段和方法 ModelAdmin类(包括 short_description admin_order_field 在自定义方法),给你很大的灵活性 当涉及到输出。 详细了解Django中的list_display docs

list_filter 支持与Django的ModelAdmin相同的字段类型 课程,给您的用户一个简单的方法来找到他们要找的东西。 详细了解Django中的list_filter docs

添加功能,不要把它取走

wagtailmodeladmin不会干扰Wagtail的作用。如果你的 模型扩展了Wagtail的 Page 模型,或者被注册为 Snippet ,它们仍然会出现在Wagtail的代码段和页面视图中 在管理中心内。 wagtailmodeladmin只是添加一个额外的, 您可以控制的另一组视图。

如何安装

  1. Install the package using pip: pip install wagtailmodeladmin
  2. Add wagtailmodeladmin to INSTALLED_APPS in your project settings
  3. Add the wagtailmodeladmin.middleware.ModelAdminMiddleware class to MIDDLEWARE_CLASSES in your project settings (it should be fine at the end)
  4. Add a wagtail_hooks.py file to your app's folder and extend the ModelAdmin, and ModelAdminGroup classes to produce the desired effect

一个简单的例子

您的应用中有一个模型,您需要一个专门的列表页面 对于该模型,菜单项添加到Wagtail的CMS中的菜单中 你可以得到它。

您的应用程式目录中的

wagtail_hooks.py 会看起来像 这个:

from wagtailmodeladmin.options import ModelAdmin, wagtailmodeladmin_register
from .models import MyPageModel

class MyPageModelAdmin(ModelAdmin): model = MyPageModel menu_label = 'Page Model' # ditch this to use verbose_name_plural from model menu_icon = 'date' # 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 list_display = ('title', 'example_field2', 'example_field3', 'live') list_filter = ('live', 'example_field2', 'example_field3') search_fields = ('title',)

# Now you just need to register your customised ModelAdmin class with Wagtail wagtailmodeladmin_register(MyPageModelAdmin)

Wagtail CMS菜单将如下所示:

Simple example menu preview

Simple example menu preview

一个更复杂的例子

您有一个应用程序,其中包含几个要显示分组的模型 一起在Wagtail的管理菜单中。一些模型可能会扩展Page, 而其他可能是更简单的模型,也许注册为Snippets, 也许不是没问题! ModelAdminGroup允许您将它们全部分组 一起很好。

您的应用程式目录中的

wagtail_hooks.py 会看起来像 这个:

from wagtailmodeladmin.options import (
    ModelAdmin, ModelAdminGroup, wagtailmodeladmin_register)
from .models import (
    MyPageModel, MyOtherPageModel, MySnippetModel, SomeOtherModel)

class MyPageModelAdmin(ModelAdmin): model = MyPageModel menu_label = 'Page Model' # ditch this to use verbose_name_plural from model menu_icon = 'doc-full-inverse' # change as required list_display = ('title', 'example_field2', 'example_field3', 'live') list_filter = ('live', 'example_field2', 'example_field3') search_fields = ('title',)

class MyOtherPageModelAdmin(ModelAdmin): model = MyOtherPageModel menu_label = 'Other Page Model' # ditch this to use verbose_name_plural from model menu_icon = 'doc-full-inverse' # change as required list_display = ('title', 'example_field2', 'example_field3', 'live') list_filter = ('live', 'example_field2', 'example_field3') search_fields = ('title',)

class MySnippetModelAdmin(ModelAdmin): model = MySnippetModel menu_label = 'Snippet Model' # ditch this to use verbose_name_plural from model menu_icon = 'snippet' # change as required list_display = ('title', 'example_field2', 'example_field3') list_filter = ('example_field2', 'example_field3') search_fields = ('title',)

class SomeOtherModelAdmin(ModelAdmin): model = SomeOtherModel menu_label = 'Some other model' # ditch this to use verbose_name_plural from model menu_icon = 'snippet' # change as required list_display = ('title', 'example_field2', 'example_field3') list_filter = ('example_field2', 'example_field3') search_fields = ('title',)

class MyModelAdminGroup(ModelAdminGroup): menu_label = 'My App' menu_icon = 'folder-open-inverse' # change as required menu_order = 200 # will put in 3rd place (000 being 1st, 100 2nd) items = (MyPageModelAdmin, MyOtherPageModelAdmin, MySnippetModelAdmin, SomeOtherModelAdmin)

# When using a ModelAdminGroup class to group several ModelAdmin classes together, # you only need to register the ModelAdminGroup class with Wagtail: wagtailmodeladmin_register(MyModelAdminGroup)

Wagtail CMS菜单将如下所示:

Complex example menu preview

Complex example menu preview

注意




相关问题推荐