Add docs and tests for separate menu item registrations for Snippets

docs/reference/viewsets.md

@@ -80,6 +80,11 @@ Viewsets are Wagtail's mechanism for defining a group of related admin views wit
 .. autoclass:: wagtail.snippets.views.snippets.SnippetViewSet
 
    .. autoattribute:: icon
+   .. autoattribute:: add_to_admin_menu
+   .. autoattribute:: add_to_settings_menu
+   .. autoattribute:: menu_label
+   .. autoattribute:: menu_name
+   .. autoattribute:: menu_order
    .. autoattribute:: list_display
    .. autoattribute:: list_filter
    .. autoattribute:: filterset_class
@@ -114,6 +119,11 @@ Viewsets are Wagtail's mechanism for defining a group of related admin views wit
    .. autoattribute:: edit_template_name
    .. autoattribute:: delete_template_name
    .. autoattribute:: history_template_name
+   .. automethod:: get_menu_label
+   .. automethod:: get_menu_name
+   .. automethod:: get_menu_icon
+   .. automethod:: get_menu_order
+   .. automethod:: get_menu_item
    .. automethod:: get_queryset
    .. automethod:: get_edit_handler
    .. automethod:: get_form_class

docs/topics/snippets.md

@@ -643,3 +643,27 @@ register_snippet(Member, viewset=MemberViewSet)
 The `viewset` parameter of `register_snippet` also accepts a dotted module path to the subclass, e.g. `"myapp.views.MemberViewSet"`.
 
 Various additional attributes are available to customise the viewset - see {class}`~wagtail.snippets.views.snippets.SnippetViewSet`.
+
+## Customising the menu item
+
+```{versionadded} 5.0
+The ability to have a separate menu item was added.
+```
+
+By default, registering a snippet model will add a "Snippets" menu item to the sidebar menu. You can configure a snippet model to have its own top-level menu item in the sidebar menu by setting {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.add_to_admin_menu` to `True`. Alternatively, if you want to add the menu item inside the Settings menu, you can set {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.add_to_settings_menu` to `True`. The menu item will use the icon specified on the `SnippetViewSet` and it will link to the index view for the snippet model.
+
+Unless specified, the menu item will be named after the model's verbose name. You can customise the menu item's label, name, and order by setting the {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.menu_label`, {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.menu_icon`, and {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.menu_order` attributes respectively. If you would like to customise the `MenuItem` instance completely, you could override the {meth}`~wagtail.snippets.views.snippets.SnippetViewSet.get_menu_item` method.
+
+An example of a custom `SnippetViewSet` subclass with `add_to_admin_menu` set to `True`:
+
+```python
+from wagtail.snippets.views.snippets import SnippetViewSet
+
+
+class AdvertViewSet(SnippetViewSet):
+    icon = "crosshairs"
+    menu_label = "Advertisements"
+    menu_name = "adverts"
+    menu_order = 300
+    add_to_admin_menu = True
+```

wagtail/snippets/tests/test_viewset.py

@@ -5,6 +5,7 @@ from django.urls import reverse
 from django.utils.timezone import now
 
 from wagtail.admin.admin_url_finder import AdminURLFinder
+from wagtail.admin.menu import admin_menu, settings_menu
 from wagtail.admin.panels import get_edit_handler
 from wagtail.admin.staticfiles import versioned_static
 from wagtail.blocks.field_block import FieldBlockAdapter
@@ -822,3 +823,28 @@ class TestDjangoORMSearchBackend(BaseSnippetViewSetTests):
             list(response.context["object_list"]),
             [self.second, self.third],
         )
+
+
+class TestMenuItemRegistration(BaseSnippetViewSetTests):
+    def setUp(self):
+        super().setUp()
+        self.request = get_dummy_request()
+        self.request.user = self.user
+
+    def test_add_to_admin_menu(self):
+        self.model = FullFeaturedSnippet
+        menu_items = admin_menu.render_component(self.request)
+        item = menu_items[-1]
+        self.assertEqual(item.name, "fullfeatured")
+        self.assertEqual(item.label, "Full-Featured MenuItem")
+        self.assertEqual(item.icon_name, "cog")
+        self.assertEqual(item.url, self.get_url("list"))
+
+    def test_add_to_settings_menu(self):
+        self.model = DraftStateModel
+        menu_items = settings_menu.render_component(self.request)
+        item = menu_items[0]
+        self.assertEqual(item.name, "draft-state-models")
+        self.assertEqual(item.label, "Draft State Models")
+        self.assertEqual(item.icon_name, "snippet")
+        self.assertEqual(item.url, self.get_url("list"))

wagtail/test/testapp/wagtail_hooks.py

@@ -256,6 +256,11 @@ class FullFeaturedSnippetViewSet(SnippetViewSet):
     list_display = ["text", "country_code", "get_foo_country_code", UpdatedAtColumn()]
     index_template_name = "tests/fullfeaturedsnippet_index.html"
     ordering = ["text", "-_updated_at", "-pk"]
+    add_to_admin_menu = True
+    menu_label = "Full-Featured MenuItem"  #
+    menu_name = "fullfeatured"
+    # Ensure that the menu item is placed last
+    menu_order = 999999
 
     # TODO: When specific search fields are supported in SQLite FTS (see #10217),
     # specify search_fields or get_search_fields here
@@ -285,6 +290,9 @@ class DraftStateModelViewSet(SnippetViewSet):
     list_filter = ["text", "first_published_at"]
     search_fields = ["text"]
     search_backend_name = None
+    add_to_settings_menu = True
+    # Ensure that the menu item is placed first
+    menu_order = -999999
 
     panels = [
         FieldPanel("text"),