Viewsets

Viewsets are Wagtail’s mechanism for defining a group of related admin views with shared properties, as a single unit. See Generic views.

ViewSet

class wagtail.admin.viewsets.base.ViewSet(name, **kwargs)

Defines a viewset to be registered with the Wagtail admin.

Parameters:

  • name – A name for this viewset, used as the URL namespace.

  • url_prefix – A URL path element, given as a string, that the URLs for this viewset will be found under. Defaults to the same as name.

All other keyword arguments will be set as attributes on the instance.

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.

ModelViewSet

class wagtail.admin.viewsets.model.ModelViewSet(name, **kwargs)

A viewset to allow listing, creating, editing and deleting model instances.

model

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

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.

icon = ''

The icon to use to represent the model within this viewset.

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.

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.

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

SnippetViewSet

class wagtail.snippets.views.snippets.SnippetViewSet(model=None, **kwargs)

A viewset that instantiates the admin views for snippets.

model = None

The model class to be registered as a snippet with this viewset.

icon = 'snippet'

The icon to use across the admin for this snippet type.

add_to_admin_menu = False

Register a custom menu item for this snippet type in the admin’s main menu.

add_to_settings_menu = False

Register a custom menu item for this snippet type in the admin’s “Settings” menu. This takes precedence if both add_to_admin_menu and add_to_settings_menu are set to True.

menu_label = None

The displayed label used for the menu item that appears in Wagtail’s sidebar. If unset, the title-cased version of the model’s verbose_name_plural will be used.

menu_name = None

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 the label is used.

menu_order = None

An integer determining the order of the menu item, 0 being the first place. If the viewset is registered within a SnippetViewSetGroup, this is ignored and the menu item order is determined by the order of items.

list_display = None

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, a 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.

list_filter = None

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 = None

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.

search_fields = None

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 = 'default'

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.

list_per_page = 20

The number of items to display per page in the index view. Defaults to 20.

chooser_per_page = 10

The number of items to display in the chooser view. Defaults to 10.

export_filename = None

The base file name for the exported listing, without extensions. If unset, the model’s db_table will be used instead.

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.

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.

admin_url_namespace = None

The URL namespace to use for the admin views. If left unset, wagtailsnippets_{app_label}_{model_name} is used instead.

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.

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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.views.snippets.HistoryView.

inspect_view_class = <class 'wagtail.snippets.views.snippets.InspectView'>

The view class to use for the inspect view; must be a subclass of wagtail.snippet.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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.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.snippet.views.chooser.SnippetChooserViewSet.

template_prefix = 'wagtailsnippets/snippets/'

The prefix of template names to look for when rendering the admin views.

index_template_name = ''

The template to use for the index view.

index_results_template_name = ''

The template to use for the results in the index view.

create_template_name = ''

The template to use for the create view.

edit_template_name = ''

The template to use for the edit view.

delete_template_name = ''

The template to use for the delete view.

history_template_name = ''

The template to use for the history view.

get_menu_label()

Returns the label text to be used for the menu item.

get_menu_name()

Returns the name to be used for the menu item.

get_menu_icon()

Returns the icon to be used for the menu item.

get_menu_order()

Returns the ordering number to be applied to the menu item.

get_menu_item(order=None)

Returns a MenuItem instance to be registered with the Wagtail admin.

The order parameter allows the method to be called from the outside (e.g. SnippetViewSetGroup) to create a sub menu item with the correct order.

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()

Returns the appropriate edit handler for this SnippetViewSet class. It can be defined either on the model itself or on the SnippetViewSet, as the edit_handler or panels properties. Falls back to extracting panel / edit handler definitions from the model class.

get_form_class(for_update=False)

Returns the form class to use for the create / edit forms.

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.

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.

get_create_template()

Returns a template to be used when rendering create_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.

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.

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.

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.

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.

get_admin_url_namespace()

Returns the URL namespace for the admin URLs for this model.

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.

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. Creates a menu item with a submenu for accessing the listing pages of those instances.

items = ()

A list or tuple of SnippetViewSet classes to be grouped together

add_to_admin_menu = True

Register a custom menu item for the group in the admin’s main menu.

menu_label = None

The displayed label used for the menu item. If unset, the title-cased version of the first model’s app_label will be used.

menu_name = None

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 the label is used.

menu_icon = None

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

menu_order = None

An integer determining the order of the menu item, 0 being the first place.

get_menu_label()

Returns the label text to be used for the menu item.

get_menu_name()

Returns the name to be used for the menu item.

get_menu_icon()

Returns the icon to be used for the menu item.

get_menu_order()

Returns the ordering number to be applied to the menu item.

get_menu_item()

Returns a MenuItem instance to be registered with the Wagtail admin.