Viewsets¶

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. editing urls.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.

menu_icon¶

The icon used for the menu item that appears in Wagtail’s sidebar.

Defaults to icon.

menu_label = ''¶

The displayed label used for the menu item.

menu_name = ''¶

The name argument passed to the MenuItem constructor, becoming the name 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 of menu_label is used.

menu_order = 8999¶

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.

menu_url¶

The URL to be used for the menu item.

Defaults to the first URL returned by get_urlpatterns().

menu_item_class¶

A wagtail.admin.menu.MenuItem subclass to be registered with a menu hook.

menu_hook¶

The name of the hook to register the menu item within.

This takes precedence over add_to_admin_menu and add_to_settings_menu.

add_to_admin_menu = False¶

Register the menu item within the admin’s main menu.

add_to_settings_menu = False¶

Register the menu item within the admin’s “Settings” menu. This takes precedence if both add_to_admin_menu and add_to_settings_menu are set to True.

get_menu_item(order=None)¶

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. a ViewSetGroup) to create a sub menu item with the correct order.

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.

items = ()¶

A list or tuple of ViewSet classes or instances to be grouped together.

menu_icon = 'folder-open-inverse'¶

The icon used for the menu item that appears in Wagtail’s sidebar.

menu_label = ''¶

The displayed label used for the menu item.

menu_name = ''¶

The name argument passed to the MenuItem constructor, becoming the name 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 of menu_label is used.

menu_order = 8999¶

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.

menu_item_class¶

A wagtail.admin.menu.MenuItem subclass to be registered with a menu hook.

add_to_admin_menu = True¶

Register the menu item within the admin’s main menu.

get_menu_item(order=None)¶

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. a ViewSetGroup) to create a sub menu item with the correct order.

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 the name, url_prefix or url_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. Either form_fields or exclude_form_fields must be supplied (unless get_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 the ModelViewSet, as the edit_handler or panels properties. If none of these are defined, it will return None and the form will be constructed as a Django form using get_form_class() (without using Panels).

menu_label¶

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. A short_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, the list_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 or ForeignKey. 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’s FilterSet.Meta.fields attribute. See its documentation for more details. If filterset_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 the filterset_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 and search_backend_name is set to use a Wagtail search backend, the search_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 of wagtail.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 of wagtail.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, an index.html template in the prefix directory and its {app_label}/{model_name}/ or {app_label}/ subdirectories will be used. Otherwise, the index_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, a index_results.html template in the prefix directory and its {app_label}/{model_name}/ or {app_label}/ subdirectories will be used. Otherwise, the index_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, a create.html template in the prefix directory and its {app_label}/{model_name}/ or {app_label}/ subdirectories will be used. Otherwise, the add_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, an edit.html template in the prefix directory and its {app_label}/{model_name}/ or {app_label}/ subdirectories will be used. Otherwise, the edit_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, a confirm_delete.html template in the prefix directory and its {app_label}/{model_name}/ or {app_label}/ subdirectories will be used. Otherwise, the delete_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, a history.html template in the prefix directory and its {app_label}/{model_name}/ or {app_label}/ subdirectories will be used. Otherwise, the history_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, an inspect.html template in the prefix directory and its {app_label}/{model_name}/ or {app_label}/ subdirectories will be used. Otherwise, the inspect_view_class.template_name will be used.

A container for grouping together multiple ModelViewSet instances.

All attributes and methods from ViewSetGroup are available.

menu_label¶

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.

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 or exclude_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.

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 of wagtail.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 in index_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 the index_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 the index_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 the create_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 the edit_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 the delete_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 the history_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 the inspect_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.

A container for grouping together multiple SnippetViewSet instances.

All attributes and methods from ModelViewSetGroup are available.

A viewset to present a flat listing of all pages of a specific type. All attributes and methods from ViewSet are available. For more information on how to use this class, see Custom page listings.

model = <class 'wagtail.models.Page'>¶

Required; the page model class that this viewset will work with.

index_view_class = <class 'wagtail.admin.views.pages.listing.IndexView'>¶

The view class to use for the index view; must be a subclass of wagtail.admin.views.pages.listing.IndexView.

choose_parent_view_class = <class 'wagtail.admin.views.pages.choose_parent.ChooseParentView'>¶

The view class to use for choosing the parent page when creating a new page of this page type.

columns = [<wagtail.admin.ui.tables.pages.BulkActionsColumn: bulk_actions>, <wagtail.admin.ui.tables.pages.PageTitleColumn: title>, <wagtail.admin.ui.tables.DateColumn: latest_revision_created_at>, <wagtail.admin.ui.tables.pages.PageStatusColumn: status>]¶

A list of wagtail.admin.ui.tables.Column instances for the columns in the listing.

filterset_class = <class 'wagtail.admin.views.pages.listing.PageFilterSet'>¶

A subclass of wagtail.admin.filters.WagtailFilterSet, which is a subclass of django_filters.FilterSet. This will be passed to the filterset_class attribute of the index view.