2016-04-13 06:01:04 +00:00
|
|
|
|
=====================
|
|
|
|
|
``ModelAdmin``
|
|
|
|
|
=====================
|
|
|
|
|
|
|
|
|
|
The ``modeladmin`` module allows you to create customisable listing
|
|
|
|
|
pages for any model in your Wagtail project, and add navigation elements to the
|
2016-08-08 20:19:33 +00:00
|
|
|
|
Wagtail admin area so that you can access them. 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.
|
2016-04-13 06:01:04 +00:00
|
|
|
|
|
|
|
|
|
You can use it with any Django model (it 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.
|
|
|
|
|
|
2016-08-08 20:19:33 +00:00
|
|
|
|
.. _modeladmin_feature_summary:
|
2016-04-13 06:01:04 +00:00
|
|
|
|
|
2016-08-08 20:19:33 +00:00
|
|
|
|
-------------------
|
|
|
|
|
Summary of features
|
|
|
|
|
-------------------
|
2016-04-13 06:01:04 +00:00
|
|
|
|
|
|
|
|
|
- A customisable list view, allowing you to control what values are displayed
|
|
|
|
|
for each row, available options for result filtering, default ordering, and
|
|
|
|
|
more.
|
|
|
|
|
- Access your list views from the Wagtail admin menu 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 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 ``modeladmin`` 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.
|
|
|
|
|
|
2016-08-08 20:19:33 +00:00
|
|
|
|
---------------------------------------------------
|
|
|
|
|
Want to know more about customising ``ModelAdmin``?
|
|
|
|
|
---------------------------------------------------
|
|
|
|
|
|
|
|
|
|
.. toctree::
|
|
|
|
|
:maxdepth: 1
|
|
|
|
|
|
|
|
|
|
primer
|
|
|
|
|
menu_item
|
|
|
|
|
indexview
|
|
|
|
|
create_edit_delete_views
|
|
|
|
|
inspectview
|
|
|
|
|
chooseparentview
|
2016-04-13 06:01:04 +00:00
|
|
|
|
|
|
|
|
|
.. _modeladmin_usage:
|
|
|
|
|
|
|
|
|
|
Installation
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
Add ``wagtail.contrib.modeladmin`` to your ``INSTALLED_APPS``:
|
|
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
|
|
INSTALLED_APPS = [
|
|
|
|
|
...
|
|
|
|
|
'wagtail.contrib.modeladmin',
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
How to use
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
.. _modeladmin_example_simple:
|
|
|
|
|
|
|
|
|
|
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 the Wagtail admin area so that you
|
|
|
|
|
can get to it.
|
|
|
|
|
|
|
|
|
|
``wagtail_hooks.py`` in your app directory would look something like this:
|
|
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
|
|
from wagtail.contrib.modeladmin.options import (
|
|
|
|
|
ModelAdmin, modeladmin_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
|
2016-07-28 22:32:51 +00:00
|
|
|
|
exclude_from_explorer = False # or True to exclude pages of this type from Wagtail's explorer view
|
2016-04-13 06:01:04 +00:00
|
|
|
|
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
|
|
|
|
|
modeladmin_register(MyPageModelAdmin)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _modeladmin_example_complex:
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
|
|
from wagtail.contrib.modeladmin.options import (
|
|
|
|
|
ModelAdmin, ModelAdminGroup, modeladmin_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')
|
2016-09-04 15:43:39 +00:00
|
|
|
|
list_filter = ('example_field2', 'example_field3')
|
2016-04-13 06:01:04 +00:00
|
|
|
|
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')
|
2016-09-04 15:43:39 +00:00
|
|
|
|
list_filter = ('example_field2', 'example_field3')
|
2016-04-13 06:01:04 +00:00
|
|
|
|
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:
|
|
|
|
|
modeladmin_register(MyModelAdminGroup)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. _modeladmin_multi_registeration:
|
|
|
|
|
|
|
|
|
|
Registering multiple classes in one ``wagtail_hooks.py`` file
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
If you have an app with more than one model that you wish to manage, or even
|
|
|
|
|
multiple models you wish to group together with ``ModelAdminGroup`` classes,
|
|
|
|
|
that's possible. Just register each of your ModelAdmin classes using
|
|
|
|
|
``modeladmin_register``, and they'll work as expected.
|
|
|
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
|
|
class MyPageModelAdmin(ModelAdmin):
|
|
|
|
|
model = MyPageModel
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
class MyOtherPageModelAdmin(ModelAdmin):
|
|
|
|
|
model = MyOtherPageModel
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
class MyModelAdminGroup(ModelAdminGroup):
|
|
|
|
|
label = _("Group 1")
|
|
|
|
|
items = (ModelAdmin1, ModelAdmin2)
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
class MyOtherModelAdminGroup(ModelAdminGroup):
|
|
|
|
|
label = _("Group 2")
|
|
|
|
|
items = (ModelAdmin3, ModelAdmin4)
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
modeladmin_register(MyPageModelAdmin)
|
|
|
|
|
modeladmin_register(MyOtherPageModelAdmin)
|
|
|
|
|
modeladmin_register(MyModelAdminGroup)
|
|
|
|
|
modeladmin_register(MyOtherModelAdminGroup)
|
|
|
|
|
|