Clarify that the insert_editor_js hook covers all core model editing/creation views #13021

We currently document that the insert_editor_js hook can be used to ...

Add additional JavaScript files or code snippets to the page editor.

However, this hook is output in all core editing & creation views, even for non-page models and has been for many releases.

Pertinent section of the Wagtail docs

https://docs.wagtail.org/en/stable/reference/hooks.html#insert-editor-js

Now that #2936 has been completed, we have a decision to make about whether we fully align with the insert_editor_js hook as documented OR re-document it to align with what the code actually has been doing for many years now.

Details (recommended changes)

1. Update wording for the hook to advise

Add additional JavaScript files or code snippets to editing and creation views for all code models. This includes page, snippets, modelviewset and the styleguide.

2. Add a new sentence about providing more information about client-side customizations and a link to https://docs.wagtail.org/en/stable/extending/extending_client_side.html .
3. Add the same sentence to the insert_global_admin_js hook, so that there are consistent cross-references to the full guide for custom client-side behaviour.
4. Update the styleguide docs to call out that the insert_editor_js hook is used.

Usage assessment

It's a bit of a mixed bag, but we can reliably communicate that Pages, Snippets, Modelviewsets all support the usage of the hook via the generic/form include.

• wagtail/admin/templates/wagtailadmin/generic/form.html
  • Account editing
  • Generic create
  • Generic edit
  • Chooser parent
  • Page create
  • Page edit
  • Wagtail search promotions add
  • Documents add
  • Images add
  • Users create
• wagtail/admin/templates/wagtailadmin/pages/copy.html
• wagtail/contrib/styleguide/templates/wagtailstyleguide/base.html

Alternative options

A. Revert insert_editor_js to be pages only via a deprecation

• We start a process to formally deprecate any usage of the insert_editor_js hook outside of page editing/creation views. While it's documented as page only, it's extremely likely this is used widely in the ecosystem.

OR

B. Do nothing

• Do nothing, we are meeting the documented spec, it just happens that the hook gets used in other places and maybe that's fine.

OR

C. Fully deprecate insert_editor_js for all usage

• We start the deprecation process for usage of the insert_editor_js hook completely. In which case, we would probably convert this to an issue.
• This has been discussed previously (core team) in late 2024 and the direction at the time was to NOT do this unless we had a really solid path towards ES modules & alignment with the Django community on better form.media capabilities.
• DEP 84: Rejuvenate form media django/deps#84 has mostly stalled / been closed. However, there is a new one on the way DEP0022 -- Adding import maps to Django django/deps#101
• Django 5.2 does bring in some nice improvements to better support script elements with attributes, however, our support within Wagtail will take a while until this is the lowest supported version. https://docs.djangoproject.com/en/5.2/releases/5.2/#forms

The new asset object Script is available for adding custom HTML-attributes to JavaScript in form media. See paths as objects for more details.

Additional context

Originally posted by @lb- in #2936

However, the bulk of this issue has now need completed in #12882

The _editor_js.html template file is now deprecated and can be removed in a future release. The insert_editor_js hook however will still be used in non-page editing views.

My recommendation is that we just keep this as is, and document it as supported this way. We'd likely need to have a deprecation process if we wanted to reduce the usage of that hook to page views only.

For now though, we have removed all core admin scripts from the template tag and no longer have this tightly coupled to the usage of the editor js hook for customisations.

Note that the hook is used by some of our modules, but this is also being reduced through the Stimulus migration plan.

Working on this

• For now, I will raise a PR with the proposed option, we can discuss in the core team meetings if needed.
• View our contributing guidelines, add a comment to the issue once you’re ready to start.