Supercharging Snippets (with revisions, drafts, workflows, etc.)

[laymonage]

Hey folks! 👋

As some of you may have seen in our latest What's New in Wagtail event, we are planning to "supercharge" the snippets feature in Wagtail.

This work is too broad to be an RFC, but we feel that we still need to give you a better idea on how we're going to do it. Thus, this post outlines the high-level overview of the work involved. Please note that we're still figuring things out as we go along, so things may be added, changed, or removed. RFCs will be created for certain implementation details that will be required for this project.

Background

As a CMS, Wagtail has plenty of useful features in its Page editor. However, a content management system manages content, not just pages. A page often consists of smaller bits of information (content) that can be managed individually and reused in other pages or inner mechanisms of the site. Since Wagtail is built on Django, you can use Django models to store such content in your database and use them in your pages. In addition, Wagtail also allows you to manage Django models in the Wagtail admin.

We currently have two ways of editing Django models in the Wagtail Admin, that is through Snippets and ModelAdmin.

Snippets

• Straightforward to use: add the @register_snippet decorator to your models and they will show up under the Snippets menu.
• Simple interface: no filtering on the listing view, can't customise the fields to be shown on the listing, etc.
• Can only be registered in the "Snippets" menu: you can't put them in a custom menu in the sidebar.
• Supports "choosers": if you have a Page or other model that references a Snippet, you can select the snippet using the Choosers dialog.
• Supports translations: you can translate a Snippet instance to other languages from the listing view.

ModelAdmin

• A bit more involved to use: create a subclass of ModelAdmin, define the display, filters, and search fields, then call modeladmin_register().
• Supports per-model customisation on the listing view.
• Can be registered anywhere in the menu, and can be grouped together with submenus.
• Doesn’t support choosers: other models can only select this model using a dropdown menu.
• Doesn't support translations: you can choose the language when creating an instance, but existing instances can't be translated to other languages.
• Most of the code was copy+pasted from Django, so it has custom implementation for filters, search, etc. Wagtail has its own approaches to these (django-filter and wagtail.search) but ModelAdmin is incompatible with Wagtail’s approaches.
• Doesn’t reuse much code out of Wagtail or Django, so there’s a lot of features to maintain.

Having two completely separate implementations like this makes it more difficult for us to implement new features that work with both implementations (for example, wagtail-localize doesn’t support ModelAdmin). It can also be confusing for new users ("which one to use?").

Proposed solution

We want to have a single, "definitive", way to manage Django models in Wagtail Admin. To achieve this, we will start by refactoring and improving Snippets to reuse as much code in Wagtail as possible, by extending from Wagtail's generic admin views. Then, we will bring new features by implementing them in the generic admin views. With this approach, the new features can be used by any Django model and they are not tied to the concept of "Snippets". In the future, we might even stop using the "Snippets" terminology and treat them as regular Django models to reduce the gap when people come from Django to Wagtail.

Stages

We have broken down the work into stages, each of them is described below. Note that these stages aren't set in stone. We may add, change, or remove any of the stages as we continue with the work and find new challenges and rooms for improvements.

Stage "X" means that the stage can be done at any time, it can be pushed out (or pulled in if the prerequisites have been fulfilled), and it does not block the subsequent stages.

Stage 0: Make snippets views extend from generic views ✅

As of Wagtail 3.0, the Snippets views are a mix of class-based views (CBV) and function-based views (FBV). In this stage, we will refactor the views into CBVs and make them extend Wagtail’s generic admin views. This is done in:

• Refactor create snippets view into class-based view #8332
• Refactor Snippets list view to extend from generic IndexView #8335
• Refactor Snippets edit view to extend from generic EditView #8344
• Refactor Snippets delete view to extend from generic DeleteView #8346
• Refactor Snippets usage view to extend from generic IndexView #8351
• Refactor Snippets index view to extend from TemplateView #8352
• Use class-based view for snippet chosen view #8417

Stage 1: Move snippets features into generic views ✅

Once the Snippets views extend from the generic views, we will lift parts of the Snippets views that contain generic features (e.g. locale, search, panels support) to the generic views. Thus, the Snippets views will only contain Snippets-specific customisation without the implementation details for those features. This is done in:

• Extract mixins from Snippet views and use it in generic create/edit/delete views #8361

Stage 2: Wrap Snippet views into a ViewSet ✅

Currently, all registered snippet models must use the same CRUD and chooser views.

In this stage, we will update @register_snippet to instead generate and register a ViewSet for each snippet. This would allow the snippet views to be customised for individual snippet models. This is done in:

• Wrap snippet views in SnippetViewSet #8422

Stage 3: Add revisions to Snippets ✅

