Viewsets¶
Viewsets are Wagtail’s mechanism for defining a group of related admin views with shared properties, as a single unit.
ViewSet¶
- class wagtail.admin.viewsets.base.ViewSet(name=None, **kwargs)¶
Defines a viewset to be registered with the Wagtail admin.
All properties of the viewset can be defined as class-level attributes, or passed as keyword arguments to the constructor (in which case they will override any class-level attributes). Additionally, the
name
property can be passed as the first positional argument to the constructor.For more information on how to use this class, see Using ViewSet to group custom admin views.
- name = None¶
A name for this viewset, used as the default URL prefix and namespace.
- url_prefix¶
The preferred URL prefix for views within this viewset. When registered through Wagtail’s register_admin_viewset hook, this will be used as the URL path component following
/admin/
. Other URL registration mechanisms (e.g. editingurls.py
manually) may disregard this and use a prefix of their own choosing.Defaults to the viewset’s
name
.
- url_namespace¶
The URL namespace for views within this viewset. Will be used internally as the application namespace for the viewset’s URLs, and generally be the instance namespace too.
Defaults to the viewset’s
name
.
- on_register()¶
Called when the viewset is registered; subclasses can override this to perform additional setup.
- get_urlpatterns()¶
Returns a set of URL routes to be registered with the Wagtail admin.
- get_url_name(view_name)¶
Returns the namespaced URL name for the given view.
- icon = ''¶
The icon to use across the views.
The icon used for the menu item that appears in Wagtail’s sidebar.
Defaults to
icon
.
The displayed label used for the menu item.
The
name
argument passed to theMenuItem
constructor, becoming thename
attribute value for that instance. This can be useful when manipulating the menu items in a custom menu hook, e.g. construct_main_menu. If unset, a slugified version ofmenu_label
is used.
An integer determining the order of the menu item, 0 being the first place. By default, it will be the last item before Reports, whose order is 9000.
The URL to be used for the menu item.
Defaults to the first URL returned by
get_urlpatterns()
.
A
wagtail.admin.menu.MenuItem
subclass to be registered with a menu hook.
The name of the hook to register the menu item within.
This takes precedence over
add_to_admin_menu
andadd_to_settings_menu
.
Register the menu item within the admin’s main menu.
Register the menu item within the admin’s “Settings” menu. This takes precedence if both
add_to_admin_menu
andadd_to_settings_menu
are set toTrue
.
Returns a
wagtail.admin.menu.MenuItem
instance to be registered with the Wagtail admin.The
order
parameter allows the method to be called from the outside (e.g. aViewSetGroup
) to create a sub menu item with the correct order.
ViewSetGroup¶
- class wagtail.admin.viewsets.base.ViewSetGroup¶
A container for grouping together multiple
ViewSet
instances. Creates a menu item with a submenu for accessing the main URL for each instances.For more information on how to use this class, see Combining multiple ViewSets using a ViewSetGroup.
The icon used for the menu item that appears in Wagtail’s sidebar.
The displayed label used for the menu item.
The
name
argument passed to theMenuItem
constructor, becoming thename
attribute value for that instance. This can be useful when manipulating the menu items in a custom menu hook, e.g. construct_main_menu. If unset, a slugified version ofmenu_label
is used.
An integer determining the order of the menu item, 0 being the first place. By default, it will be the last item before Reports, whose order is 9000.
A
wagtail.admin.menu.MenuItem
subclass to be registered with a menu hook.
Register the menu item within the admin’s main menu.
Returns a
wagtail.admin.menu.MenuItem
instance to be registered with the Wagtail admin.The
order
parameter allows the method to be called from the outside (e.g. aViewSetGroup
) to create a sub menu item with the correct order.
ModelViewSet¶
- class wagtail.admin.viewsets.model.ModelViewSet(name=None, **kwargs)¶
A viewset to allow listing, creating, editing and deleting model instances.
All attributes and methods from
ViewSet
are available.For more information on how to use this class, see Generic views.
- model¶
Required; the model class that this viewset will work with. The
model_name
will be used as the URL prefix and namespace, unless these are specified explicitly via thename
,url_prefix
orurl_namespace
attributes.- form_fields¶
A list of model field names that should be included in the create / edit forms.
- exclude_form_fields¶
Used in place of
form_fields
to indicate that all of the model’s fields except the ones listed here should appear in the create / edit forms. Eitherform_fields
orexclude_form_fields
must be supplied (unlessget_form_class()
is being overridden).- get_form_class(for_update=False)¶
Returns the form class to use for the create / edit forms.
- get_edit_handler()¶
Returns the appropriate edit handler for this
ModelViewSet
class. It can be defined either on the model itself or on theModelViewSet
, as theedit_handler
orpanels
properties. If none of these are defined, it will returnNone
and the form will be constructed as a Django form usingget_form_class()
(without using Panels).
The displayed label used for the menu item.
Defaults to the title-cased version of the model’s
verbose_name_plural
.
- add_to_reference_index = True¶
Register the model to the reference index to track its usage. For more details, see Managing the Reference Index.
- ordering = None¶
The default ordering to use for the index view. Can be a string or a list/tuple in the same format as Django’s
ordering
.
- list_per_page = 20¶
The number of items to display per page in the index view. Defaults to 20.
- list_display¶
A list or tuple, where each item is either:
The name of a field on the model;
The name of a callable or property on the model that accepts a single parameter for the model instance; or
An instance of the
wagtail.admin.ui.tables.Column
class.
If the name refers to a database field, the ability to sort the listing by the database column will be offerred and the field’s verbose name will be used as the column header.
If the name refers to a callable or property, an
admin_order_field
attribute can be defined on it to point to the database column for sorting. Ashort_description
attribute can also be defined on the callable or property to be used as the column header.This list will be passed to the
list_display
attribute of the index view. If left unset, thelist_display
attribute of the index view will be used instead, which by default is defined as["__str__", wagtail.admin.ui.tables.UpdatedAtColumn()]
.
- list_export¶
A list or tuple, where each item is the name of a field, an attribute, or a single-argument callable on the model to be exported.
- list_filter¶
A list or tuple, where each item is the name of model fields of type
BooleanField
,CharField
,DateField
,DateTimeField
,IntegerField
orForeignKey
. Alternatively, it can also be a dictionary that maps a field name to a list of lookup expressions. This will be passed as django-filter’sFilterSet.Meta.fields
attribute. See its documentation for more details. Iffilterset_class
is set, this attribute will be ignored.
- filterset_class¶
A subclass of
wagtail.admin.filters.WagtailFilterSet
, which is a subclass of django_filters.FilterSet. This will be passed to thefilterset_class
attribute of the index view.
- export_headings¶
A dictionary of export column heading overrides in the format
{field_name: heading}
.
- export_filename¶
The base file name for the exported listing, without extensions. If unset, the model’s
db_table
will be used instead.
- search_fields¶
The fields to use for the search in the index view. If set to
None
andsearch_backend_name
is set to use a Wagtail search backend, thesearch_fields
attribute of the model will be used instead.
- search_backend_name¶
The name of the Wagtail search backend to use for the search in the index view. If set to a falsy value, the search will fall back to use Django’s QuerySet API.
- copy_view_enabled = True¶
Whether to enable the copy view. Defaults to
True
.
- inspect_view_enabled = False¶
Whether to enable the inspect view. Defaults to
False
.
- inspect_view_fields = []¶
The model fields or attributes to display in the inspect view.
If the field has a corresponding
get_FOO_display()
method on the model, the method’s return value will be used instead.If you have
wagtail.images
installed, and the field’s value is an instance ofwagtail.images.models.AbstractImage
, a thumbnail of that image will be rendered.If you have
wagtail.documents
installed, and the field’s value is an instance ofwagtail.docs.models.AbstractDocument
, a link to that document will be rendered, along with the document title, file extension and size.
- inspect_view_fields_exclude = []¶
The fields to exclude from the inspect view.
- index_view_class = <class 'wagtail.admin.views.generic.models.IndexView'>¶
The view class to use for the index view; must be a subclass of
wagtail.admin.views.generic.IndexView
.
- add_view_class = <class 'wagtail.admin.views.generic.models.CreateView'>¶
The view class to use for the create view; must be a subclass of
wagtail.admin.views.generic.CreateView
.
- edit_view_class = <class 'wagtail.admin.views.generic.models.EditView'>¶
The view class to use for the edit view; must be a subclass of
wagtail.admin.views.generic.EditView
.
- delete_view_class = <class 'wagtail.admin.views.generic.models.DeleteView'>¶
The view class to use for the delete view; must be a subclass of
wagtail.admin.views.generic.DeleteView
.
- usage_view_class = <class 'wagtail.admin.views.generic.usage.UsageView'>¶
The view class to use for the usage view; must be a subclass of
wagtail.admin.views.generic.usage.UsageView
.
- history_view_class = <class 'wagtail.admin.views.generic.history.HistoryView'>¶
The view class to use for the history view; must be a subclass of
wagtail.admin.views.generic.history.HistoryView
.
- copy_view_class = <class 'wagtail.admin.views.generic.models.CopyView'>¶
The view class to use for the copy view; must be a subclass of
wagtail.admin.views.generic.CopyView
.
- inspect_view_class = <class 'wagtail.admin.views.generic.models.InspectView'>¶
The view class to use for the inspect view; must be a subclass of
wagtail.admin.views.generic.InspectView
.
- template_prefix = ''¶
The prefix of template names to look for when rendering the admin views.
- index_template_name¶
A template to be used when rendering
index_view
.Default: if
template_prefix
is specified, anindex.html
template in the prefix directory and its{app_label}/{model_name}/
or{app_label}/
subdirectories will be used. Otherwise, theindex_view_class.template_name
will be used.
- index_results_template_name¶
A template to be used when rendering
index_results_view
.Default: if
template_prefix
is specified, aindex_results.html
template in the prefix directory and its{app_label}/{model_name}/
or{app_label}/
subdirectories will be used. Otherwise, theindex_view_class.results_template_name
will be used.
- create_template_name¶
A template to be used when rendering
add_view
.Default: if
template_prefix
is specified, acreate.html
template in the prefix directory and its{app_label}/{model_name}/
or{app_label}/
subdirectories will be used. Otherwise, theadd_view_class.template_name
will be used.
- edit_template_name¶
A template to be used when rendering
edit_view
.Default: if
template_prefix
is specified, anedit.html
template in the prefix directory and its{app_label}/{model_name}/
or{app_label}/
subdirectories will be used. Otherwise, theedit_view_class.template_name
will be used.
- delete_template_name¶
A template to be used when rendering
delete_view
.Default: if
template_prefix
is specified, aconfirm_delete.html
template in the prefix directory and its{app_label}/{model_name}/
or{app_label}/
subdirectories will be used. Otherwise, thedelete_view_class.template_name
will be used.
- history_template_name¶
A template to be used when rendering
history_view
.Default: if
template_prefix
is specified, ahistory.html
template in the prefix directory and its{app_label}/{model_name}/
or{app_label}/
subdirectories will be used. Otherwise, thehistory_view_class.template_name
will be used.
- inspect_template_name¶
A template to be used when rendering
inspect_view
.Default: if
template_prefix
is specified, aninspect.html
template in the prefix directory and its{app_label}/{model_name}/
or{app_label}/
subdirectories will be used. Otherwise, theinspect_view_class.template_name
will be used.
ModelViewSetGroup¶
- class wagtail.admin.viewsets.model.ModelViewSetGroup¶
A container for grouping together multiple
ModelViewSet
instances.All attributes and methods from
ViewSetGroup
are available.The displayed label used for the menu item.
If unset, defaults to the title-cased version of the model’s
app_label
from the first viewset.
ChooserViewSet¶
- class wagtail.admin.viewsets.chooser.ChooserViewSet(*args, **kwargs)¶
A viewset that creates a chooser modal interface for choosing model instances.
- model¶
Required; the model class that this viewset will work with.
- icon = 'snippet'¶
The icon to use in the header of the chooser modal, and on the chooser widget
- choose_one_text = 'Choose'¶
Label for the ‘choose’ button in the chooser widget when choosing an initial item
- page_title = None¶
Title text for the chooser modal (defaults to the same as
choose_one_text
)`
- choose_another_text = 'Choose another'¶
Label for the ‘choose’ button in the chooser widget, when an item has already been chosen
- edit_item_text = 'Edit'¶
Label for the ‘edit’ button in the chooser widget
- per_page = 10¶
Number of results to show per page
- preserve_url_parameters = ['multiple']¶
A list of URL query parameters that should be passed on unmodified as part of any links or form submissions within the chooser modal workflow.
- url_filter_parameters = []¶
A list of URL query parameters that, if present in the url, should be applied as filters to the queryset. (These should also be listed in preserve_url_parameters.)
- choose_view_class = <class 'wagtail.admin.views.generic.chooser.ChooseView'>¶
The view class to use for the overall chooser modal; must be a subclass of
wagtail.admin.views.generic.chooser.ChooseView
.
- choose_results_view_class = <class 'wagtail.admin.views.generic.chooser.ChooseResultsView'>¶
The view class used to render just the results panel within the chooser modal; must be a subclass of
wagtail.admin.views.generic.chooser.ChooseResultsView
.
- chosen_view_class = <class 'wagtail.admin.views.generic.chooser.ChosenView'>¶
The view class used after an item has been chosen; must be a subclass of
wagtail.admin.views.generic.chooser.ChosenView
.
- chosen_multiple_view_class = <class 'wagtail.admin.views.generic.chooser.ChosenMultipleView'>¶
The view class used after multiple items have been chosen; must be a subclass of
wagtail.admin.views.generic.chooser.ChosenMultipleView
.
- create_view_class = <class 'wagtail.admin.views.generic.chooser.CreateView'>¶
The view class used to handle submissions of the ‘create’ form; must be a subclass of
wagtail.admin.views.generic.chooser.CreateView
.
- base_widget_class = <class 'wagtail.admin.widgets.chooser.BaseChooser'>¶
The base Widget class that the chooser widget will be derived from.
- widget_class¶
Returns the form widget class for this chooser.
- widget_telepath_adapter_class = None¶
The adapter class used to map the widget class to its JavaScript implementation - see Form widget client-side API. Only required if the chooser uses custom JavaScript code.
- register_widget = True¶
Defaults to True; if False, the chooser widget will not automatically be registered for use in admin forms.
- base_block_class = <class 'wagtail.blocks.field_block.ChooserBlock'>¶
The base ChooserBlock class that the StreamField chooser block will be derived from.
- get_block_class(name=None, module_path=None)¶
Returns a StreamField ChooserBlock class using this chooser.
- Parameters:
name – Name to give to the class; defaults to the model name with “ChooserBlock” appended
module_path – The dotted path of the module where the class can be imported from; used when deconstructing the block definition for migration files.
- creation_form_class = None¶
Form class to use for the form in the “Create” tab of the modal.
- form_fields = None¶
List of model fields that should be included in the creation form, if creation_form_class is not specified.
- exclude_form_fields = None¶
List of model fields that should be excluded from the creation form, if creation_form_class. If none of
creation_form_class
,form_fields
orexclude_form_fields
are specified, the “Create” tab will be omitted.
- create_action_label = 'Create'¶
Label for the submit button on the ‘create’ form
- create_action_clicked_label = None¶
Alternative text to display on the submit button after it has been clicked
- creation_tab_label = None¶
Label for the ‘create’ tab in the chooser modal (defaults to the same as create_action_label)
- search_tab_label = 'Search'¶
Label for the ‘search’ tab in the chooser modal
- get_object_list()¶
Returns a queryset of objects that are available to be chosen. By default, all instances of
model
are returned.
SnippetViewSet¶
- class wagtail.snippets.views.snippets.SnippetViewSet(**kwargs)¶
A viewset that instantiates the admin views for snippets.
All attributes and methods from
ModelViewSet
are available.For more information on how to use this class, see Customizing admin views for snippets.
- model = None¶
The model class to be registered as a snippet with this viewset.
- chooser_per_page = 10¶
The number of items to display in the chooser view. Defaults to 10.
- admin_url_namespace = None¶
The URL namespace to use for the admin views. If left unset,
wagtailsnippets_{app_label}_{model_name}
is used instead.Deprecated - the preferred attribute to customise is
url_namespace
.
- base_url_path = None¶
The base URL path to use for the admin views. If left unset,
snippets/{app_label}/{model_name}
is used instead.Deprecated - the preferred attribute to customise is
url_prefix
.
- chooser_admin_url_namespace = None¶
The URL namespace to use for the chooser admin views. If left unset,
wagtailsnippetchoosers_{app_label}_{model_name}
is used instead.
- chooser_base_url_path = None¶
The base URL path to use for the chooser admin views. If left unset,
snippets/choose/{app_label}/{model_name}
is used instead.
- index_view_class = <class 'wagtail.snippets.views.snippets.IndexView'>¶
The view class to use for the index view; must be a subclass of
wagtail.snippets.views.snippets.IndexView
.
- add_view_class = <class 'wagtail.snippets.views.snippets.CreateView'>¶
The view class to use for the create view; must be a subclass of
wagtail.snippets.views.snippets.CreateView
.
- edit_view_class = <class 'wagtail.snippets.views.snippets.EditView'>¶
The view class to use for the edit view; must be a subclass of
wagtail.snippets.views.snippets.EditView
.
- delete_view_class = <class 'wagtail.snippets.views.snippets.DeleteView'>¶
The view class to use for the delete view; must be a subclass of
wagtail.snippets.views.snippets.DeleteView
.
- usage_view_class = <class 'wagtail.snippets.views.snippets.UsageView'>¶
The view class to use for the usage view; must be a subclass of
wagtail.snippets.views.snippets.UsageView
.
- history_view_class = <class 'wagtail.snippets.views.snippets.HistoryView'>¶
The view class to use for the history view; must be a subclass of
wagtail.snippets.views.snippets.HistoryView
.
- copy_view_class = <class 'wagtail.snippets.views.snippets.CopyView'>¶
The view class to use for the copy view; must be a subclass of
wagtail.snippet.views.snippets.CopyView
.
- inspect_view_class = <class 'wagtail.snippets.views.snippets.InspectView'>¶
The view class to use for the inspect view; must be a subclass of
wagtail.snippets.views.snippets.InspectView
.
- revisions_view_class = <class 'wagtail.snippets.views.snippets.PreviewRevisionView'>¶
The view class to use for previewing revisions; must be a subclass of
wagtail.snippets.views.snippets.PreviewRevisionView
.
- revisions_revert_view_class¶
The view class to use for reverting to a previous revision.
By default, this class is generated by combining the edit view with
wagtail.admin.views.generic.mixins.RevisionsRevertMixin
. As a result, this class must be a subclass ofwagtail.snippets.views.snippets.EditView
and must handle the reversion correctly.
- revisions_compare_view_class = <class 'wagtail.snippets.views.snippets.RevisionsCompareView'>¶
The view class to use for comparing revisions; must be a subclass of
wagtail.snippets.views.snippets.RevisionsCompareView
.
- revisions_unschedule_view_class = <class 'wagtail.snippets.views.snippets.RevisionsUnscheduleView'>¶
The view class to use for unscheduling revisions; must be a subclass of
wagtail.snippets.views.snippets.RevisionsUnscheduleView
.
- unpublish_view_class = <class 'wagtail.snippets.views.snippets.UnpublishView'>¶
The view class to use for unpublishing a snippet; must be a subclass of
wagtail.snippets.views.snippets.UnpublishView
.
- preview_on_add_view_class = <class 'wagtail.snippets.views.snippets.PreviewOnCreateView'>¶
The view class to use for previewing on the create view; must be a subclass of
wagtail.snippets.views.snippets.PreviewOnCreateView
.
- preview_on_edit_view_class = <class 'wagtail.snippets.views.snippets.PreviewOnEditView'>¶
The view class to use for previewing on the edit view; must be a subclass of
wagtail.snippets.views.snippets.PreviewOnEditView
.
- lock_view_class = <class 'wagtail.snippets.views.snippets.LockView'>¶
The view class to use for locking a snippet; must be a subclass of
wagtail.snippets.views.snippets.LockView
.
- unlock_view_class = <class 'wagtail.snippets.views.snippets.UnlockView'>¶
The view class to use for unlocking a snippet; must be a subclass of
wagtail.snippets.views.snippets.UnlockView
.
- chooser_viewset_class = <class 'wagtail.snippets.views.chooser.SnippetChooserViewSet'>¶
The ViewSet class to use for the chooser views; must be a subclass of
wagtail.snippets.views.chooser.SnippetChooserViewSet
.
- get_queryset(request)¶
Returns a QuerySet of all model instances to be shown on the index view. If
None
is returned (the default), the logic inindex_view.get_base_queryset()
will be used instead.
- get_edit_handler()¶
Like
ModelViewSet.get_edit_handler()
, but falls back to extracting panel definitions from the model class if no edit handler is defined.
- get_index_template()¶
Returns a template to be used when rendering
index_view
. If a template is specified by theindex_template_name
attribute, that will be used. Otherwise, a list of preferred template names are returned.Deprecated - the preferred way to customise this is to define an
index_template_name
property.
- get_index_results_template()¶
Returns a template to be used when rendering
index_results_view
. If a template is specified by theindex_results_template_name
attribute, that will be used. Otherwise, a list of preferred template names are returned.Deprecated - the preferred way to customise this is to define an
index_results_template_name
property.
- get_create_template()¶
Returns a template to be used when rendering
add_view
. If a template is specified by thecreate_template_name
attribute, that will be used. Otherwise, a list of preferred template names are returned.Deprecated - the preferred way to customise this is to define a
create_template_name
property.
- get_edit_template()¶
Returns a template to be used when rendering
edit_view
. If a template is specified by theedit_template_name
attribute, that will be used. Otherwise, a list of preferred template names are returned.Deprecated - the preferred way to customise this is to define an
edit_template_name
property.
- get_delete_template()¶
Returns a template to be used when rendering
delete_view
. If a template is specified by thedelete_template_name
attribute, that will be used. Otherwise, a list of preferred template names are returned.Deprecated - the preferred way to customise this is to define a
delete_template_name
property.
- get_history_template()¶
Returns a template to be used when rendering
history_view
. If a template is specified by thehistory_template_name
attribute, that will be used. Otherwise, a list of preferred template names are returned.Deprecated - the preferred way to customise this is to define a
history_template_name
property.
- get_inspect_template()¶
Returns a template to be used when rendering
inspect_view
. If a template is specified by theinspect_template_name
attribute, that will be used. Otherwise, a list of preferred template names are returned.Deprecated - the preferred way to customise this is to define an
inspect_template_name
property.
- get_admin_url_namespace()¶
Returns the URL namespace for the admin URLs for this model.
Deprecated - the preferred way to customise this is to define a
url_namespace
property.
- get_admin_base_path()¶
Returns the base path for the admin URLs for this model. The returned string must not begin or end with a slash.
Deprecated - the preferred way to customise this is to define a
url_prefix
property.
- get_chooser_admin_url_namespace()¶
Returns the URL namespace for the chooser admin URLs for this model.
- get_chooser_admin_base_path()¶
Returns the base path for the chooser admin URLs for this model. The returned string must not begin or end with a slash.
SnippetViewSetGroup¶
- class wagtail.snippets.views.snippets.SnippetViewSetGroup¶
A container for grouping together multiple
SnippetViewSet
instances.All attributes and methods from
ModelViewSetGroup
are available.