Documentation for ChooserViewSet

docs/extending/generic_views.md

@@ -46,3 +46,37 @@ def register_viewset():
 ```
 
 Various additional attributes are available to customise the viewset - see [](../reference/viewsets).
+
+
+ChooserViewSet
+--------------
+
+The `wagtail.admin.viewsets.chooser.ChooserViewSet` class provides the views that make up a modal chooser interface, allowing users to select from a list of model instances to populate a ForeignKey field. Using the same `Person` model, the following definition (to be placed in `views.py`) will generate the views for a person chooser modal:
+
+```python
+from wagtail.admin.viewsets.chooser import ChooserViewSet
+from .models import Person
+
+
+class PersonChooserViewSet(ChooserViewSet):
+    model = People
+    icon = "user"
+    choose_one_text = "Choose a person"
+    choose_another_text = "Choose another person"
+    edit_item_text = "Edit this person"
+```
+
+Again this can be registered with the `register_admin_viewset` hook:
+
+```python
+from wagtail import hooks
+
+from .views import PersonChooserViewSet
+
+
+@hooks.register("register_admin_viewset")
+def register_viewset():
+    return PersonChooserViewSet("person_chooser")
+```
+
+Registering a chooser viewset will also set up a chooser widget to be used whenever a ForeignKey field to that model appears in a `WagtailAdminModelForm` - see [](./forms). In particular, this means that a panel definition such as `FieldPanel("author")`, where `author` is a foreign key to the `Person` model, will automatically use this chooser interface.

docs/reference/viewsets.md

@@ -37,4 +37,26 @@ ModelViewSet
    .. autoattribute:: add_view_class
    .. autoattribute:: edit_view_class
    .. autoattribute:: delete_view_class
+
+
+ChooserViewSet
+--------------
+
+.. autoclass:: wagtail.admin.viewsets.chooser.ChooserViewSet
+
+   .. attribute:: model
+
+   Required; the model class that this viewset will work with.
+
+   .. autoattribute:: icon
+   .. autoattribute:: choose_one_text
+   .. autoattribute:: page_title
+   .. autoattribute:: choose_another_text
+   .. autoattribute:: edit_item_text
+   .. autoattribute:: choose_view_class
+   .. autoattribute:: choose_results_view_class
+   .. autoattribute:: chosen_view_class
+   .. autoattribute:: widget_class
+   .. autoattribute:: register_widget
+
 ```

wagtail/admin/viewsets/chooser.py

@@ -11,17 +11,33 @@ from .base import ViewSet
 
 
 class ChooserViewSet(ViewSet):
-    icon = "snippet"
-    choose_one_text = _("Choose")
-    page_title = None
-    choose_another_text = _("Choose another")
-    edit_item_text = _("Edit")
+    """
+    A viewset that creates a chooser modal interface for choosing model instances.
+    """
 
+    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
+
+    #: The view class to use for the overall chooser modal; must be a subclass of ``wagtail.admin.views.generic.chooser.ChooseView``.
     choose_view_class = chooser_views.ChooseView
+
+    #: 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``.
     choose_results_view_class = chooser_views.ChooseResultsView
+
+    #: The view class used after an item has been chosen; must be a subclass of ``wagtail.admin.views.generic.chooser.ChosenView``.
     chosen_view_class = chooser_views.ChosenView
+
+    #: The base Widget class that the chooser widget will be derived from.
     base_widget_class = BaseChooser
 
+    #: Defaults to True; if False, the chooser widget will not automatically be registered for use in admin forms.
     register_widget = True
 
     def __init__(self, *args, **kwargs):
@@ -55,6 +71,9 @@ class ChooserViewSet(ViewSet):
 
     @cached_property
     def widget_class(self):
+        """
+        Returns the form widget class for this chooser.
+        """
         return type(
             "%sChooserWidget" % self.model.__name__,
             (self.base_widget_class,),