From 989329344aabe8ef7a5e55bebfde53f0e00f42e2 Mon Sep 17 00:00:00 2001
From: Johannes Maron <johannes@maron.family>
Date: Thu, 7 Nov 2024 10:21:25 +0100
Subject: Fixed #35886 -- Added support for object-based form media script
 assets.

---
 docs/releases/5.2.txt       |  4 +++
 docs/topics/forms/media.txt | 63 +++++++++++++++++++++++++++++++++------------
 2 files changed, 50 insertions(+), 17 deletions(-)

(limited to 'docs')

diff --git a/docs/releases/5.2.txt b/docs/releases/5.2.txt
index aaf47ff8e8..de99832f13 100644
--- a/docs/releases/5.2.txt
+++ b/docs/releases/5.2.txt
@@ -259,6 +259,10 @@ Forms
 * An :attr:`~django.forms.BoundField.aria_describedby` property is added to
   ``BoundField`` to ease use of this HTML attribute in templates.
 
+* The new asset object :class:`~django.forms.Script` is available for adding
+  custom HTML-attributes to JavaScript in form media. See
+  :ref:`paths as objects <form-media-asset-objects>` for more details.
+
 Generic Views
 ~~~~~~~~~~~~~
 
diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt
index 3fddf2d4bb..17bd385ed0 100644
--- a/docs/topics/forms/media.txt
+++ b/docs/topics/forms/media.txt
@@ -2,6 +2,8 @@
 Form Assets (the ``Media`` class)
 =================================
 
+.. currentmodule:: django.forms
+
 Rendering an attractive and easy-to-use web form requires more than just
 HTML - it also requires CSS stylesheets, and if you want to use fancy widgets,
 you may also need to include some JavaScript on each page. The exact
@@ -130,6 +132,24 @@ A tuple describing the required JavaScript files. See :ref:`the
 section on paths <form-asset-paths>` for details of how to specify
 paths to these files.
 
+``Script`` objects
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.2
+
+.. class:: Script(src, **attributes)
+
+    Represents a script file.
+
+    The first parameter, ``src``, is the string path to the script file. See
+    :ref:`the section on paths <form-asset-paths>` for details on how to
+    specify paths to these files.
+
+    The optional keyword arguments, ``**attributes``, are HTML attributes that
+    are set on the rendered ``<script>`` tag.
+
+    See :ref:`form-media-asset-objects` for usage examples.
+
 ``extend``
 ----------
 
@@ -271,29 +291,38 @@ Or if :mod:`~django.contrib.staticfiles` is configured using the
     <script src="https://static.example.com/animations.27e20196a850.js"></script>
     <script src="https://othersite.com/actions.js"></script>
 
+.. _form-media-asset-objects:
+
 Paths as objects
 ----------------
 
-Asset paths may also be given as hashable objects implementing an
-``__html__()`` method. The ``__html__()`` method is typically added using the
-:func:`~django.utils.html.html_safe` decorator. The object is responsible for
-outputting the complete HTML ``<script>`` or ``<link>`` tag content:
+Assets may also be object-based, using :class:`.Script`.
+Furthermore, these allow you to pass custom HTML attributes::
 
-.. code-block:: pycon
+    class Media:
+        js = [
+            Script(
+                "https://cdn.example.com/something.min.js",
+                **{
+                    "crossorigin": "anonymous",
+                    "async": True,
+                },
+            ),
+        ]
+
+If this Media definition were to be rendered, it would become the following
+HTML:
 
-    >>> from django import forms
-    >>> from django.utils.html import html_safe
-    >>>
-    >>> @html_safe
-    ... class JSPath:
-    ...     def __str__(self):
-    ...         return '<script src="https://example.org/asset.js" defer>'
-    ...
+.. code-block:: html+django
 
-    >>> class SomeWidget(forms.TextInput):
-    ...     class Media:
-    ...         js = [JSPath()]
-    ...
+    <script src="https://cdn.example.com/something.min.js"
+            crossorigin="anonymous"
+            async>
+    </script>
+
+.. versionchanged:: 5.2
+
+    The object class ``Script`` was added.
 
 ``Media`` objects
 =================
-- 
cgit v1.3