Adopt data attribute usage of SwapController (w-swap) for all header searches

- Removes six inline scripts completely, no longer relying on window.headerSearch
- Update the fallback Stimulus Swap controller afterLoad to be a deprecated method
- Add upgrade considerations
- Fix regression from d554cbe3103028094e095b4512323ca2967aca4a where manually submitting page search results would load the partial, not full page response
- Closes #9950

client/src/controllers/SwapController.ts

@@ -11,7 +11,7 @@ declare global {
 /**
  * Support legacy window global approach until header search
  * can fully adopt data-attributes.
- *
+ * @deprecated RemovedInWagtail60
  */
 const getGlobalHeaderSearchOptions = (): {
   targetOutput?: string;
@@ -95,7 +95,7 @@ export class SwapController extends Controller<
    * Ensure we have backwards compatibility with setting window.headerSearch
    * and allowing for elements without a controller attached to be set up.
    *
-   * Will be removed in a future release.
+   * @deprecated RemovedInWagtail60
    */
   static afterLoad(identifier: string) {
     domReady().then(() => {

docs/reference/viewsets.md

@@ -1,3 +1,5 @@
+(viewsets_reference)=
+
 # Viewsets
 
 Viewsets are Wagtail's mechanism for defining a group of related admin views with shared properties, as a single unit. See [Generic views](../extending/generic_views).

docs/releases/5.1.md

@@ -405,3 +405,79 @@ There are probably three places in your code, which have to be changed:
 1. Creation: Instead of using `strftime("%d %b %Y %H:%M")`, you can now store the datetime directly in the "data" field. We've implemented a new helper `wagtail.utils.timestamps.ensure_utc()`, which ensures the correct timezone (UTC).
 2. Display: To display the timestamp in the user's timezone and format with a `LogFormatter`, we've created utils to parse (`wagtail.utils.timestamps.parse_datetime_localized()`) and render (`wagtail.utils.timestamps.render_timestamp()`) those timestamps. Look at the existing formatters [here](https://github.com/wagtail/wagtail/blob/main/wagtail/wagtail_hooks.py).
 3. Migration: You can use the code of the above migration ([source](https://github.com/wagtail/wagtail/blob/main/wagtail/migrations/0088_fix_log_entry_json_timestamps.py)) as a guideline to migrate your existing timestamps in the database.
+
+### Header searching now relies on data attributes
+
+Previously the header search relied on inline scripts and a `window.headerSearch` global to activate the behaviour. This has now changed to a data attributes approach and the window global usage will be removed in a future major release.
+
+If you are using the documented Wagtail [viewsets](viewsets_reference), Snippets or `ModelAdmin` approaches to building custom admin views, there should be no change required.
+
+If you are using the shared header template include for a custom search integration, here's how to adopt the new approach.
+
+#### Header include before
+
+```html+django
+{% extends "wagtailadmin/base.html" %}
+{% load wagtailadmin_tags %}
+{% block extra_js %}
+    {{ block.super }}
+    <script>
+        window.headerSearch = {
+            url: "{% url 'myapp:search_results' %}",
+            termInput: '#id_q',
+            targetOutput: '#my-results',
+        };
+    </script>
+{% endblock %}
+{% block content %}
+    {% include "wagtailadmin/shared/header.html" with title="my title" search_url="myapp:index" %}
+    ... other content
+{% endblock %}
+```
+
+#### Header include after
+
+Note: No need for `extra_js` usage at all.
+
+```html+django
+{% extends "wagtailadmin/base.html" %}
+{% load wagtailadmin_tags %}
+{% block content %}
+    {% url 'myapp:search_results' as search_results_url %}
+    {% include "wagtailadmin/shared/header.html" with title="my title" search_url="myapp:index" search_results_url=search_results_url search_target="#my-results" %}
+    ... other content
+{% endblock %}
+```
+
+Alternatively, if you have customisations that manually declare or override `window.headerSearch`, here's how to adopt the new approach.
+
+#### Manual usage before
+
+```html
+<script>
+    window.headerSearch = {
+        url: '{{ my_async_results_url }}',
+        termInput: '#id_q',
+        targetOutput: '#some-results',
+    };
+</script>
+<form role="search">
+    <input type="text" name="q" id="id_q" />
+</form>
+<div id="some-results"></div>
+```
+
+#### Manual usage after
+
+```html
+<form
+    role="search"
+    data-controller="w-swap"
+    data-action="change->w-swap#searchLazy input->w-swap#searchLazy"
+    data-w-swap-src-value="{{ my_async_results_url }}"
+    data-w-swap-target-value="#some-results"
+>
+    <input type="text" name="q" data-w-swap-target="input" id="id_q" data-w-swap-target="input" />
+</form>
+<div id="some-results"></div>
+```

wagtail/admin/forms/search.py

@@ -7,7 +7,10 @@ class SearchForm(forms.Form):
     def __init__(self, *args, **kwargs):
         placeholder = kwargs.pop("placeholder", _("Search"))
         super().__init__(*args, **kwargs)
-        self.fields["q"].widget.attrs = {"placeholder": placeholder}
+        self.fields["q"].widget.attrs = {
+            "placeholder": placeholder,
+            "data-w-swap-target": "input",
+        }
 
     q = forms.CharField(
         label=gettext_lazy("Search term"),

wagtail/admin/templates/wagtailadmin/chooser/browse.html

@@ -5,7 +5,7 @@
     {% trans "Choose a page" as choose_str %}
 {% endif %}
 
-{% include "wagtailadmin/shared/header.html" with title=choose_str subtitle=page_type_names|join:", " search_url="wagtailadmin_choose_page_search" query_parameters="page_type="|add:page_type_string icon="doc-empty-inverse" %}
+{% include "wagtailadmin/shared/header.html" with title=choose_str subtitle=page_type_names|join:", " search_url="wagtailadmin_choose_page_search" query_parameters="page_type="|add:page_type_string icon="doc-empty-inverse" search_disable_async=True %}
 
 <div class="nice-padding">
     {% include 'wagtailadmin/chooser/_link_types.html' with current='internal' %}

wagtail/admin/templates/wagtailadmin/generic/index.html

@@ -2,19 +2,5 @@
 {% load i18n %}
 
 {% block header %}
-    {% include "wagtailadmin/shared/header.html" with title=page_title subtitle=page_subtitle action_url=header_action_url action_text=header_action_label search_url=search_url search_form=search_form icon=header_icon only %}
-{% endblock %}
-
-{% block extra_js %}
-    {{ block.super }}
-
-    {% if search_form %}
-        <script>
-            window.headerSearch = {
-                url: "{{ index_results_url }}",
-                termInput: "#id_q",
-                targetOutput: "#listing-results"
-            }
-        </script>
-    {% endif %}
+    {% include "wagtailadmin/shared/header.html" with title=page_title subtitle=page_subtitle action_url=header_action_url action_text=header_action_label icon=header_icon search_url=search_url search_form=search_form search_results_url=index_results_url only %}
 {% endblock %}

wagtail/admin/templates/wagtailadmin/pages/search.html

@@ -3,14 +3,6 @@
 {% block titletag %}{% trans 'Search' %}{% endblock %}
 {% block extra_js %}
     {{ block.super }}
-
-    <script>
-        window.headerSearch = {
-            url: "{% url 'wagtailadmin_pages:search_results' %}",
-            termInput: "#id_q",
-            targetOutput: "#page-results"
-        }
-    </script>
     <script>
         window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'PAGE';
     </script>
@@ -19,8 +11,8 @@
 
 {% block content %}
     {% trans "Search" as search_str %}
-    {% include "wagtailadmin/shared/header.html" with title=search_str search_url="wagtailadmin_pages:search_results" icon="search" %}
-
+    {% url 'wagtailadmin_pages:search_results' as search_results_url %}
+    {% include "wagtailadmin/shared/header.html" with title=search_str search_url="wagtailadmin_pages:search" icon="search" search_results_url=search_results_url search_target="#page-results" %}
     <div id="page-results">
         {% include "wagtailadmin/pages/search_results.html" %}
     </div>

wagtail/admin/templates/wagtailadmin/shared/header.html

@@ -9,6 +9,9 @@
     - `description` - if present, displayed as a small text below the `h1` tag title
     - `search_url` - if present, display a search box. This is a URL route name (taking no parameters) to be used as the action for that search box
     - `search_form` - form object for the search form. Required if search_url is passed
+    - `search_results_url` - URL to be used for async requests to search results, if not provided, the form's action URL will be used
+    - `search_target` - A selector string to be used as the target for teh search results to be swapped into. Defaults to '#results'
+    - `search_disable_async` - If True, the default header async search functionality will not be used
     - `query_parameters` - a query string (without the '?') to be placed after the search URL
     - `icon` - name of an icon to place against the title
     - `avatar` - if present, display an 'avatar' in place of icon. This is the URL to be used as the img src for avatar
@@ -44,7 +47,19 @@
                 {% if description %}<div class="w-header__description">{{ description }}</div>{% endif %}
             </div>
             {% if search_url %}
-                <form class="col search-form" action="{% url search_url %}{% if query_parameters %}?{{ query_parameters }}{% endif %}" method="get" novalidate role="search">
+                <form
+                    class="col search-form"
+                    action="{% url search_url %}{% if query_parameters %}?{{ query_parameters }}{% endif %}"
+                    method="get"
+                    novalidate
+                    role="search"
+                    {% if not search_disable_async %}
+                        data-controller="w-swap"
+                        data-action="change->w-swap#searchLazy input->w-swap#searchLazy"
+                        {% if search_results_url %}data-w-swap-src-value="{{ search_results_url }}"{% endif %}
+                        {% if search_target %}data-w-swap-target-value="{{ search_target }}"{% endif %}
+                    {% endif %}
+                >
                     {% for field in search_form %}
                         {% include "wagtailadmin/shared/field.html" with field=field classname="w-mb-0 -w-mt-2.5" sr_only_label=True icon="search" %}
                     {% endfor %}

wagtail/contrib/redirects/templates/wagtailredirects/index.html

@@ -6,19 +6,9 @@
 
 {% block titletag %}{% trans "Redirects" %}{% endblock %}
 
-{% block extra_js %}
-    {{ block.super }}
-    <script>
-        window.headerSearch = {
-            url: "{% url 'wagtailredirects:index' %}",
-            termInput: "#id_q",
-            targetOutput: "#redirects-results"
-        }
-    </script>
-{% endblock %}
-
 {% block content %}
     {% trans "Redirects" as redirects_str %}
+    {% url 'wagtailredirects:index' as search_results_url %}
     {% if user_can_add %}
         {% url "wagtailredirects:add" as add_link %}
         {% trans "Add redirect" as add_str %}
@@ -35,17 +25,13 @@
                 </ul>
             </div>
         {% endfragment %}
-        {% include "wagtailadmin/shared/header.html" with title=redirects_str icon="redirect" search_url="wagtailredirects:index" query_parameters=query_parameters action_url=add_link action_text=add_str action_icon="plus" extra_actions=redirect_actions %}
-
-
+        {% include "wagtailadmin/shared/header.html" with title=redirects_str icon="redirect" search_url="wagtailredirects:index" query_parameters=query_parameters action_url=add_link action_text=add_str action_icon="plus" extra_actions=redirect_actions search_results_url=search_results_url search_target="#redirects-results" %}
     {% else %}
-        {% include "wagtailadmin/shared/header.html" with title=redirects_str icon="redirect" search_url="wagtailredirects:index" %}
+        {% include "wagtailadmin/shared/header.html" with title=redirects_str icon="redirect" search_url="wagtailredirects:index" search_results_url=search_results_url search_target="#redirects-results" %}
     {% endif %}
-
     <div class="nice-padding">
         <div id="redirects-results" class="redirects">
             {% include "wagtailredirects/results.html" %}
         </div>
     </div>
-
 {% endblock %}

wagtail/contrib/search_promotions/templates/wagtailsearchpromotions/index.html

@@ -2,23 +2,12 @@
 {% load i18n %}
 {% block titletag %}{% trans "Search Terms" %}{% endblock %}
 
-{% block extra_js %}
-    {{ block.super }}
-    <script>
-        window.headerSearch = {
-            url: "{% url 'wagtailsearchpromotions:index' %}",
-            termInput: "#id_q",
-            targetOutput: "#editorspicks-results"
-        }
-    </script>
-{% endblock %}
-
 {% block content %}
     {% trans "Promoted search results" as sp_title_str %}
     {% trans "Add new promoted result" as sp_text_str %}
-
+    {% url 'wagtailsearchpromotions:index' as search_results_url %}
     {% url "wagtailsearchpromotions:add" as add_link %}
-    {% include "wagtailadmin/shared/header.html" with title=sp_title_str action_url=add_link icon="pick" action_text=sp_text_str search_url="wagtailsearchpromotions:index" %}
+    {% include "wagtailadmin/shared/header.html" with title=sp_title_str action_url=add_link icon="pick" action_text=sp_text_str search_url="wagtailsearchpromotions:index" search_results_url=search_results_url search_target="#editorspicks-results" %}
 
     <div class="nice-padding">
         <div id="editorspicks-results" class="redirects">

wagtail/contrib/styleguide/templates/wagtailstyleguide/base.html

@@ -462,6 +462,7 @@
 
             {% url "wagtailstyleguide" as add_link %}
             {% include "wagtailadmin/shared/header.html" with title=title_trans action_url=add_link icon="image" action_text="button" search_url="wagtailimages:index" %}
+            <div id="listing-results" style="display: none;">{% comment %} Not implemented, hide content to avoid confusion {% endcomment %}</div>
         {% endpanel %}
 
         {% panel id="forms" heading="Forms" %}

wagtail/documents/templates/wagtaildocs/documents/index.html

@@ -3,13 +3,6 @@
 {% block titletag %}Documents{% endblock %}
 {% block extra_js %}
     {{ block.super }}
-    <script>
-        window.headerSearch = {
-            url: "{% url 'wagtaildocs:listing_results' %}",
-            termInput: "#id_q",
-            targetOutput: "#document-results"
-        }
-    </script>
     <script>
         window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'DOCUMENT';
     </script>
@@ -18,14 +11,14 @@
 
 {% block content %}
     {% trans "Documents" as doc_str %}
-
+    {% url 'wagtaildocs:listing_results' as search_results_url %}
     {% if user_can_add %}
         {% trans "Add a document" as add_doc_str %}
         {% url "wagtaildocs:add_multiple" as add_link %}
         {% querystring as querystring %}
-        {% include "wagtailadmin/shared/header.html" with title=doc_str action_url=add_link|add:querystring icon="doc-full-inverse" action_text=add_doc_str search_url="wagtaildocs:index" %}
+        {% include "wagtailadmin/shared/header.html" with title=doc_str action_url=add_link|add:querystring icon="doc-full-inverse" action_text=add_doc_str search_url="wagtaildocs:index" search_results_url=search_results_url search_target="#document-results" %}
     {% else %}
-        {% include "wagtailadmin/shared/header.html" with title=doc_str icon="doc-full-inverse" search_url="wagtaildocs:index" %}
+        {% include "wagtailadmin/shared/header.html" with title=doc_str icon="doc-full-inverse" search_url="wagtaildocs:index" search_results_url=search_results_url search_target="#document-results" %}
     {% endif %}
 
     <div class="nice-padding">

wagtail/images/templates/wagtailimages/images/index.html

@@ -6,13 +6,6 @@
 {% block titletag %}{% trans "Images" %}{% endblock %}
 {% block extra_js %}
     {{ block.super }}
-    <script>
-        window.headerSearch = {
-            url: "{% url 'wagtailimages:listing_results' %}",
-            termInput: "#id_q",
-            targetOutput: "#image-results"
-        }
-    </script>
     <script>
         window.wagtailConfig.BULK_ACTION_ITEM_TYPE = 'IMAGE';
     </script>
@@ -21,14 +14,14 @@
 
 {% block content %}
     {% trans "Images" as im_str %}
-
+    {% url 'wagtailimages:listing_results' as search_results_url %}
     {% if user_can_add %}
         {% trans "Add an image" as add_img_str %}
         {% url "wagtailimages:add_multiple" as add_link %}
         {% querystring as querystring %}
-        {% include "wagtailadmin/shared/header.html" with title=im_str action_url=add_link|add:querystring icon="image" action_text=add_img_str search_url="wagtailimages:index" %}
+        {% include "wagtailadmin/shared/header.html" with title=im_str action_url=add_link|add:querystring icon="image" action_text=add_img_str search_url="wagtailimages:index" search_results_url=search_results_url search_target="#image-results" %}
     {% else %}
-        {% include "wagtailadmin/shared/header.html" with title=im_str icon="image" search_url="wagtailimages:index" %}
+        {% include "wagtailadmin/shared/header.html" with title=im_str icon="image" search_url="wagtailimages:index" search_results_url=search_results_url search_target="#image-results" %}
     {% endif %}
 
     <div class="nice-padding">

wagtail/snippets/templates/wagtailsnippets/snippets/index.html

@@ -21,8 +21,7 @@
             {% include view.export_buttons_template_name %}
         {% endif %}
     {% endfragment %}
-    {% include 'wagtailadmin/shared/header.html' with breadcrumb=breadcrumb title=model_opts.verbose_name_plural|capfirst icon=header_icon search_url=search_url base_actions=base_action_locale action_url=action_url_add_snippet action_icon="plus" action_text=action_text_snippet extra_actions=extra_actions %}
-
+    {% include 'wagtailadmin/shared/header.html' with breadcrumb=breadcrumb title=model_opts.verbose_name_plural|capfirst icon=header_icon search_url=search_url base_actions=base_action_locale action_url=action_url_add_snippet action_icon="plus" action_text=action_text_snippet extra_actions=extra_actions search_results_url=index_results_url %}
     <div class="nice-padding{% if filters %} filterable{% endif %}">
         <div id="listing-results" class="snippets">
             {% include "wagtailsnippets/snippets/index_results.html" %}

wagtail/users/templates/wagtailusers/users/edit.html

@@ -4,7 +4,7 @@
 {% block content %}
 
     {% trans "Editing" as editing_str %}
-    {% include "wagtailadmin/shared/header.html" with title=editing_str subtitle=user.get_username merged=1 icon="user" %}
+    {% include "wagtailadmin/shared/header.html" with title=editing_str subtitle=user.get_username merged=1 icon="user" search_results_url=index_results_url %}
 
     <div class="w-tabs" data-tabs>
         <div class="w-tabs__wrapper">

wagtail/users/templates/wagtailusers/users/index.html

@@ -13,7 +13,7 @@
     {% trans "Add a user" as add_a_user_str %}
 
     {% url "wagtailusers_users:add" as add_link %}
-    {% include "wagtailadmin/shared/header.html" with subtitle=group.name title=users_str action_url=add_link action_text=add_a_user_str icon="user" search_url="wagtailusers_users:index" %}
+    {% include "wagtailadmin/shared/header.html" with subtitle=group.name title=users_str action_url=add_link action_text=add_a_user_str icon="user" search_url="wagtailusers_users:index" search_results_url=index_results_url %}
 
     <div class="nice-padding">
         <div id="listing-results" class="users">