mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-12-22 17:16:24 +00:00
Code Issues 25 Releases Wiki Activity

Fixed #35886 -- Added support for object-based form media script assets.

Browse Source
This commit is contained in:
Johannes Maron 2024-11-07 10:21:25 +01:00 committed by Sarah Boyce
parent fcd9d08379
commit e2d19b295c
4 changed files with 213 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
django/forms/widgets.py
View File

@ -9,7 +9,7 @@ from collections import defaultdict
from graphlib import CycleError, TopologicalSorter
from itertools import chain
from django.forms.utils import to_current_timezone
from django.forms.utils import flatatt, to_current_timezone
from django.templatetags.static import static
from django.utils import formats
from django.utils.choices import normalize_choices
@ -23,6 +23,7 @@ from django.utils.translation import gettext_lazy as _
from .renderers import get_default_renderer
__all__ = (
"Script",
"Media",
"MediaDefiningClass",
"Widget",
@ -61,6 +62,53 @@ class MediaOrderConflictWarning(RuntimeWarning):
pass
@html_safe
class MediaAsset:
element_template = "{path}"
def __init__(self, path, **attributes):
self._path = path
self.attributes = attributes
def __eq__(self, other):
# Compare the path only, to ensure performant comparison in Media.merge.
return (self.__class__ is other.__class__ and self.path == other.path) or (
isinstance(other, str) and self._path == other
)
def __hash__(self):
# Hash the path only, to ensure performant comparison in Media.merge.
return hash(self._path)
def __str__(self):
return format_html(
self.element_template,
path=self.path,
attributes=flatatt(self.attributes),
)
def __repr__(self):
return f"{type(self).__qualname__}({self._path!r})"
@property
def path(self):
"""
Ensure an absolute path.
Relative paths are resolved via the {% static %} template tag.
"""
if self._path.startswith(("http://", "https://", "/")):
return self._path
return static(self._path)
class Script(MediaAsset):
element_template = '<script src="{path}"{attributes}></script>'
def __init__(self, src, **attributes):
# We alter the signature to allow src to be passed as a keyword argument.
super().__init__(src, **attributes)
@html_safe
class Media:
def __init__(self, media=None, css=None, js=None):

4
docs/releases/5.2.txt
View File

@ -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
~~~~~~~~~~~~~

63
docs/topics/forms/media.txt
View File

@ -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,
},
),
]
>>> 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>'
...
If this Media definition were to be rendered, it would become the following
HTML:
>>> class SomeWidget(forms.TextInput):
... class Media:
... js = [JSPath()]
...
.. code-block:: html+django
<script src="https://cdn.example.com/something.min.js"
crossorigin="anonymous"
async>
</script>
.. versionchanged:: 5.2
The object class ``Script`` was added.
``Media`` objects
=================

190
tests/forms_tests/tests/test_media.py
View File

