==================================================================
django-js-asset -- JS, CSS and JSON support for django.forms.Media
==================================================================
**Note!** `Django 5.2 adds its own support for JavaScript objects
`__.
This library has a slightly different API and also supports much older
versions
of Django, *and* it also supports CSS and JSON tags.
Usage
=====
Use this to insert a script tag via ``forms.Media`` containing additional
attributes (such as id and ``data-*`` for CSP-compatible data
injection.):
.. code-block:: python
from js_asset import JS
forms.Media(js=[
JS("asset.js", {
"id": "asset-script",
"data-answer": "42",
}),
])
The rendered media tag (via ``{{ media.js }} or {{ media }}`` will
now contain a script tag as follows, without line breaks:
.. code-block:: html
The attributes are automatically escaped. The data attributes may now be
accessed inside ``asset.js``:
.. code-block:: javascript
var answer = document.querySelector("#asset-script").dataset.answer;
Also, because the implementation of static differs between supported
Django versions (older do not take the presence of
``django.contrib.staticfiles in INSTALLED_APPS`` into account), a
``js_asset.static`` function is provided which does the right thing
automatically.
CSS and JSON support
====================
Since 3.0 django-js-asset also ships a CSS and JSON media object which
can be used to ship stylesheets, inline styles and JSON blobs to the
frontend.
It's recommended to pass those through ``forms.Media(js=[]) as well since
js is a simple list while css`` uses a dictionary keyed with the media to
use for the stylesheet.
So, you can add everything at once:
.. code-block:: python
from js_asset import CSS, JS, JSON
forms.Media(js=[
JSON({"configuration": 42}, id="widget-configuration"),
CSS("widget/style.css"),
CSS("p{color:red;}", inline=True),
JS("widget/script.js", {"type": "module"}),
])
This produces:
.. code-block:: html
Compatibility
=============
At the time of writing this app is compatible with Django 4.2 and better
(up to and including the Django main branch), but have a look at the
[tox configuration
] for
definitive answers.
Extremely experimental importmap support
========================================
django-js-asset ships an extremely experimental implementation adding
support
for using [importmaps
].
One of the reasons why importmaps are useful when used with Django is that