In this stage, revisions will be available for Snippets. The History view for Snippets will allow the user to revert back to a previous revision and compare differences between revisions. This is done by refactoring the PageRevision model into a generic Revision model and extracting save_revision() (and other revision-related methods and properties) from Page into a RevisionMixin. Then, we'll update the generic views to call save_revision() every time an instance of a model that extends from RevisionMixin is created or edited. To do this, we'll need to:

• Replace PageRevision with generic Revision model #8441
• Check that Page.save_revision() was given a specific page object #8573
• Use GenericForeignKey and GenericRelation for Revision #8571
• Extract revision-related properties and methods in Page into RevisionMixin #8482
• Save revision in generic and modeladmin views if the model extends from RevisionMixin #8495
• Implement the ability to filter revisions and revert to a previous revision for Snippets  #8509
• Extract generic RevisionsCompareView and add the ability to compare revisions for snippets #8531

Screenshots

Stage 3.1: Implement new Page Editor UI on Snippets ✅

The draft state for Snippets will require some UI rework to the Snippets views to show the published/draft status and the scheduled publishing feature. To do this, we will copy across the new header info (including breadcrumbs, see #8472) and side panels from the new Page Editor so that we can display the status of the Snippet in the same way it’s displayed on Pages. This is done in:

• Add breadcrumbs and new Page Editor side panels to Snippets views #8623

Screenshots

Stage 4: Add Draft state to Snippets ✅

This includes the ability to save a draft of a Snippet and publish it, but not any moderation. We want Snippet draft/publishing/unpublishing to work in a similar fashion to Pages, so that:

• Editors get a consistent experience
• Editors are able to create Snippets and (later) preview them before making them available to be selected from pages/other models

We will create a DraftStateMixin for models. This mixin can only be applied if the RevisionMixin is applied - so that any time you use the DraftStateMixin you must have revisions enabled, but you can still use revisions on their own without having to use drafts. To ensure the DraftStateMixin is never applied without the RevisionMixin, we’ll perform a system check in the DraftStateMixin. This is done in:

• Extract drafts-related fields, methods, and properties from Page to DraftStateMixin #8612

The DraftStateMixin will include a way to show if the model is live (extracted from pages). We will also update the action buttons to add in a Publish button alongside Save, which publishes the Snippet. The basic version is done in:

• Add publishing action to Snippets if the model extends DraftStateMixin #8624

In addition, we still have to figure out what it means for a Snippet to be in a "draft" state. See the discussion in #8599 for more details.

Stage 4.1: Use latest_revision from RevisionMixin to find the draft title and updated date ✅

The Page model has (denormalised) draft_title and latest_revision_created_at fields to optimise the performance of the listing views by avoiding too many table joins on the database. Rather than adding these fields to every snippet, we’d like to add them to the revisions themselves, so we can get it from the latest/first revision instead. So that we know which is the latest revision, we’ll introduce a latest_revision field to the RevisionMixin. After this is done, we should also refactor Page to use this latest_revision field instead of the draft_title and latest_revision_created_at fields.

Stage X: Improve Snippets listing view and filters ✅

We want the listing of Snippets to be customisable, so that more metadata can be shown to help users find the right Snippet.

In order to do this, we will need to update the Snippet listing for all Snippets, regardless of them having the DraftStateMixin applied or not.

Snippets listing differs from page listing as Snippets don’t have a common title field (though they do share some common metadata). The default listing view will show the following columns:

• Name
  For snippets that have the RevisionMixin, the name field will be the latest_revision's title (which is the str() of the instance at the time the latest_revision is created). For basic snippets, this column will be populated by the str() representation of the snippet.
• Updated at
  • For basic snippets this will show the last time the last audit log was created for the snippet (e.g. the last time it was saved by a user)
  • For snippets with the RevisionMixin we will show when the last revision was created.
• Usage
  This will show the number of pages/model instances that reference the snippet. This will need the work outlined in Draft state for snippets and quickly and accurately finding an object's usage #8496.
• Status
  This will show the "Live" and "Draft" status when the DraftStateMixin is applied.

This is done in:

• Extract queryset filtering code from ReportView to generic IndexView #8851
• Add Updated and Status columns to Snippets listing and other improvements  #8890

We will also add ordering and basic filters to the default listing view where they make sense.

Developers will be able to customise the display, order, and filter fields by overriding the ViewSet. We'll probably also add the possibility to register snippets under a different menu using the ViewSet. This will be documented later.

Stage 5: Add Previews to Snippets ✅

In this stage we’ll change Previews so they are managed as a mixin independently of pages. Pages will use the Preview mixin, just as any other model will be able to.

To achieve this we will move these methods and attributes out of Page into a new mixin (e.g. PreviewableMixin) so they can be generally used by other model types. The mixin will be added to the base class of the page, so all pages will still have previews and they still work the same way. This is done in:

• Extract PreviewableMixin from Page model #8709

When the mixin is added to a Snippet, we will display a Preview button (as per pages). To add a preview to a model, the developers will add the mixin to their (snippet) model class, and define a template using a preview_template attribute.

To add multiple preview modes to a model, the developer will override get_preview_template, get_preview_context, and/or serve_preview and provide separate templates for each mode, in the same way they currently do for Pages.

This is implemented in:

• Add preview support for Snippets that extend PreviewableMixin #8808

We will need to update developer docs to show how this works, and some advice on how to use previews with non page models (e.g. Snippets).

---

Everything below this line is unlikely to make it into Wagtail 4.0, and instead will be part of the subsequent release(s).

---

Stage X: Snippet usage ✅

In order to unpublish and delete a Snippet, that Snippet should not be used anywhere on the site. To do this we will need to introduce a listing of where the Snippet is being used, which will mean creating a new usage index.

We can discuss the technical details for this in:

• Draft state for snippets and quickly and accurately finding an object's usage #8496

Stage 6: Introduce workflows for Snippets ✅

• While not necessarily required for workflows, we've also implemented locking for snippets in Lock snippets when scheduled for publishing if LockableMixin is applied #9735 and Add the ability to lock snippets that extend LockableMixin #9763.
• See Workflows for snippets: implementation reference #9955.

Next steps

ModelAdmin parity

This involves making the SnippetViewSet easier to configure, to act as the replacement of the ModelAdmin classes.

• Custom icon per snippet model
  • Existing issue/PR:
    • Add the ability to define custom icons for Pages #9652
    • User-defined Snippet Icons #9653
    • Custom snippet icons #9804
  • Need to ensure this is used across all views for the model
• Easier menu items organisation (register outside "Snippets")
• Easier filters setup on listing view
• Other ModelAdmin capabilities?

For further discussion, head over to:

• Snippets vs ModelAdmin parity #10206

Tech debt

• Unify code for header, side panels, action menu items, and other templates
  • If possible, pages views as well, to use the generic views
• Rethink permission handling to make it work for both pages and snippets, or at least have a similar interface so that it's easier to unify the above things.
• Refactor page create/edit views to extend from generic views and CreateEditOptionalFeaturesMixin
  • We've extracted this mixin in Extract revision and draft state logic from generic views into mixins #9709. Now that the mixin also contains code to handle workflows, we could reduce a lot of code duplicity by making use of the mixin in the page create/edit views.

Miscellaneous

• Show warning when unpublishing snippets and pages that are used by other objects
  • Make use of the recently introduced reference index
  • Show warning when selecting draft snippets/pages?
• Consider multiple registration of SnippetViewSets
  • I think I saw some people saying that they'd like to be able to register different views (mostly different listing views) for the same Django model.
  • This is currently not possible, as a Django model can only have a single registered SnippetViewSet. This is necessary as we need a single "canonical" viewset for linking stuff between features (e.g. link to the edit view from the dashboard of snippets that are in a workflow).
  • Might be able to use ModelViewSet instead?
  • If they just need to add a few custom views, it's possible to just subclass the default SnippetViewSet and override get_urlpatterns()... I suppose there should be an easier way to register the urls to the sidebar menu, though.

---

Out of scope for now

• Commenting
• Live URLs for snippets (need to think about how this works with sites and cached_paths)
• Aliases (Snippets don’t have tree structure so these are not needed)
• Copying (need to provide a generic way to copy revisions from one object to another)

---

Thanks for reading, please let us know what you think about this!

Also check out previous/related discussions on specific parts of this project:

• Improving Snippets functionality to allow professional work #8403
• Add breadcrumb menu to snippet pages #8472
• Draft Snippets functionality #8599
• Draft state for snippets and quickly and accurately finding an object's usage #8496
• Workflows for snippets: implementation reference #9955

Last updated: 2023-01-24 16:40 GMT

[lb-]

Might be worth flagging Snippets bulk actions are well underway also #8574

[lb-]

@laymonage a bit nitpicky but maybe we should rename DraftStateMixin to PublishMixin or PublishableMixin?

[kaedroho]

@lb- I think DraftStateMixin makes sense here because it adds the ability to save a draft version of the object. Without it, the user can only publish.

[lb-]

no problems - happy to go with what we have

[ababic]

@laymonage Personally, I think your suggestion of RevisableMixin sounds most appropriate. DraftStateMixin certainly makes sense too, but RevisableMixin is a better description of the functionality that is added. Revisions offer way more than just 'draft state' - they offer 'complete history' of objects.

[laymonage]

Hi @ababic, thanks! However, we've actually separated the behavior into two different mixins: RevisionMixin and DraftStateMixin.

• The RevisionMixin offers "complete history" of objects, but they are always considered "live". This adds the save_revision(), with_content_json(), and some other methods.
• Meanwhile, the DraftStateMixin introduces the live (and other related fields), which allows objects to have a "draft" (i.e. unpublished) state, and allows them to have "Publish" actions.
• The DraftStateMixin requires the RevisionMixin to be applied because unpublished changes are stored as revisions, but the RevisionMixin can be used without the DraftStateMixin applied.

With that in mind, the suggested RevisableMixin name doesn't seem to fit as a replacement to DraftStateMixin. We can rename RevisionMixin into RevisableMixin, but I'm not sure it's worth the effort for such a small change. We still haven't written the docs though, so feel free to suggest any name changes as long as they make sense with the current implementation of the mixins on main. Preferably sooner though, as we need to start writing the docs soon! 😄

[ababic]

Well clarified, thanks @laymonage. I admit I was "reacting to reactions" here rather than looking at the code 😀

[thibaudcolas]

I have multiple questions on this work from a maintenance standpoint:

• What’s the future of ModelAdmin? It’s not clear from the discussion so far whether we intend to keep supporting it or not. If it keeps being supported, is it strictly for backwards compatibility or would there be use cases better served by it?
• How are we intending to document which of ModelAdmin vs Snippets people should use? This feels like a crucial point to me so we guide them towards the option that’s most likely to work longer-term
• What’s the plan to add some or all of the above features to the bakerydemo site? Snippets (and ModelAdmin) usage there is relatively basic, for example lacking translations. I have a feeling those new features will make snippets harder to maintain if we don’t have a straightforward way to test them.

[laymonage]

Hey Thibaud, I agree it's not clear yet on what we'll do with ModelAdmin. Here are my personal thoughts so far:

• I think ideally we would want to eventually remove ModelAdmin from Wagtail's codebase, and maybe publish it as a separate package that will be maintained for a short term while people migrate to Snippets.
  However, working on this so far I've found that the current SnippetsViewSet implementation on main is still very lacking to be a ModelAdmin replacement. It feels very low-level and the boilerplate needed when we want to add filters is a bit more involved than ModelAdmin. This doesn't mean that SnippetsViewSet can never replace ModelAdmin, though. It just means that we have to design an API that's more high-level for people to customise it.
• Once we have the above API implemented, I feel like we can incorporate some of ModelAdmin's intro docs to the Snippets docs (in terms of introducing a way to edit your Django models in the admin). Then, maybe mention ModelAdmin as an alternative? Right now Snippets docs are more easily accessible (in the Usage guide) compared to ModelAdmin (buried in Reference > contrib). We can document an intro to Snippets in the current docs, and add a new section in Reference that details the API for Snippets, similar to the docs for pages.
• I have made some dirty updates on my local bakerydemo copy to test the recent work on Snippets. Would love to make a proper PR, but right now one small thing irks me a bit: the codebase isn't autoformatted with black yet. I should probably make a PR for that as well...

[lb-]

I have strong opinions about the preservation of ModelAdmin - but I also understand the need to simplify the maintenance of Wagtail code.

ModelAdmin is built in a very different way to lots of other code in Wagtail and it is hard to support UI updates and improvements in its current state.

However, it is also an incredibly powerful tool that is really flexible and can help manage things that really do not make sense as snippets (e.g. Pages, or even things like form responses or in theory models that are not even in Django models).

My concern is that with the potential of ModelAdmin being made an external package, Wagtail may not get that flexibility out of the box any more and ModelAdmin will stagnate even more.

Maybe there is a future where ModelAdmin can come out of contrib and be a layer on top of the viewsets approach that is part of core.

[kaedroho]

I don't think we should plan to remove ModelAdmin until we've implemented a replacement for it.

A big part of the work here is moving a lot of snippet and page features into the generic views and viewsets. Next, I think we should create a new ModelAdmin-like API on top of the views/viewsets.

The new-ModelAdmin and snippets would share code, and be functionally equivalent but would differ on how they are added to menus and ModelAdmin won't use the word "Snippet" anywhere. I think this will be a good replacement for the current contrib module for making any Django model editable in Wagtail.

There are a couple of other features of ModelAdmin that wouldn't be covered by the generic views / viewsets:

• Adding a custom listing view for pages - I think we should suggest people use reports for this instead
• InspectView - We could replace this by introducing a "view only" permission for pages/snippets, which allows someone to open a page/snippet without edit permission but the fields will be locked

With those features covered, I don't think there would be anything else that ModelAdmin currently does that wouldn't be covered by something in core (let me know if you think I've missed something).

I think we should keep it around for backwards compatibility, but maintain it as a separate package to not confuse new users.

[thibaudcolas]

We discussed this briefly in today’s core team meeting and there was general consensus (among a small group) that we’d want to recommend other features than ModelAdmin (Snippets, Reports, generic choosers) at some point. Consider moving ModelAdmin from a contrib module to a separate package at some other point. And only share a defined timeline once the recent work on the aforementioned features is shipping, so as not to cause confusion.

@laymonage I’d be interested in seeing a "features comparison table" that compares ModelAdmin, Snippets, Reports – with rows for each feature, and columns for each of ModelAdmin / Snippets / Reports. Potentially with links to issues / docs in each cell so we know where the feature is at. Here’s an example. Is this something you think would be worthwhile to produce, either for addition in the Wagtail docs, or as a working document outside the docs?

[Scotchester]

Agree that such a comparison table would be very helpful.

[ababic]

Just wanted to say how wonderful it is to see some movement toward consistency here. I feel like this whole thing has been approached really sensibly. Wonderful work guys!

One thing I feel might have been missed though: modeladmin makes sense for a Django-based CMS. It offers developers a clear option to replicate what they might already have in raw Django or another Django-based CMS. It started life at Rock Kitchen Harris as a 'migration pack' to help us bring existing Django, Django-CMS and Mezzanine projects into Wagtail. Please don't make the mistake of thinking everybody comes directly to Wagtail without experience of Django or other Django-based products - It may appear more common these days, but keep in mind: you will naturally hear more noise from those developers, because they are having to grasp so much more at once.

Believe me when I say: experienced Django devs are still 'converting' to Wagtail and taking care of business without support. They just want a clear migration path - and when you give them that, they'll thank you for it. modeladmin was the product of a few key questions that bubbled up in our minds when we were looking at ways to "do Django sites better" (in priority order):

1. How do we get the editors to where they need to be? The events team just went directly to a listing before... They really aren't interested in navigating the explorer for three levels to get to the event pages. They don't care about the page trees, or the difference between pages and other models - that's a developer concern! (Modeladmin was built originally for PAGE MODELS only! The would-be-snippet-model management actually came later. It's way more than a snippet replacement - please don't overlook this)
2. What the jeggins is a 'snippet'? Code snippets? Clients seem to understand what a 'model' is, but is 'Snippets' where they'll look to update 'Coffee regions' or 'Children's book award categories'? (Show model names directly in the menu to bypass the need for editors to know the difference between pages and non-pages, and pair with icons to improve recognisability)
3. A 'register decorator' is all well and good, but what do I do when the model is out of my control (e.g. from a third-party app)? (a familiar Django-like registration mechanism in any wagtail_hooks.py file)
4. All our apps have their own page, taxonomy and other misc models... How do we group these 'related things' together in the nav to reduce mental load for editors, like Django does for us? (ModelAdminGroup!)

If Wagtail has clear answers to these questions, there's no need for modeladmin to exist, and I'll be happy to see the back of it. I'm not sure we have all the answers yet, though.

[lb-]

One other thing that ModelAdmin does really well is provide the ability to administer the same model in different ways, so you could provide multiple ways to manage Page models based on almost any kind of criteria.

Additionally, you can do this for any model, so you could have two ModelAdmins that apply to the same model (e.g. SalesItem), the first may just be a simple listing for some users with a high level set of columns. The second could be for another group of users with different permissions that focuses on digging into detail with more columns, editing access and linked models.

While I am sure this can be built with register_snippet - the current architecture will need a rethink as the relevant snippet utils are added to the Model itself and it will only be set up once per model.

[thibaudcolas]

Are customisable snippet icons on the menu as well? (#4095, #4040). This feels like a worthwhile consideration to me as part of architectural changes, as icons are yet another bit of metadata which would ideally only be defined once per model and then propagated to the menu items, listing views, chooser widgets, etc.

[dkirkham]

I somehow missed these issues and have written up my own feature request and draft PR in #9652 and #9653.

[dashmug]

Are stages 1 to 4 gonna make it to Wagtail 4? I'm trying out the 4.0rc2 but I don't see any of these features for Snippets?

[gasman]

Previewing, revision history and draft state are in - see https://docs.wagtail.org/en/latest/topics/snippets.html#making-snippets-previewable.

[dashmug]

Nice. We'll try it out. Thank you @gasman.

[NotANormalNerd]

We are currently looking into using non-page models more in our Wagtail, which brings me here. I would have some feedback on this discussion as well:

1. What has already happened in Wagtail 4 with snippets is amazing work. 🫶🏻 Thank you for that.
2. One functionality that is missing for us right now to fully commit to snippets is order ability in the UI. We have some snippets that are called/selected by their order (think ads or banners)
3. With the whole discussion going on about ModelAdmin I am a bit confused, if we should use snippets or if we should use ModelAdmin. I tried reading the documentation but there is no clear: This is the main difference between ModelAdmin and Snippets. Are snippets an opinionated approach to non Page models? Are they treated differently? Can we use the new mixins for Snippets on ModelAdminModels as well or do we have to implement that ourselves? What can I do with ModelAdmins that I can't do with Snippets?

Maybe Snippets should be a "variant" of ModelAdmins, meaning being based on them and offering a quick and easy way to setup a opinionated ModelAdmin, but leaving the ModelAdmin escape hatch for a more low level approach. Basically having @register_snippet auto-create a ModelAdmin class (think ModelAdminFactory, like ModelFormFactory).

I would really appreciate if somebody could help me understand the difference here.

Best regards,
Dennis

[laymonage]

Hi, thanks for the feedback!

One functionality that is missing for us right now to fully commit to snippets is order ability in the UI. We have some snippets that are called/selected by their order (think ads or banners)

Do you mean custom, drag-and-drop ordering on the listing view, like on the page explorer? If so, that's not in our plans yet, but that sounds like a good idea. However, if you just want to order the listing based on a specific DB column, that would be possible in #9147. Right now, there's limited ordering support by defining the ordering in your model's Meta class.

With the whole discussion going on about ModelAdmin I am a bit confused, if we should use snippets or if we should use ModelAdmin. I tried reading the documentation but there is no clear: This is the main difference between ModelAdmin and Snippets. Are snippets an opinionated approach to non Page models? Are they treated differently? Can we use the new mixins for Snippets on ModelAdminModels as well or do we have to implement that ourselves? What can I do with ModelAdmins that I can't do with Snippets?

Sorry we haven't been very clear on this! Right now the new features for snippets are intended only to be used on the snippets admin. For example, the preview panel for PreviewableMixin isn't available in the ModelAdmin edit view. Publishing/unpublishing also aren't available in the ModelAdmin edit view (though if I remember correctly, the revisions will still be saved). This is because the view code needs to handle the logic for those mixins and we had to pick one place (between ModelAdmin and snippets) to put this in -- we went with snippets.

By the way, the two are not mutually exclusive, you can use @register_snippet and ModelAdmin on the same model.

Maybe Snippets should be a "variant" of ModelAdmins, meaning being based on them and offering a quick and easy way to setup a opinionated ModelAdmin, but leaving the ModelAdmin escape hatch for a more low level approach. Basically having @register_snippet auto-create a ModelAdmin class (think ModelAdminFactory, like ModelFormFactory).

I imagine this is our long-term goal, and we're already halfway (?) through this. However, instead of ModelAdmin classes, we're automatically generating SnippetViewSet instances. We aim this SnippetViewSet to be the way for customising your snippet views. Here's how you'd use it:

• Define a subclass of SnippetViewSet (I probably should've put this example in views.py instead of wagtail_hooks.py)
  

  wagtail/wagtail/test/testapp/wagtail_hooks.py

  Lines 229 to 237 in 895ebc5

  	class FilterableSnippetViewSet(SnippetViewSet):
  	list_display = ["text", "country_code", "get_foo_country_code", UpdatedAtColumn()]
  	@property
  	def index_view_class(self):
  	class FilterableSnippetList(SnippetListView):
  	filterset_class = FilterableSnippetFilterSet
  	return FilterableSnippetList

• Point to the viewset in your model definition using admin_viewset (we'd probably want a nicer way to do this, e.g. actually use a hook)
  

  wagtail/wagtail/test/snippets/models.py

  Lines 66 to 68 in 895ebc5

  	@register_snippet
  	class FilterableSnippet(index.Indexed, models.Model):
  	admin_viewset = "wagtail.test.testapp.wagtail_hooks.FilterableSnippetViewSet"

The above feature has yet to be documented though, as we feel it still needs more thinking!

[thibaudcolas]

Thought I’d get back to this discussion to ask whether there has been any discussions of snippets’ support in rich text?

This strikes me as a natural fit for this project, as it currently takes a lot of work to implement any kind of "inline text with associated data". A generic snippet-focused API would be an excellent way to make this possible with higher-level, "server-side only no need to touch JS" APIs. And I don’t think it would necessarily be that much work, since we already have choosers for snippets – we’d just need to know which field(s) of the snippet to store in the rich text (id or otherwise) so the annotation is associated with the correct model instance, and which field(s) to use when displaying any kind of preview / "thumbnail"-type information which we might want to have access to outside the chooser (for example in the rich text tooltip).

[kaedroho]

I think we should move away from blocks in rich text in general, and use streamfield blocks to embed block elements like images, embeds, and snippets within the content of a page.

This would remove the need to have to deal with two different representations for each type, but also could make it easier for headless sites to handle and customise rich text on the frontend.

[thibaudcolas]

Yes, no reason not to use StreamField for those. What I’m interested in is support for inline text annotations, which StreamField isn’t suited for. For example here is a screenshot of Google Docs’ "People" and "Place" smart chips:

[dopry]

I like where snippets are headed. Our team wanted workflow and revisioning for our re-usable content, so we setup a 'Reference' site with pages for all of our re-usable content. We considered snippets but they didn't meet our editorial needs. More full featured snippets might have changed our decision. Will there be advantages to using snippets in the future vs our approach of creating out of tree pages? It sounds like snippets, once all these features are added, will be fairly indistinguishable from pages.

[laymonage]

Hi everyone, thanks for showing your interest in this discussion!

Sorry I haven't been able to reply and answer your questions. In the past few months, we've been hard at work making workflows and locking available for snippets. The feature has been merged and will be included in Wagtail 4.2. For more details, see:

• Workflows for snippets: implementation reference #9955
• Publishing workflows for snippets #9817

Now that we've covered all the big features, I think the next thing we should focus on is to fill in the gaps: polishing the UX, clearing up tech debts, making snippets up to par with ModelAdmin, etc., then finally deprecating ModelAdmin.

ModelAdmin parity

This involves making the SnippetViewSet easier to configure, to act as the replacement of the ModelAdmin classes.

• Custom icon per snippet model
  • Existing issue/PR:
    • Add the ability to define custom icons for Pages #9652
    • User-defined Snippet Icons #9653
    • Custom snippet icons #9804
  • Need to ensure this is used across all views for the model
• Easier menu items organisation (register outside "Snippets")
• Easier filters setup on listing view
• Other ModelAdmin capabilities?

Tech debt

• Unify code for header, side panels, action menu items, and other templates
  • If possible, pages views as well, to use the generic views
• Rethink permission handling to make it work for both pages and snippets, or at least have a similar interface so that it's easier to unify the above things.

Miscellaneous

• Show warning when unpublishing snippets and pages that are used by other objects
  • Make use of the recently introduced reference index
  • Show warning when selecting draft snippets/pages?
• Consider multiple registration of SnippetViewSets
  • I think I saw some people saying that they'd like to be able to register different views (mostly different listing views) for the same Django model.
  • This is currently not possible, as a Django model can only have a single registered SnippetViewSet. This is necessary as we need a single "canonical" viewset for linking stuff between features (e.g. link to the edit view from the dashboard of snippets that are in a workflow).
  • Might be able to use ModelViewSet instead?
  • If they just need to add a few custom views, it's possible to just subclass the default SnippetViewSet and override get_urlpatterns()... I suppose there should be an easier way to register the urls to the sidebar menu, though.
• "Copy" feature, like pages?

Edit: I've updated the main post to reflect the current status and include this update.

[lb-]

FormPage listing & form responses as snippets

I'd like to suggest that snippets be used under the hood to power the form responses (and maybe even form page listing) interaction.

This would be a good use case for ensuring that Snippets and ViewSets can support many of the features the ModelAdmin can already support. It will also massively enhance the capabilities of form and form response management.

I'm not sure if reports are a better way to integrate form submission listings though.

Just an idea.

[lb-]

Settings as Snippets / Singleton Snippets

I would like to suggest that we explore the concept of a singleton (single instance) Snippet, one that is never shown as a listing but only ever has one 'truth' instance.

If we had this, we could potentially implement it for the underlying approach of Setting models maybe.

[enzedonline]

This really needs to be single instance per locale to allow translation on multi-lingual sites. It's the biggest pain with settings just now and ends up with me using snippets as settings to get translation capability.

[laymonage]

Some thoughts on icons, views, and menu customisations: #4095 (comment)

[ababic]

@laymonage how do you feel about rebuilding modeladmin as a part of the core app, where it essentially becomes a 'convenient customisation layer' on top of the snippet views?

[laymonage]

Hi @ababic, thanks! I raised a somewhat similar idea on the core team meeting last week. Here's a summary of what I said:

I noticed that when using modeladmin with Pages, only the listing view is actually used, and the rest will redirect to the page views. I'm wondering whether this is something that we should do instead of fully removing model admin (or, at least before we actually remove it). Eventually, modeladmin is just another mechanism to make listing views, not a fully-equipped set of views. For editing, you still need to register them as snippets.

Am I right to think that the biggest value of modeladmin is the listing view and the menu registration mechanisms, and not so much the CUD views?

But anyway, the general consensus was that if we can make the snippets customisation as convenient as modeladmin (but uses Wagtail's approach to filter using django-filter and search with the search backends), and provide a clear path and reasonable timeline for migrating from modeladmin to snippets, there's not much value in keeping/reworking modeladmin.

[ababic]

Am I right to think that the biggest value of modeladmin is the listing view and the menu registration mechanisms, and not so much the CUD views?

Yes, the intention was always just to provide the easy configuration options and utilise existing view logic - there was just no way to 'plug in' to most of it, because all of the views were function-based until very recently.

[ababic]

But anyway, the general consensus was that if we can make the snippets customisation as convenient as modeladmin (but uses Wagtail's approach to filter using django-filter and search with the search backends), and provide a clear path and reasonable timeline for migrating from modeladmin to snippets, there's not much value in keeping/reworking modeladmin.

Realistically, there's no reason why a new version of modeladmin (or the snippet views themselves) shouldn't be able to convert a list of field name strings into a basic set of django-filter filters, deriving things from what we know about the model/field configuration. I don't think the main listing views even support any kind of filtering though, do they?

[ababic]

If I had to be really really derivative about the value of modeladmin that I still feel is missing with Snippets, I would say:

1. The term 'snippet' just doesn't feel like a good fit for a lot of things, and modeladmin provides a way around that. Think: models from third-party apps, or models managed from the front-end that are registered more just for visibility/auditability, or to allow for choosing.
2. The barrier-to-entry in getting a decent amount of control over the representation of model data is really really low. But, if you want to do something off-the-wall, you can get your hands dirty.

On 1: Maybe control over the menu item position caters for this to a degree, but I think developers would still be cautious about referring to their models as 'Snippets' in code. Perhaps 'generisizing' the naming of base classes / underlying components further might help here?

On 2: Whatever the final shape of things, it would be good to start thinking about developer-facing interfaces for easily customising the listing / filter / menu item options. These are things that modeladmin does quite well, and that I think developers would miss the most. Most of the bits and pieces are there - it's just really about wrapping it all up.

[laymonage]

Thanks @ababic, some good points there! I've created a separate discussion to discuss about snippets vs ModelAdmin parity here:

• Snippets vs ModelAdmin parity #10206

[lb-]

Preview / inspect snippets view

As noted above, ModelAdmin has a great feature called inspect, basically a read only view for a model instance.

I think porting this to Snippets would be expected, but maybe a different approach (or parallel feature) could be a standalone preview view.

There already is the ability to Preview snippets and maybe this could be adapted to a single view and available to users without edit access to the snippets.

[ababic]

I love the idea of using 'preview' functionality here where available.

One thing I dislike about the current inspect view is that it's very much its own thing. I'm sure there must be 'less custom' ways to generate read-only representations of model instances?!

The permission side of things is also a little odd. If starting afresh, we should probably make better use of Django's new(ish) 'view' permission for models.

[th3hamm0r]

I wasn't sure where to put this question, since the parity-discussion #10206 is locked, so I hope it's ok here:

@laymonage Are there any plans to actually get rid of the "Snippets" term and/or this extra level (e.g. in the URL, breadcrumbs,...)?

We've actually never used snippets before, we've only used the ModelAdmin, since this extra level of "Snippets" (and the term itself) created much confusion in the beginning ("Everything is basically a model, why are pages, images, documents, forms,... in the root or in custom submenus, and some other models below 'Snippets'"?).

Since this has been improved a lot by your amazing work, we are now trying to migrate everything (new) to the ModelViewSets, but mostly to SnippetViewSets, to get all the features (e.g. panels/edit_handlers, bulk actions).

But even with add_to_admin_menu = True it does not feel the same as with the ModelAdmin. On the first view, e.g. if you look at the bakerydemo, the navigation looks good. But if you're at the index view of one of the models, beside the "snippets"-path, you have the "Snippets"-breadcrumb item, and the title bar shows "Snippets [Modelname]", which is all a bit confusing.

Currently, we use the following tweaks for our SnippetViewSets to get this experience without "Snippets" (and a bit more parity with ModelAdmin 😉 ):

• remove the Snippet-breadcrumb-item (by overriding breadcrumbs_items)
• remove "snippets" from the url (by overriding get_admin_base_path())
• override wagtailsnippets/snippets/index.html to get rid of "Snippets" in the titletag-block (by setting a custom index_template_name)
• allow a user only with "view"-permission to open the IndexView
  This is more a ModelAdmin-parity-thing, which I assume just hasn't been tackled yet.
  If a user can only view an object, he should still be able to open the index view.
  • override menu_item_class to also take the "view"-permission into consideration
  • add "view" to the IndexViews any_permission_required
  • We've also adapted the TitleColumn to fallback to the inspect-url or None, if the user cannot edit the object (by overriding IndexView._get_title_column()).
  • add "view" to the InspectViews any_permission_required (optional, if inspect_view_enabled = True)

So I'm thinking of making the snippet-less configuration the default, but still allow to switch to the old setup (for a deprecation period vs. just keep the option).
Another option would be to move most of the snippets-logic into the ModelViewSet, and only keep the Snippets to get this extra level of hierarchy.

[th3hamm0r]

Fyi: I've somehow missed the discussion #10740 and the linked slack discussion about the term "Snippet" entirely 😅
The detailed implementation plan seems to fix all those problems in the future. So in the meantime we will use the above tweaks to basically get snippets without showing "Snippets" to the end user 😉