@ -1,8 +1,96 @@
from django.forms import CharField, Form, Media, MultiWidget, TextInput
from django.forms.widgets import MediaAsset, Script
from django.template import Context, Template
from django.templatetags.static import static
from django.test import SimpleTestCase, override_settings
from django.utils.html import format_html, html_safe
from django.utils.html import html_safe
class CSS(MediaAsset):
element_template = '<link href="{path}"{attributes}>'
def __init__(self, href, **attributes):
super().__init__(href, **attributes)
self.attributes["rel"] = "stylesheet"
@override_settings(
STATIC_URL="http://media.example.com/static/",
)
class MediaAssetTestCase(SimpleTestCase):
def test_init(self):
attributes = {"media": "all", "is": "magic-css"}
asset = MediaAsset("path/to/css", **attributes)
self.assertEqual(asset._path, "path/to/css")
self.assertEqual(asset.attributes, attributes)
self.assertIsNot(asset.attributes, attributes)
def test_eq(self):
self.assertEqual(MediaAsset("path/to/css"), MediaAsset("path/to/css"))
self.assertEqual(MediaAsset("path/to/css"), "path/to/css")
self.assertEqual(
MediaAsset("path/to/css", media="all"), MediaAsset("path/to/css")
)
self.assertNotEqual(MediaAsset("path/to/css"), MediaAsset("path/to/other.css"))
self.assertNotEqual(MediaAsset("path/to/css"), "path/to/other.css")
self.assertNotEqual(MediaAsset("path/to/css", media="all"), CSS("path/to/css"))
def test_hash(self):
self.assertEqual(hash(MediaAsset("path/to/css")), hash("path/to/css"))
self.assertEqual(
hash(MediaAsset("path/to/css")), hash(MediaAsset("path/to/css"))
)
def test_str(self):
self.assertEqual(
str(MediaAsset("path/to/css")),
"http://media.example.com/static/path/to/css",
)
self.assertEqual(
str(MediaAsset("http://media.other.com/path/to/css")),
"http://media.other.com/path/to/css",
)
def test_repr(self):
self.assertEqual(repr(MediaAsset("path/to/css")), "MediaAsset('path/to/css')")
self.assertEqual(
repr(MediaAsset("http://media.other.com/path/to/css")),
"MediaAsset('http://media.other.com/path/to/css')",
)
def test_path(self):
asset = MediaAsset("path/to/css")
self.assertEqual(asset.path, "http://media.example.com/static/path/to/css")
asset = MediaAsset("http://media.other.com/path/to/css")
self.assertEqual(asset.path, "http://media.other.com/path/to/css")
asset = MediaAsset("https://secure.other.com/path/to/css")
self.assertEqual(asset.path, "https://secure.other.com/path/to/css")
asset = MediaAsset("/absolute/path/to/css")
self.assertEqual(asset.path, "/absolute/path/to/css")
asset = MediaAsset("//absolute/path/to/css")
self.assertEqual(asset.path, "//absolute/path/to/css")
@override_settings(STATIC_URL="http://media.example.com/static/")
class ScriptTestCase(SimpleTestCase):
def test_init_with_src_kwarg(self):
self.assertEqual(
Script(src="path/to/js").path, "http://media.example.com/static/path/to/js"
)
def test_str(self):
self.assertHTMLEqual(
str(Script("path/to/js")),
'<script src="http://media.example.com/static/path/to/js"></script>',
)
self.assertHTMLEqual(
str(Script("path/to/js", **{"async": True, "deferred": False})),
'<script src="http://media.example.com/static/path/to/js" async></script>',
)
@override_settings(
@ -714,63 +802,6 @@ class FormsMediaTestCase(SimpleTestCase):
self.assertEqual(merged._js_lists, [["a"]])
@html_safe
class Asset:
def __init__(self, path):
self.path = path
def __eq__(self, other):
return (self.__class__ == other.__class__ and self.path == other.path) or (
other.__class__ == str and self.path == other
)
def __hash__(self):
return hash(self.path)
def __str__(self):
return self.absolute_path(self.path)
def absolute_path(self, path):
"""
Given a relative or absolute path to a static asset, return an absolute
path. An absolute path will be returned unchanged while a relative path
will be passed to django.templatetags.static.static().
"""
if path.startswith(("http://", "https://", "/")):
return path
return static(path)
def __repr__(self):
return f"{self.path!r}"
class CSS(Asset):
def __init__(self, path, medium):
super().__init__(path)
self.medium = medium
def __str__(self):
path = super().__str__()
return format_html(
'<link href="{}" media="{}" rel="stylesheet">',
self.absolute_path(path),
self.medium,
)
class JS(Asset):
def __init__(self, path, integrity=None):
super().__init__(path)
self.integrity = integrity or ""
def __str__(self, integrity=None):
path = super().__str__()
template = '<script src="{}"%s></script>' % (
' integrity="{}"' if self.integrity else "{}"
)
return format_html(template, self.absolute_path(path), self.integrity)
@override_settings(
STATIC_URL="http://media.example.com/static/",
)
@ -779,17 +810,22 @@ class FormsMediaObjectTestCase(SimpleTestCase):
def test_construction(self):
m = Media(
css={"all": (CSS("path/to/css1", "all"), CSS("/path/to/css2", "all"))},
css={
"all": (
CSS("path/to/css1", media="all"),
CSS("/path/to/css2", media="all"),
)
},
js=(
JS("/path/to/js1"),
JS("http://media.other.com/path/to/js2"),
JS(
Script("/path/to/js1"),
Script("http://media.other.com/path/to/js2"),
Script(
"https://secure.other.com/path/to/js3",
integrity="9d947b87fdeb25030d56d01f7aa75800",
),
),
)
self.assertEqual(
self.assertHTMLEqual(
str(m),
'<link href="http://media.example.com/static/path/to/css1" media="all" '
'rel="stylesheet">\n'
@ -801,9 +837,9 @@ class FormsMediaObjectTestCase(SimpleTestCase):
)
self.assertEqual(
repr(m),
"Media(css={'all': ['path/to/css1', '/path/to/css2']}, "
"js=['/path/to/js1', 'http://media.other.com/path/to/js2', "
"'https://secure.other.com/path/to/js3'])",
"Media(css={'all': [CSS('path/to/css1'), CSS('/path/to/css2')]}, "
"js=[Script('/path/to/js1'), Script('http://media.other.com/path/to/js2'), "
"Script('https://secure.other.com/path/to/js3')])",
)
def test_simplest_class(self):
@ -823,22 +859,24 @@ class FormsMediaObjectTestCase(SimpleTestCase):
def test_combine_media(self):
class MyWidget1(TextInput):
class Media:
css = {"all": (CSS("path/to/css1", "all"), "/path/to/css2")}
css = {"all": (CSS("path/to/css1", media="all"), "/path/to/css2")}
js = (
"/path/to/js1",
"http://media.other.com/path/to/js2",
"https://secure.other.com/path/to/js3",
JS("/path/to/js4", integrity="9d947b87fdeb25030d56d01f7aa75800"),
Script(
"/path/to/js4", integrity="9d947b87fdeb25030d56d01f7aa75800"
),
)
class MyWidget2(TextInput):
class Media:
css = {"all": (CSS("/path/to/css2", "all"), "/path/to/css3")}
js = (JS("/path/to/js1"), "/path/to/js4")
css = {"all": (CSS("/path/to/css2", media="all"), "/path/to/css3")}
js = (Script("/path/to/js1"), "/path/to/js4")
w1 = MyWidget1()
w2 = MyWidget2()
self.assertEqual(
self.assertHTMLEqual(
str(w1.media + w2.media),
'<link href="http://media.example.com/static/path/to/css1" media="all" '
'rel="stylesheet">\n'
@ -857,14 +895,14 @@ class FormsMediaObjectTestCase(SimpleTestCase):
media = Media(
css={
"all": (
CSS("/path/to/css1", "all"),
CSS("/path/to/css1", "all"),
CSS("/path/to/css1", media="all"),
CSS("/path/to/css1", media="all"),
"/path/to/css1",
)
},
js=(JS("/path/to/js1"), JS("/path/to/js1"), "/path/to/js1"),
js=(Script("/path/to/js1"), Script("/path/to/js1"), "/path/to/js1"),
)
self.assertEqual(
self.assertHTMLEqual(
str(media),
'<link href="/path/to/css1" media="all" rel="stylesheet">\n'
'<script src="/path/to/js1"></script>',