django-components 0.81__tar.gz → 0.82__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {django_components-0.81/src/django_components.egg-info → django_components-0.82}/PKG-INFO +213 -8
- {django_components-0.81 → django_components-0.82}/README.md +212 -7
- {django_components-0.81 → django_components-0.82}/pyproject.toml +1 -1
- {django_components-0.81 → django_components-0.82}/src/django_components/component.py +11 -137
- django_components-0.82/src/django_components/component_media.py +350 -0
- {django_components-0.81 → django_components-0.82/src/django_components.egg-info}/PKG-INFO +213 -8
- {django_components-0.81 → django_components-0.82}/src/django_components.egg-info/SOURCES.txt +1 -0
- {django_components-0.81 → django_components-0.82}/tests/test_autodiscover.py +3 -1
- django_components-0.82/tests/test_component_media.py +861 -0
- django_components-0.81/tests/test_component_media.py +0 -386
- {django_components-0.81 → django_components-0.82}/LICENSE +0 -0
- {django_components-0.81 → django_components-0.82}/setup.cfg +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/__init__.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/app_settings.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/apps.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/attributes.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/component_registry.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/context.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/expression.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/logger.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/management/__init__.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/middleware.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/node.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/provide.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/py.typed +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/slots.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/template_loader.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/template_parser.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/templatetags/component_tags.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/types.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components/utils.py +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.81 → django_components-0.82}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_attributes.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_command_startcomponent.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_component.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_component_as_view.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_context.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_registry.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_settings.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_template_parser.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_templatetags.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_templatetags_component.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_templatetags_provide.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_templatetags_slot_fill.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/test_templatetags_templating.py +0 -0
- {django_components-0.81 → django_components-0.82}/tests/testutils.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: django_components
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.82
|
|
4
4
|
Summary: A way to create simple reusable template components in Django.
|
|
5
5
|
Author-email: Emil Stenström <emil@emilstenstrom.se>
|
|
6
6
|
License: MIT
|
|
@@ -59,7 +59,8 @@ Read on to learn about the details!
|
|
|
59
59
|
- [Rendering HTML attributes](#rendering-html-attributes)
|
|
60
60
|
- [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
|
|
61
61
|
- [Component context and scope](#component-context-and-scope)
|
|
62
|
-
- [
|
|
62
|
+
- [Defining HTML/JS/CSS files](#defining-htmljscss-files)
|
|
63
|
+
- [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
|
|
63
64
|
- [Available settings](#available-settings)
|
|
64
65
|
- [Logging and debugging](#logging-and-debugging)
|
|
65
66
|
- [Management Command](#management-command)
|
|
@@ -286,9 +287,12 @@ from django_components import component
|
|
|
286
287
|
|
|
287
288
|
@component.register("calendar")
|
|
288
289
|
class Calendar(component.Component):
|
|
289
|
-
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
290
|
-
#
|
|
291
|
-
|
|
290
|
+
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
291
|
+
# will be automatically found. To customize which template to use based on context
|
|
292
|
+
# you can override method `get_template_name` instead of specifying `template_name`.
|
|
293
|
+
#
|
|
294
|
+
# `template_name` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
295
|
+
template_name = "template.html"
|
|
292
296
|
|
|
293
297
|
# This component takes one parameter, a date string to show in the template
|
|
294
298
|
def get_context_data(self, date):
|
|
@@ -296,9 +300,10 @@ class Calendar(component.Component):
|
|
|
296
300
|
"date": date,
|
|
297
301
|
}
|
|
298
302
|
|
|
303
|
+
# Both `css` and `js` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
299
304
|
class Media:
|
|
300
|
-
css = "
|
|
301
|
-
js = "
|
|
305
|
+
css = "style.css"
|
|
306
|
+
js = "script.js"
|
|
302
307
|
```
|
|
303
308
|
|
|
304
309
|
And voilá!! We've created our first component.
|
|
@@ -1669,7 +1674,207 @@ If you find yourself using the `only` modifier often, you can set the [context_b
|
|
|
1669
1674
|
|
|
1670
1675
|
Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
|
|
1671
1676
|
|
|
1672
|
-
##
|
|
1677
|
+
## Defining HTML/JS/CSS files
|
|
1678
|
+
|
|
1679
|
+
django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
|
|
1680
|
+
|
|
1681
|
+
To be familiar with how Django handles static files, we recommend reading also:
|
|
1682
|
+
- [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
|
|
1683
|
+
|
|
1684
|
+
### Defining file paths relative to component or static dirs
|
|
1685
|
+
|
|
1686
|
+
As seen in the [getting started example](#create-your-first-component), to associate HTML/JS/CSS
|
|
1687
|
+
files with a component, you set them as `template_name`, `Media.js` and `Media.css` respectively:
|
|
1688
|
+
|
|
1689
|
+
```py
|
|
1690
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1691
|
+
from django_components import component
|
|
1692
|
+
|
|
1693
|
+
@component.register("calendar")
|
|
1694
|
+
class Calendar(component.Component):
|
|
1695
|
+
template_name = "template.html"
|
|
1696
|
+
|
|
1697
|
+
class Media:
|
|
1698
|
+
css = "style.css"
|
|
1699
|
+
js = "script.js"
|
|
1700
|
+
```
|
|
1701
|
+
|
|
1702
|
+
In the example above, the files are defined relative to the directory where `component.py` is.
|
|
1703
|
+
|
|
1704
|
+
Alternatively, you can specify the file paths relative to the directories set in `STATICFILES_DIRS`.
|
|
1705
|
+
|
|
1706
|
+
Assuming that `STATICFILES_DIRS` contains path `[project root]/components`, we can rewrite the example as:
|
|
1707
|
+
|
|
1708
|
+
```py
|
|
1709
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1710
|
+
from django_components import component
|
|
1711
|
+
|
|
1712
|
+
@component.register("calendar")
|
|
1713
|
+
class Calendar(component.Component):
|
|
1714
|
+
template_name = "calendar/template.html"
|
|
1715
|
+
|
|
1716
|
+
class Media:
|
|
1717
|
+
css = "calendar/style.css"
|
|
1718
|
+
js = "calendar/script.js"
|
|
1719
|
+
```
|
|
1720
|
+
|
|
1721
|
+
NOTE: In case of conflict, the preference goes to resolving the files relative to the component's directory.
|
|
1722
|
+
|
|
1723
|
+
### Defining multiple paths
|
|
1724
|
+
|
|
1725
|
+
Each component can have only a single template. However, you can define as many JS or CSS files as you want using a list.
|
|
1726
|
+
|
|
1727
|
+
```py
|
|
1728
|
+
class MyComponent(component.Component):
|
|
1729
|
+
class Media:
|
|
1730
|
+
js = ["path/to/script1.js", "path/to/script2.js"]
|
|
1731
|
+
css = ["path/to/style1.css", "path/to/style2.css"]
|
|
1732
|
+
```
|
|
1733
|
+
|
|
1734
|
+
### Configuring CSS Media Types
|
|
1735
|
+
|
|
1736
|
+
You can define which stylesheets will be associated with which
|
|
1737
|
+
[CSS Media types](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries#targeting_media_types). You do so by defining CSS files as a dictionary.
|
|
1738
|
+
|
|
1739
|
+
See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5.0/topics/forms/media/#css).
|
|
1740
|
+
|
|
1741
|
+
Again, you can set either a single file or a list of files per media type:
|
|
1742
|
+
|
|
1743
|
+
```py
|
|
1744
|
+
class MyComponent(component.Component):
|
|
1745
|
+
class Media:
|
|
1746
|
+
css = {
|
|
1747
|
+
"all": "path/to/style1.css",
|
|
1748
|
+
"print": "path/to/style2.css",
|
|
1749
|
+
}
|
|
1750
|
+
```
|
|
1751
|
+
|
|
1752
|
+
```py
|
|
1753
|
+
class MyComponent(component.Component):
|
|
1754
|
+
class Media:
|
|
1755
|
+
css = {
|
|
1756
|
+
"all": ["path/to/style1.css", "path/to/style2.css"],
|
|
1757
|
+
"print": ["path/to/style3.css", "path/to/style4.css"],
|
|
1758
|
+
}
|
|
1759
|
+
```
|
|
1760
|
+
|
|
1761
|
+
NOTE: When you define CSS as a string or a list, the `all` media type is implied.
|
|
1762
|
+
|
|
1763
|
+
|
|
1764
|
+
### Supported types for file paths
|
|
1765
|
+
|
|
1766
|
+
File paths can be any of:
|
|
1767
|
+
- `str`
|
|
1768
|
+
- `bytes`
|
|
1769
|
+
- `PathLike` (`__fspath__` method)
|
|
1770
|
+
- `SafeData` (`__html__` method)
|
|
1771
|
+
- `Callable` that returns any of the above, evaluated at class creation (`__new__`)
|
|
1772
|
+
|
|
1773
|
+
```py
|
|
1774
|
+
from pathlib import Path
|
|
1775
|
+
|
|
1776
|
+
from django.utils.safestring import mark_safe
|
|
1777
|
+
|
|
1778
|
+
class SimpleComponent(component.Component):
|
|
1779
|
+
class Media:
|
|
1780
|
+
css = [
|
|
1781
|
+
mark_safe('<link href="/static/calendar/style.css" rel="stylesheet" />'),
|
|
1782
|
+
Path("calendar/style1.css"),
|
|
1783
|
+
"calendar/style2.css",
|
|
1784
|
+
b"calendar/style3.css",
|
|
1785
|
+
lambda: "calendar/style4.css",
|
|
1786
|
+
]
|
|
1787
|
+
js = [
|
|
1788
|
+
mark_safe('<script src="/static/calendar/script.js"></script>'),
|
|
1789
|
+
Path("calendar/script1.js"),
|
|
1790
|
+
"calendar/script2.js",
|
|
1791
|
+
b"calendar/script3.js",
|
|
1792
|
+
lambda: "calendar/script4.js",
|
|
1793
|
+
]
|
|
1794
|
+
```
|
|
1795
|
+
|
|
1796
|
+
### Path as objects
|
|
1797
|
+
|
|
1798
|
+
In the example [above](#supported-types-for-file-paths), you could see that when we used `mark_safe` to mark a string as a `SafeString`, we had to define the full `<script>`/`<link>` tag.
|
|
1799
|
+
|
|
1800
|
+
This is an extension of Django's [Paths as objects](https://docs.djangoproject.com/en/5.0/topics/forms/media/#paths-as-objects) feature, where "safe" strings are taken as is, and accessed only at render time.
|
|
1801
|
+
|
|
1802
|
+
Because of that, the paths defined as "safe" strings are NEVER resolved, neither relative to component's directory, nor relative to `STATICFILES_DIRS`.
|
|
1803
|
+
|
|
1804
|
+
"Safe" strings can be used to lazily resolve a path, or to customize the `<script>` or `<link>` tag for individual paths:
|
|
1805
|
+
|
|
1806
|
+
```py
|
|
1807
|
+
class LazyJsPath:
|
|
1808
|
+
def __init__(self, static_path: str) -> None:
|
|
1809
|
+
self.static_path = static_path
|
|
1810
|
+
|
|
1811
|
+
def __html__(self):
|
|
1812
|
+
full_path = static(self.static_path)
|
|
1813
|
+
return format_html(
|
|
1814
|
+
f'<script type="module" src="{full_path}"></script>'
|
|
1815
|
+
)
|
|
1816
|
+
|
|
1817
|
+
@component.register("calendar")
|
|
1818
|
+
class Calendar(component.Component):
|
|
1819
|
+
template_name = "calendar/template.html"
|
|
1820
|
+
|
|
1821
|
+
def get_context_data(self, date):
|
|
1822
|
+
return {
|
|
1823
|
+
"date": date,
|
|
1824
|
+
}
|
|
1825
|
+
|
|
1826
|
+
class Media:
|
|
1827
|
+
css = "calendar/style.css"
|
|
1828
|
+
js = [
|
|
1829
|
+
# <script> tag constructed by Media class
|
|
1830
|
+
"calendar/script1.js",
|
|
1831
|
+
# Custom <script> tag
|
|
1832
|
+
LazyJsPath("calendar/script2.js"),
|
|
1833
|
+
]
|
|
1834
|
+
```
|
|
1835
|
+
|
|
1836
|
+
### Customize how paths are rendered into HTML tags with `media_class`
|
|
1837
|
+
|
|
1838
|
+
Sometimes you may need to change how all CSS `<link>` or JS `<script>` tags are rendered for a given component. You can achieve this by providing your own subclass of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media) to component's `media_class` attribute.
|
|
1839
|
+
|
|
1840
|
+
Normally, the JS and CSS paths are passed to `Media` class, which decides how the paths are resolved and how the `<link>` and `<script>` tags are constructed.
|
|
1841
|
+
|
|
1842
|
+
To change how the tags are constructed, you can override the [`Media.render_js` and `Media.render_css` methods](https://github.com/django/django/blob/fa7848146738a9fe1d415ee4808664e54739eeb7/django/forms/widgets.py#L102):
|
|
1843
|
+
|
|
1844
|
+
```py
|
|
1845
|
+
from django.forms.widgets import Media
|
|
1846
|
+
from django_components import component
|
|
1847
|
+
|
|
1848
|
+
class MyMedia(Media):
|
|
1849
|
+
# Same as original Media.render_js, except
|
|
1850
|
+
# the `<script>` tag has also `type="module"`
|
|
1851
|
+
def render_js(self):
|
|
1852
|
+
tags = []
|
|
1853
|
+
for path in self._js:
|
|
1854
|
+
if hasattr(path, "__html__"):
|
|
1855
|
+
tag = path.__html__()
|
|
1856
|
+
else:
|
|
1857
|
+
tag = format_html(
|
|
1858
|
+
'<script type="module" src="{}"></script>',
|
|
1859
|
+
self.absolute_path(path)
|
|
1860
|
+
)
|
|
1861
|
+
return tags
|
|
1862
|
+
|
|
1863
|
+
@component.register("calendar")
|
|
1864
|
+
class Calendar(component.Component):
|
|
1865
|
+
template_name = "calendar/template.html"
|
|
1866
|
+
|
|
1867
|
+
class Media:
|
|
1868
|
+
css = "calendar/style.css"
|
|
1869
|
+
js = "calendar/script.js"
|
|
1870
|
+
|
|
1871
|
+
# Override the behavior of Media class
|
|
1872
|
+
media_class = MyMedia
|
|
1873
|
+
```
|
|
1874
|
+
|
|
1875
|
+
NOTE: The instance of the `Media` class (or it's subclass) is available under `Component.media` after the class creation (`__new__`).
|
|
1876
|
+
|
|
1877
|
+
## Rendering JS/CSS dependencies
|
|
1673
1878
|
|
|
1674
1879
|
The JS and CSS files included in components are not automatically rendered.
|
|
1675
1880
|
Instead, use the following tags to specify where to render the dependencies:
|
|
@@ -35,7 +35,8 @@ Read on to learn about the details!
|
|
|
35
35
|
- [Rendering HTML attributes](#rendering-html-attributes)
|
|
36
36
|
- [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
|
|
37
37
|
- [Component context and scope](#component-context-and-scope)
|
|
38
|
-
- [
|
|
38
|
+
- [Defining HTML/JS/CSS files](#defining-htmljscss-files)
|
|
39
|
+
- [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
|
|
39
40
|
- [Available settings](#available-settings)
|
|
40
41
|
- [Logging and debugging](#logging-and-debugging)
|
|
41
42
|
- [Management Command](#management-command)
|
|
@@ -262,9 +263,12 @@ from django_components import component
|
|
|
262
263
|
|
|
263
264
|
@component.register("calendar")
|
|
264
265
|
class Calendar(component.Component):
|
|
265
|
-
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
266
|
-
#
|
|
267
|
-
|
|
266
|
+
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
267
|
+
# will be automatically found. To customize which template to use based on context
|
|
268
|
+
# you can override method `get_template_name` instead of specifying `template_name`.
|
|
269
|
+
#
|
|
270
|
+
# `template_name` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
271
|
+
template_name = "template.html"
|
|
268
272
|
|
|
269
273
|
# This component takes one parameter, a date string to show in the template
|
|
270
274
|
def get_context_data(self, date):
|
|
@@ -272,9 +276,10 @@ class Calendar(component.Component):
|
|
|
272
276
|
"date": date,
|
|
273
277
|
}
|
|
274
278
|
|
|
279
|
+
# Both `css` and `js` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
275
280
|
class Media:
|
|
276
|
-
css = "
|
|
277
|
-
js = "
|
|
281
|
+
css = "style.css"
|
|
282
|
+
js = "script.js"
|
|
278
283
|
```
|
|
279
284
|
|
|
280
285
|
And voilá!! We've created our first component.
|
|
@@ -1645,7 +1650,207 @@ If you find yourself using the `only` modifier often, you can set the [context_b
|
|
|
1645
1650
|
|
|
1646
1651
|
Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
|
|
1647
1652
|
|
|
1648
|
-
##
|
|
1653
|
+
## Defining HTML/JS/CSS files
|
|
1654
|
+
|
|
1655
|
+
django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
|
|
1656
|
+
|
|
1657
|
+
To be familiar with how Django handles static files, we recommend reading also:
|
|
1658
|
+
- [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
|
|
1659
|
+
|
|
1660
|
+
### Defining file paths relative to component or static dirs
|
|
1661
|
+
|
|
1662
|
+
As seen in the [getting started example](#create-your-first-component), to associate HTML/JS/CSS
|
|
1663
|
+
files with a component, you set them as `template_name`, `Media.js` and `Media.css` respectively:
|
|
1664
|
+
|
|
1665
|
+
```py
|
|
1666
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1667
|
+
from django_components import component
|
|
1668
|
+
|
|
1669
|
+
@component.register("calendar")
|
|
1670
|
+
class Calendar(component.Component):
|
|
1671
|
+
template_name = "template.html"
|
|
1672
|
+
|
|
1673
|
+
class Media:
|
|
1674
|
+
css = "style.css"
|
|
1675
|
+
js = "script.js"
|
|
1676
|
+
```
|
|
1677
|
+
|
|
1678
|
+
In the example above, the files are defined relative to the directory where `component.py` is.
|
|
1679
|
+
|
|
1680
|
+
Alternatively, you can specify the file paths relative to the directories set in `STATICFILES_DIRS`.
|
|
1681
|
+
|
|
1682
|
+
Assuming that `STATICFILES_DIRS` contains path `[project root]/components`, we can rewrite the example as:
|
|
1683
|
+
|
|
1684
|
+
```py
|
|
1685
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1686
|
+
from django_components import component
|
|
1687
|
+
|
|
1688
|
+
@component.register("calendar")
|
|
1689
|
+
class Calendar(component.Component):
|
|
1690
|
+
template_name = "calendar/template.html"
|
|
1691
|
+
|
|
1692
|
+
class Media:
|
|
1693
|
+
css = "calendar/style.css"
|
|
1694
|
+
js = "calendar/script.js"
|
|
1695
|
+
```
|
|
1696
|
+
|
|
1697
|
+
NOTE: In case of conflict, the preference goes to resolving the files relative to the component's directory.
|
|
1698
|
+
|
|
1699
|
+
### Defining multiple paths
|
|
1700
|
+
|
|
1701
|
+
Each component can have only a single template. However, you can define as many JS or CSS files as you want using a list.
|
|
1702
|
+
|
|
1703
|
+
```py
|
|
1704
|
+
class MyComponent(component.Component):
|
|
1705
|
+
class Media:
|
|
1706
|
+
js = ["path/to/script1.js", "path/to/script2.js"]
|
|
1707
|
+
css = ["path/to/style1.css", "path/to/style2.css"]
|
|
1708
|
+
```
|
|
1709
|
+
|
|
1710
|
+
### Configuring CSS Media Types
|
|
1711
|
+
|
|
1712
|
+
You can define which stylesheets will be associated with which
|
|
1713
|
+
[CSS Media types](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries#targeting_media_types). You do so by defining CSS files as a dictionary.
|
|
1714
|
+
|
|
1715
|
+
See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5.0/topics/forms/media/#css).
|
|
1716
|
+
|
|
1717
|
+
Again, you can set either a single file or a list of files per media type:
|
|
1718
|
+
|
|
1719
|
+
```py
|
|
1720
|
+
class MyComponent(component.Component):
|
|
1721
|
+
class Media:
|
|
1722
|
+
css = {
|
|
1723
|
+
"all": "path/to/style1.css",
|
|
1724
|
+
"print": "path/to/style2.css",
|
|
1725
|
+
}
|
|
1726
|
+
```
|
|
1727
|
+
|
|
1728
|
+
```py
|
|
1729
|
+
class MyComponent(component.Component):
|
|
1730
|
+
class Media:
|
|
1731
|
+
css = {
|
|
1732
|
+
"all": ["path/to/style1.css", "path/to/style2.css"],
|
|
1733
|
+
"print": ["path/to/style3.css", "path/to/style4.css"],
|
|
1734
|
+
}
|
|
1735
|
+
```
|
|
1736
|
+
|
|
1737
|
+
NOTE: When you define CSS as a string or a list, the `all` media type is implied.
|
|
1738
|
+
|
|
1739
|
+
|
|
1740
|
+
### Supported types for file paths
|
|
1741
|
+
|
|
1742
|
+
File paths can be any of:
|
|
1743
|
+
- `str`
|
|
1744
|
+
- `bytes`
|
|
1745
|
+
- `PathLike` (`__fspath__` method)
|
|
1746
|
+
- `SafeData` (`__html__` method)
|
|
1747
|
+
- `Callable` that returns any of the above, evaluated at class creation (`__new__`)
|
|
1748
|
+
|
|
1749
|
+
```py
|
|
1750
|
+
from pathlib import Path
|
|
1751
|
+
|
|
1752
|
+
from django.utils.safestring import mark_safe
|
|
1753
|
+
|
|
1754
|
+
class SimpleComponent(component.Component):
|
|
1755
|
+
class Media:
|
|
1756
|
+
css = [
|
|
1757
|
+
mark_safe('<link href="/static/calendar/style.css" rel="stylesheet" />'),
|
|
1758
|
+
Path("calendar/style1.css"),
|
|
1759
|
+
"calendar/style2.css",
|
|
1760
|
+
b"calendar/style3.css",
|
|
1761
|
+
lambda: "calendar/style4.css",
|
|
1762
|
+
]
|
|
1763
|
+
js = [
|
|
1764
|
+
mark_safe('<script src="/static/calendar/script.js"></script>'),
|
|
1765
|
+
Path("calendar/script1.js"),
|
|
1766
|
+
"calendar/script2.js",
|
|
1767
|
+
b"calendar/script3.js",
|
|
1768
|
+
lambda: "calendar/script4.js",
|
|
1769
|
+
]
|
|
1770
|
+
```
|
|
1771
|
+
|
|
1772
|
+
### Path as objects
|
|
1773
|
+
|
|
1774
|
+
In the example [above](#supported-types-for-file-paths), you could see that when we used `mark_safe` to mark a string as a `SafeString`, we had to define the full `<script>`/`<link>` tag.
|
|
1775
|
+
|
|
1776
|
+
This is an extension of Django's [Paths as objects](https://docs.djangoproject.com/en/5.0/topics/forms/media/#paths-as-objects) feature, where "safe" strings are taken as is, and accessed only at render time.
|
|
1777
|
+
|
|
1778
|
+
Because of that, the paths defined as "safe" strings are NEVER resolved, neither relative to component's directory, nor relative to `STATICFILES_DIRS`.
|
|
1779
|
+
|
|
1780
|
+
"Safe" strings can be used to lazily resolve a path, or to customize the `<script>` or `<link>` tag for individual paths:
|
|
1781
|
+
|
|
1782
|
+
```py
|
|
1783
|
+
class LazyJsPath:
|
|
1784
|
+
def __init__(self, static_path: str) -> None:
|
|
1785
|
+
self.static_path = static_path
|
|
1786
|
+
|
|
1787
|
+
def __html__(self):
|
|
1788
|
+
full_path = static(self.static_path)
|
|
1789
|
+
return format_html(
|
|
1790
|
+
f'<script type="module" src="{full_path}"></script>'
|
|
1791
|
+
)
|
|
1792
|
+
|
|
1793
|
+
@component.register("calendar")
|
|
1794
|
+
class Calendar(component.Component):
|
|
1795
|
+
template_name = "calendar/template.html"
|
|
1796
|
+
|
|
1797
|
+
def get_context_data(self, date):
|
|
1798
|
+
return {
|
|
1799
|
+
"date": date,
|
|
1800
|
+
}
|
|
1801
|
+
|
|
1802
|
+
class Media:
|
|
1803
|
+
css = "calendar/style.css"
|
|
1804
|
+
js = [
|
|
1805
|
+
# <script> tag constructed by Media class
|
|
1806
|
+
"calendar/script1.js",
|
|
1807
|
+
# Custom <script> tag
|
|
1808
|
+
LazyJsPath("calendar/script2.js"),
|
|
1809
|
+
]
|
|
1810
|
+
```
|
|
1811
|
+
|
|
1812
|
+
### Customize how paths are rendered into HTML tags with `media_class`
|
|
1813
|
+
|
|
1814
|
+
Sometimes you may need to change how all CSS `<link>` or JS `<script>` tags are rendered for a given component. You can achieve this by providing your own subclass of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media) to component's `media_class` attribute.
|
|
1815
|
+
|
|
1816
|
+
Normally, the JS and CSS paths are passed to `Media` class, which decides how the paths are resolved and how the `<link>` and `<script>` tags are constructed.
|
|
1817
|
+
|
|
1818
|
+
To change how the tags are constructed, you can override the [`Media.render_js` and `Media.render_css` methods](https://github.com/django/django/blob/fa7848146738a9fe1d415ee4808664e54739eeb7/django/forms/widgets.py#L102):
|
|
1819
|
+
|
|
1820
|
+
```py
|
|
1821
|
+
from django.forms.widgets import Media
|
|
1822
|
+
from django_components import component
|
|
1823
|
+
|
|
1824
|
+
class MyMedia(Media):
|
|
1825
|
+
# Same as original Media.render_js, except
|
|
1826
|
+
# the `<script>` tag has also `type="module"`
|
|
1827
|
+
def render_js(self):
|
|
1828
|
+
tags = []
|
|
1829
|
+
for path in self._js:
|
|
1830
|
+
if hasattr(path, "__html__"):
|
|
1831
|
+
tag = path.__html__()
|
|
1832
|
+
else:
|
|
1833
|
+
tag = format_html(
|
|
1834
|
+
'<script type="module" src="{}"></script>',
|
|
1835
|
+
self.absolute_path(path)
|
|
1836
|
+
)
|
|
1837
|
+
return tags
|
|
1838
|
+
|
|
1839
|
+
@component.register("calendar")
|
|
1840
|
+
class Calendar(component.Component):
|
|
1841
|
+
template_name = "calendar/template.html"
|
|
1842
|
+
|
|
1843
|
+
class Media:
|
|
1844
|
+
css = "calendar/style.css"
|
|
1845
|
+
js = "calendar/script.js"
|
|
1846
|
+
|
|
1847
|
+
# Override the behavior of Media class
|
|
1848
|
+
media_class = MyMedia
|
|
1849
|
+
```
|
|
1850
|
+
|
|
1851
|
+
NOTE: The instance of the `Media` class (or it's subclass) is available under `Component.media` after the class creation (`__new__`).
|
|
1852
|
+
|
|
1853
|
+
## Rendering JS/CSS dependencies
|
|
1649
1854
|
|
|
1650
1855
|
The JS and CSS files included in components are not automatically rendered.
|
|
1651
1856
|
Instead, use the following tags to specify where to render the dependencies:
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "django_components"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.82"
|
|
8
8
|
requires-python = ">=3.8, <4.0"
|
|
9
9
|
description = "A way to create simple reusable template components in Django."
|
|
10
10
|
keywords = ["django", "components", "css", "js", "html"]
|