django-components 0.81__tar.gz → 0.83__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.83}/PKG-INFO +231 -11
- {django_components-0.81 → django_components-0.83}/README.md +230 -10
- {django_components-0.81 → django_components-0.83}/pyproject.toml +1 -1
- {django_components-0.81 → django_components-0.83}/src/django_components/attributes.py +7 -2
- {django_components-0.81 → django_components-0.83}/src/django_components/component.py +28 -140
- django_components-0.83/src/django_components/component_media.py +350 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/context.py +1 -1
- {django_components-0.81 → django_components-0.83}/src/django_components/safer_staticfiles/apps.py +2 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/slots.py +15 -1
- {django_components-0.81 → django_components-0.83/src/django_components.egg-info}/PKG-INFO +231 -11
- {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/SOURCES.txt +2 -0
- {django_components-0.81 → django_components-0.83}/tests/test_attributes.py +2 -0
- {django_components-0.81 → django_components-0.83}/tests/test_autodiscover.py +3 -1
- django_components-0.83/tests/test_component_media.py +868 -0
- django_components-0.83/tests/test_safer_staticfiles.py +103 -0
- {django_components-0.81 → django_components-0.83}/tests/test_templatetags_provide.py +41 -0
- {django_components-0.81 → django_components-0.83}/tests/test_templatetags_slot_fill.py +23 -23
- django_components-0.81/tests/test_component_media.py +0 -386
- {django_components-0.81 → django_components-0.83}/LICENSE +0 -0
- {django_components-0.81 → django_components-0.83}/setup.cfg +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/__init__.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/app_settings.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/apps.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/component_registry.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/expression.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/logger.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/management/__init__.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/middleware.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/node.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/provide.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/py.typed +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/template_loader.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/template_parser.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/templatetags/component_tags.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/types.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components/utils.py +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_command_startcomponent.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_component.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_component_as_view.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_context.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_registry.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_settings.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_template_parser.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_templatetags.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_templatetags_component.py +0 -0
- {django_components-0.81 → django_components-0.83}/tests/test_templatetags_templating.py +0 -0
- {django_components-0.81 → django_components-0.83}/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.83
|
|
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
|
|
@@ -40,7 +40,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
40
40
|
<div class="calendar-component">Today's date is <span>2015-06-19</span></div>
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
[See the example project](./sampleproject) or read on to learn about the details!
|
|
44
44
|
|
|
45
45
|
## Table of Contents
|
|
46
46
|
|
|
@@ -50,16 +50,17 @@ Read on to learn about the details!
|
|
|
50
50
|
- [Compatiblity](#compatiblity)
|
|
51
51
|
- [Create your first component](#create-your-first-component)
|
|
52
52
|
- [Using single-file components](#using-single-file-components)
|
|
53
|
-
- [Use
|
|
53
|
+
- [Use components in templates](#use-components-in-templates)
|
|
54
|
+
- [Use components outside of templates](#use-components-outside-of-templates)
|
|
54
55
|
- [Use components as views](#use-components-as-views)
|
|
55
|
-
- [Registering components](#registering-components)
|
|
56
56
|
- [Autodiscovery](#autodiscovery)
|
|
57
57
|
- [Using slots in templates](#using-slots-in-templates)
|
|
58
58
|
- [Passing data to components](#passing-data-to-components)
|
|
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)
|
|
@@ -141,6 +142,21 @@ INSTALLED_APPS = [
|
|
|
141
142
|
If you are on an older version of django-components, your alternatives are a) passing `--ignore <pattern>` options to the _collecstatic_ CLI command, or b) defining a subclass of StaticFilesConfig.
|
|
142
143
|
Both routes are described in the official [docs of the _staticfiles_ app](https://docs.djangoproject.com/en/4.2/ref/contrib/staticfiles/#customizing-the-ignored-pattern-list).
|
|
143
144
|
|
|
145
|
+
Note that `safer_staticfiles` excludes the `.py` and `.html` files for [collectstatic command](https://docs.djangoproject.com/en/5.0/ref/contrib/staticfiles/#collectstatic):
|
|
146
|
+
|
|
147
|
+
```sh
|
|
148
|
+
python manage.py collectstatic
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
but it is ignored on the [development server](https://docs.djangoproject.com/en/5.0/ref/django-admin/#runserver):
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
python manage.py runserver
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
For a step-by-step guide on deploying production server with static files,
|
|
158
|
+
[see the demo project](./sampleproject/README.md).
|
|
159
|
+
|
|
144
160
|
## Installation
|
|
145
161
|
|
|
146
162
|
Install the app into your environment:
|
|
@@ -286,9 +302,12 @@ from django_components import component
|
|
|
286
302
|
|
|
287
303
|
@component.register("calendar")
|
|
288
304
|
class Calendar(component.Component):
|
|
289
|
-
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
290
|
-
#
|
|
291
|
-
|
|
305
|
+
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
306
|
+
# will be automatically found. To customize which template to use based on context
|
|
307
|
+
# you can override method `get_template_name` instead of specifying `template_name`.
|
|
308
|
+
#
|
|
309
|
+
# `template_name` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
310
|
+
template_name = "template.html"
|
|
292
311
|
|
|
293
312
|
# This component takes one parameter, a date string to show in the template
|
|
294
313
|
def get_context_data(self, date):
|
|
@@ -296,9 +315,10 @@ class Calendar(component.Component):
|
|
|
296
315
|
"date": date,
|
|
297
316
|
}
|
|
298
317
|
|
|
318
|
+
# Both `css` and `js` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
299
319
|
class Media:
|
|
300
|
-
css = "
|
|
301
|
-
js = "
|
|
320
|
+
css = "style.css"
|
|
321
|
+
js = "script.js"
|
|
302
322
|
```
|
|
303
323
|
|
|
304
324
|
And voilá!! We've created our first component.
|
|
@@ -1669,7 +1689,207 @@ If you find yourself using the `only` modifier often, you can set the [context_b
|
|
|
1669
1689
|
|
|
1670
1690
|
Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
|
|
1671
1691
|
|
|
1672
|
-
##
|
|
1692
|
+
## Defining HTML/JS/CSS files
|
|
1693
|
+
|
|
1694
|
+
django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
|
|
1695
|
+
|
|
1696
|
+
To be familiar with how Django handles static files, we recommend reading also:
|
|
1697
|
+
- [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
|
|
1698
|
+
|
|
1699
|
+
### Defining file paths relative to component or static dirs
|
|
1700
|
+
|
|
1701
|
+
As seen in the [getting started example](#create-your-first-component), to associate HTML/JS/CSS
|
|
1702
|
+
files with a component, you set them as `template_name`, `Media.js` and `Media.css` respectively:
|
|
1703
|
+
|
|
1704
|
+
```py
|
|
1705
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1706
|
+
from django_components import component
|
|
1707
|
+
|
|
1708
|
+
@component.register("calendar")
|
|
1709
|
+
class Calendar(component.Component):
|
|
1710
|
+
template_name = "template.html"
|
|
1711
|
+
|
|
1712
|
+
class Media:
|
|
1713
|
+
css = "style.css"
|
|
1714
|
+
js = "script.js"
|
|
1715
|
+
```
|
|
1716
|
+
|
|
1717
|
+
In the example above, the files are defined relative to the directory where `component.py` is.
|
|
1718
|
+
|
|
1719
|
+
Alternatively, you can specify the file paths relative to the directories set in `STATICFILES_DIRS`.
|
|
1720
|
+
|
|
1721
|
+
Assuming that `STATICFILES_DIRS` contains path `[project root]/components`, we can rewrite the example as:
|
|
1722
|
+
|
|
1723
|
+
```py
|
|
1724
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1725
|
+
from django_components import component
|
|
1726
|
+
|
|
1727
|
+
@component.register("calendar")
|
|
1728
|
+
class Calendar(component.Component):
|
|
1729
|
+
template_name = "calendar/template.html"
|
|
1730
|
+
|
|
1731
|
+
class Media:
|
|
1732
|
+
css = "calendar/style.css"
|
|
1733
|
+
js = "calendar/script.js"
|
|
1734
|
+
```
|
|
1735
|
+
|
|
1736
|
+
NOTE: In case of conflict, the preference goes to resolving the files relative to the component's directory.
|
|
1737
|
+
|
|
1738
|
+
### Defining multiple paths
|
|
1739
|
+
|
|
1740
|
+
Each component can have only a single template. However, you can define as many JS or CSS files as you want using a list.
|
|
1741
|
+
|
|
1742
|
+
```py
|
|
1743
|
+
class MyComponent(component.Component):
|
|
1744
|
+
class Media:
|
|
1745
|
+
js = ["path/to/script1.js", "path/to/script2.js"]
|
|
1746
|
+
css = ["path/to/style1.css", "path/to/style2.css"]
|
|
1747
|
+
```
|
|
1748
|
+
|
|
1749
|
+
### Configuring CSS Media Types
|
|
1750
|
+
|
|
1751
|
+
You can define which stylesheets will be associated with which
|
|
1752
|
+
[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.
|
|
1753
|
+
|
|
1754
|
+
See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5.0/topics/forms/media/#css).
|
|
1755
|
+
|
|
1756
|
+
Again, you can set either a single file or a list of files per media type:
|
|
1757
|
+
|
|
1758
|
+
```py
|
|
1759
|
+
class MyComponent(component.Component):
|
|
1760
|
+
class Media:
|
|
1761
|
+
css = {
|
|
1762
|
+
"all": "path/to/style1.css",
|
|
1763
|
+
"print": "path/to/style2.css",
|
|
1764
|
+
}
|
|
1765
|
+
```
|
|
1766
|
+
|
|
1767
|
+
```py
|
|
1768
|
+
class MyComponent(component.Component):
|
|
1769
|
+
class Media:
|
|
1770
|
+
css = {
|
|
1771
|
+
"all": ["path/to/style1.css", "path/to/style2.css"],
|
|
1772
|
+
"print": ["path/to/style3.css", "path/to/style4.css"],
|
|
1773
|
+
}
|
|
1774
|
+
```
|
|
1775
|
+
|
|
1776
|
+
NOTE: When you define CSS as a string or a list, the `all` media type is implied.
|
|
1777
|
+
|
|
1778
|
+
|
|
1779
|
+
### Supported types for file paths
|
|
1780
|
+
|
|
1781
|
+
File paths can be any of:
|
|
1782
|
+
- `str`
|
|
1783
|
+
- `bytes`
|
|
1784
|
+
- `PathLike` (`__fspath__` method)
|
|
1785
|
+
- `SafeData` (`__html__` method)
|
|
1786
|
+
- `Callable` that returns any of the above, evaluated at class creation (`__new__`)
|
|
1787
|
+
|
|
1788
|
+
```py
|
|
1789
|
+
from pathlib import Path
|
|
1790
|
+
|
|
1791
|
+
from django.utils.safestring import mark_safe
|
|
1792
|
+
|
|
1793
|
+
class SimpleComponent(component.Component):
|
|
1794
|
+
class Media:
|
|
1795
|
+
css = [
|
|
1796
|
+
mark_safe('<link href="/static/calendar/style.css" rel="stylesheet" />'),
|
|
1797
|
+
Path("calendar/style1.css"),
|
|
1798
|
+
"calendar/style2.css",
|
|
1799
|
+
b"calendar/style3.css",
|
|
1800
|
+
lambda: "calendar/style4.css",
|
|
1801
|
+
]
|
|
1802
|
+
js = [
|
|
1803
|
+
mark_safe('<script src="/static/calendar/script.js"></script>'),
|
|
1804
|
+
Path("calendar/script1.js"),
|
|
1805
|
+
"calendar/script2.js",
|
|
1806
|
+
b"calendar/script3.js",
|
|
1807
|
+
lambda: "calendar/script4.js",
|
|
1808
|
+
]
|
|
1809
|
+
```
|
|
1810
|
+
|
|
1811
|
+
### Path as objects
|
|
1812
|
+
|
|
1813
|
+
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.
|
|
1814
|
+
|
|
1815
|
+
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.
|
|
1816
|
+
|
|
1817
|
+
Because of that, the paths defined as "safe" strings are NEVER resolved, neither relative to component's directory, nor relative to `STATICFILES_DIRS`.
|
|
1818
|
+
|
|
1819
|
+
"Safe" strings can be used to lazily resolve a path, or to customize the `<script>` or `<link>` tag for individual paths:
|
|
1820
|
+
|
|
1821
|
+
```py
|
|
1822
|
+
class LazyJsPath:
|
|
1823
|
+
def __init__(self, static_path: str) -> None:
|
|
1824
|
+
self.static_path = static_path
|
|
1825
|
+
|
|
1826
|
+
def __html__(self):
|
|
1827
|
+
full_path = static(self.static_path)
|
|
1828
|
+
return format_html(
|
|
1829
|
+
f'<script type="module" src="{full_path}"></script>'
|
|
1830
|
+
)
|
|
1831
|
+
|
|
1832
|
+
@component.register("calendar")
|
|
1833
|
+
class Calendar(component.Component):
|
|
1834
|
+
template_name = "calendar/template.html"
|
|
1835
|
+
|
|
1836
|
+
def get_context_data(self, date):
|
|
1837
|
+
return {
|
|
1838
|
+
"date": date,
|
|
1839
|
+
}
|
|
1840
|
+
|
|
1841
|
+
class Media:
|
|
1842
|
+
css = "calendar/style.css"
|
|
1843
|
+
js = [
|
|
1844
|
+
# <script> tag constructed by Media class
|
|
1845
|
+
"calendar/script1.js",
|
|
1846
|
+
# Custom <script> tag
|
|
1847
|
+
LazyJsPath("calendar/script2.js"),
|
|
1848
|
+
]
|
|
1849
|
+
```
|
|
1850
|
+
|
|
1851
|
+
### Customize how paths are rendered into HTML tags with `media_class`
|
|
1852
|
+
|
|
1853
|
+
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.
|
|
1854
|
+
|
|
1855
|
+
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.
|
|
1856
|
+
|
|
1857
|
+
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):
|
|
1858
|
+
|
|
1859
|
+
```py
|
|
1860
|
+
from django.forms.widgets import Media
|
|
1861
|
+
from django_components import component
|
|
1862
|
+
|
|
1863
|
+
class MyMedia(Media):
|
|
1864
|
+
# Same as original Media.render_js, except
|
|
1865
|
+
# the `<script>` tag has also `type="module"`
|
|
1866
|
+
def render_js(self):
|
|
1867
|
+
tags = []
|
|
1868
|
+
for path in self._js:
|
|
1869
|
+
if hasattr(path, "__html__"):
|
|
1870
|
+
tag = path.__html__()
|
|
1871
|
+
else:
|
|
1872
|
+
tag = format_html(
|
|
1873
|
+
'<script type="module" src="{}"></script>',
|
|
1874
|
+
self.absolute_path(path)
|
|
1875
|
+
)
|
|
1876
|
+
return tags
|
|
1877
|
+
|
|
1878
|
+
@component.register("calendar")
|
|
1879
|
+
class Calendar(component.Component):
|
|
1880
|
+
template_name = "calendar/template.html"
|
|
1881
|
+
|
|
1882
|
+
class Media:
|
|
1883
|
+
css = "calendar/style.css"
|
|
1884
|
+
js = "calendar/script.js"
|
|
1885
|
+
|
|
1886
|
+
# Override the behavior of Media class
|
|
1887
|
+
media_class = MyMedia
|
|
1888
|
+
```
|
|
1889
|
+
|
|
1890
|
+
NOTE: The instance of the `Media` class (or it's subclass) is available under `Component.media` after the class creation (`__new__`).
|
|
1891
|
+
|
|
1892
|
+
## Rendering JS/CSS dependencies
|
|
1673
1893
|
|
|
1674
1894
|
The JS and CSS files included in components are not automatically rendered.
|
|
1675
1895
|
Instead, use the following tags to specify where to render the dependencies:
|
|
@@ -16,7 +16,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
16
16
|
<div class="calendar-component">Today's date is <span>2015-06-19</span></div>
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
[See the example project](./sampleproject) or read on to learn about the details!
|
|
20
20
|
|
|
21
21
|
## Table of Contents
|
|
22
22
|
|
|
@@ -26,16 +26,17 @@ Read on to learn about the details!
|
|
|
26
26
|
- [Compatiblity](#compatiblity)
|
|
27
27
|
- [Create your first component](#create-your-first-component)
|
|
28
28
|
- [Using single-file components](#using-single-file-components)
|
|
29
|
-
- [Use
|
|
29
|
+
- [Use components in templates](#use-components-in-templates)
|
|
30
|
+
- [Use components outside of templates](#use-components-outside-of-templates)
|
|
30
31
|
- [Use components as views](#use-components-as-views)
|
|
31
|
-
- [Registering components](#registering-components)
|
|
32
32
|
- [Autodiscovery](#autodiscovery)
|
|
33
33
|
- [Using slots in templates](#using-slots-in-templates)
|
|
34
34
|
- [Passing data to components](#passing-data-to-components)
|
|
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)
|
|
@@ -117,6 +118,21 @@ INSTALLED_APPS = [
|
|
|
117
118
|
If you are on an older version of django-components, your alternatives are a) passing `--ignore <pattern>` options to the _collecstatic_ CLI command, or b) defining a subclass of StaticFilesConfig.
|
|
118
119
|
Both routes are described in the official [docs of the _staticfiles_ app](https://docs.djangoproject.com/en/4.2/ref/contrib/staticfiles/#customizing-the-ignored-pattern-list).
|
|
119
120
|
|
|
121
|
+
Note that `safer_staticfiles` excludes the `.py` and `.html` files for [collectstatic command](https://docs.djangoproject.com/en/5.0/ref/contrib/staticfiles/#collectstatic):
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
python manage.py collectstatic
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
but it is ignored on the [development server](https://docs.djangoproject.com/en/5.0/ref/django-admin/#runserver):
|
|
128
|
+
|
|
129
|
+
```sh
|
|
130
|
+
python manage.py runserver
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
For a step-by-step guide on deploying production server with static files,
|
|
134
|
+
[see the demo project](./sampleproject/README.md).
|
|
135
|
+
|
|
120
136
|
## Installation
|
|
121
137
|
|
|
122
138
|
Install the app into your environment:
|
|
@@ -262,9 +278,12 @@ from django_components import component
|
|
|
262
278
|
|
|
263
279
|
@component.register("calendar")
|
|
264
280
|
class Calendar(component.Component):
|
|
265
|
-
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
266
|
-
#
|
|
267
|
-
|
|
281
|
+
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
282
|
+
# will be automatically found. To customize which template to use based on context
|
|
283
|
+
# you can override method `get_template_name` instead of specifying `template_name`.
|
|
284
|
+
#
|
|
285
|
+
# `template_name` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
286
|
+
template_name = "template.html"
|
|
268
287
|
|
|
269
288
|
# This component takes one parameter, a date string to show in the template
|
|
270
289
|
def get_context_data(self, date):
|
|
@@ -272,9 +291,10 @@ class Calendar(component.Component):
|
|
|
272
291
|
"date": date,
|
|
273
292
|
}
|
|
274
293
|
|
|
294
|
+
# Both `css` and `js` can be relative to dir where `calendar.py` is, or relative to STATICFILES_DIRS
|
|
275
295
|
class Media:
|
|
276
|
-
css = "
|
|
277
|
-
js = "
|
|
296
|
+
css = "style.css"
|
|
297
|
+
js = "script.js"
|
|
278
298
|
```
|
|
279
299
|
|
|
280
300
|
And voilá!! We've created our first component.
|
|
@@ -1645,7 +1665,207 @@ If you find yourself using the `only` modifier often, you can set the [context_b
|
|
|
1645
1665
|
|
|
1646
1666
|
Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
|
|
1647
1667
|
|
|
1648
|
-
##
|
|
1668
|
+
## Defining HTML/JS/CSS files
|
|
1669
|
+
|
|
1670
|
+
django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
|
|
1671
|
+
|
|
1672
|
+
To be familiar with how Django handles static files, we recommend reading also:
|
|
1673
|
+
- [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
|
|
1674
|
+
|
|
1675
|
+
### Defining file paths relative to component or static dirs
|
|
1676
|
+
|
|
1677
|
+
As seen in the [getting started example](#create-your-first-component), to associate HTML/JS/CSS
|
|
1678
|
+
files with a component, you set them as `template_name`, `Media.js` and `Media.css` respectively:
|
|
1679
|
+
|
|
1680
|
+
```py
|
|
1681
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1682
|
+
from django_components import component
|
|
1683
|
+
|
|
1684
|
+
@component.register("calendar")
|
|
1685
|
+
class Calendar(component.Component):
|
|
1686
|
+
template_name = "template.html"
|
|
1687
|
+
|
|
1688
|
+
class Media:
|
|
1689
|
+
css = "style.css"
|
|
1690
|
+
js = "script.js"
|
|
1691
|
+
```
|
|
1692
|
+
|
|
1693
|
+
In the example above, the files are defined relative to the directory where `component.py` is.
|
|
1694
|
+
|
|
1695
|
+
Alternatively, you can specify the file paths relative to the directories set in `STATICFILES_DIRS`.
|
|
1696
|
+
|
|
1697
|
+
Assuming that `STATICFILES_DIRS` contains path `[project root]/components`, we can rewrite the example as:
|
|
1698
|
+
|
|
1699
|
+
```py
|
|
1700
|
+
# In a file [project root]/components/calendar/calendar.py
|
|
1701
|
+
from django_components import component
|
|
1702
|
+
|
|
1703
|
+
@component.register("calendar")
|
|
1704
|
+
class Calendar(component.Component):
|
|
1705
|
+
template_name = "calendar/template.html"
|
|
1706
|
+
|
|
1707
|
+
class Media:
|
|
1708
|
+
css = "calendar/style.css"
|
|
1709
|
+
js = "calendar/script.js"
|
|
1710
|
+
```
|
|
1711
|
+
|
|
1712
|
+
NOTE: In case of conflict, the preference goes to resolving the files relative to the component's directory.
|
|
1713
|
+
|
|
1714
|
+
### Defining multiple paths
|
|
1715
|
+
|
|
1716
|
+
Each component can have only a single template. However, you can define as many JS or CSS files as you want using a list.
|
|
1717
|
+
|
|
1718
|
+
```py
|
|
1719
|
+
class MyComponent(component.Component):
|
|
1720
|
+
class Media:
|
|
1721
|
+
js = ["path/to/script1.js", "path/to/script2.js"]
|
|
1722
|
+
css = ["path/to/style1.css", "path/to/style2.css"]
|
|
1723
|
+
```
|
|
1724
|
+
|
|
1725
|
+
### Configuring CSS Media Types
|
|
1726
|
+
|
|
1727
|
+
You can define which stylesheets will be associated with which
|
|
1728
|
+
[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.
|
|
1729
|
+
|
|
1730
|
+
See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5.0/topics/forms/media/#css).
|
|
1731
|
+
|
|
1732
|
+
Again, you can set either a single file or a list of files per media type:
|
|
1733
|
+
|
|
1734
|
+
```py
|
|
1735
|
+
class MyComponent(component.Component):
|
|
1736
|
+
class Media:
|
|
1737
|
+
css = {
|
|
1738
|
+
"all": "path/to/style1.css",
|
|
1739
|
+
"print": "path/to/style2.css",
|
|
1740
|
+
}
|
|
1741
|
+
```
|
|
1742
|
+
|
|
1743
|
+
```py
|
|
1744
|
+
class MyComponent(component.Component):
|
|
1745
|
+
class Media:
|
|
1746
|
+
css = {
|
|
1747
|
+
"all": ["path/to/style1.css", "path/to/style2.css"],
|
|
1748
|
+
"print": ["path/to/style3.css", "path/to/style4.css"],
|
|
1749
|
+
}
|
|
1750
|
+
```
|
|
1751
|
+
|
|
1752
|
+
NOTE: When you define CSS as a string or a list, the `all` media type is implied.
|
|
1753
|
+
|
|
1754
|
+
|
|
1755
|
+
### Supported types for file paths
|
|
1756
|
+
|
|
1757
|
+
File paths can be any of:
|
|
1758
|
+
- `str`
|
|
1759
|
+
- `bytes`
|
|
1760
|
+
- `PathLike` (`__fspath__` method)
|
|
1761
|
+
- `SafeData` (`__html__` method)
|
|
1762
|
+
- `Callable` that returns any of the above, evaluated at class creation (`__new__`)
|
|
1763
|
+
|
|
1764
|
+
```py
|
|
1765
|
+
from pathlib import Path
|
|
1766
|
+
|
|
1767
|
+
from django.utils.safestring import mark_safe
|
|
1768
|
+
|
|
1769
|
+
class SimpleComponent(component.Component):
|
|
1770
|
+
class Media:
|
|
1771
|
+
css = [
|
|
1772
|
+
mark_safe('<link href="/static/calendar/style.css" rel="stylesheet" />'),
|
|
1773
|
+
Path("calendar/style1.css"),
|
|
1774
|
+
"calendar/style2.css",
|
|
1775
|
+
b"calendar/style3.css",
|
|
1776
|
+
lambda: "calendar/style4.css",
|
|
1777
|
+
]
|
|
1778
|
+
js = [
|
|
1779
|
+
mark_safe('<script src="/static/calendar/script.js"></script>'),
|
|
1780
|
+
Path("calendar/script1.js"),
|
|
1781
|
+
"calendar/script2.js",
|
|
1782
|
+
b"calendar/script3.js",
|
|
1783
|
+
lambda: "calendar/script4.js",
|
|
1784
|
+
]
|
|
1785
|
+
```
|
|
1786
|
+
|
|
1787
|
+
### Path as objects
|
|
1788
|
+
|
|
1789
|
+
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.
|
|
1790
|
+
|
|
1791
|
+
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.
|
|
1792
|
+
|
|
1793
|
+
Because of that, the paths defined as "safe" strings are NEVER resolved, neither relative to component's directory, nor relative to `STATICFILES_DIRS`.
|
|
1794
|
+
|
|
1795
|
+
"Safe" strings can be used to lazily resolve a path, or to customize the `<script>` or `<link>` tag for individual paths:
|
|
1796
|
+
|
|
1797
|
+
```py
|
|
1798
|
+
class LazyJsPath:
|
|
1799
|
+
def __init__(self, static_path: str) -> None:
|
|
1800
|
+
self.static_path = static_path
|
|
1801
|
+
|
|
1802
|
+
def __html__(self):
|
|
1803
|
+
full_path = static(self.static_path)
|
|
1804
|
+
return format_html(
|
|
1805
|
+
f'<script type="module" src="{full_path}"></script>'
|
|
1806
|
+
)
|
|
1807
|
+
|
|
1808
|
+
@component.register("calendar")
|
|
1809
|
+
class Calendar(component.Component):
|
|
1810
|
+
template_name = "calendar/template.html"
|
|
1811
|
+
|
|
1812
|
+
def get_context_data(self, date):
|
|
1813
|
+
return {
|
|
1814
|
+
"date": date,
|
|
1815
|
+
}
|
|
1816
|
+
|
|
1817
|
+
class Media:
|
|
1818
|
+
css = "calendar/style.css"
|
|
1819
|
+
js = [
|
|
1820
|
+
# <script> tag constructed by Media class
|
|
1821
|
+
"calendar/script1.js",
|
|
1822
|
+
# Custom <script> tag
|
|
1823
|
+
LazyJsPath("calendar/script2.js"),
|
|
1824
|
+
]
|
|
1825
|
+
```
|
|
1826
|
+
|
|
1827
|
+
### Customize how paths are rendered into HTML tags with `media_class`
|
|
1828
|
+
|
|
1829
|
+
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.
|
|
1830
|
+
|
|
1831
|
+
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.
|
|
1832
|
+
|
|
1833
|
+
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):
|
|
1834
|
+
|
|
1835
|
+
```py
|
|
1836
|
+
from django.forms.widgets import Media
|
|
1837
|
+
from django_components import component
|
|
1838
|
+
|
|
1839
|
+
class MyMedia(Media):
|
|
1840
|
+
# Same as original Media.render_js, except
|
|
1841
|
+
# the `<script>` tag has also `type="module"`
|
|
1842
|
+
def render_js(self):
|
|
1843
|
+
tags = []
|
|
1844
|
+
for path in self._js:
|
|
1845
|
+
if hasattr(path, "__html__"):
|
|
1846
|
+
tag = path.__html__()
|
|
1847
|
+
else:
|
|
1848
|
+
tag = format_html(
|
|
1849
|
+
'<script type="module" src="{}"></script>',
|
|
1850
|
+
self.absolute_path(path)
|
|
1851
|
+
)
|
|
1852
|
+
return tags
|
|
1853
|
+
|
|
1854
|
+
@component.register("calendar")
|
|
1855
|
+
class Calendar(component.Component):
|
|
1856
|
+
template_name = "calendar/template.html"
|
|
1857
|
+
|
|
1858
|
+
class Media:
|
|
1859
|
+
css = "calendar/style.css"
|
|
1860
|
+
js = "calendar/script.js"
|
|
1861
|
+
|
|
1862
|
+
# Override the behavior of Media class
|
|
1863
|
+
media_class = MyMedia
|
|
1864
|
+
```
|
|
1865
|
+
|
|
1866
|
+
NOTE: The instance of the `Media` class (or it's subclass) is available under `Component.media` after the class creation (`__new__`).
|
|
1867
|
+
|
|
1868
|
+
## Rendering JS/CSS dependencies
|
|
1649
1869
|
|
|
1650
1870
|
The JS and CSS files included in components are not automatically rendered.
|
|
1651
1871
|
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.83"
|
|
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"]
|
|
@@ -15,6 +15,10 @@ HTML_ATTRS_DEFAULTS_KEY = "defaults"
|
|
|
15
15
|
HTML_ATTRS_ATTRS_KEY = "attrs"
|
|
16
16
|
|
|
17
17
|
|
|
18
|
+
def _default(val: Any, default_val: Any) -> Any:
|
|
19
|
+
return val if val is not None else default_val
|
|
20
|
+
|
|
21
|
+
|
|
18
22
|
class HtmlAttrsNode(Node):
|
|
19
23
|
def __init__(
|
|
20
24
|
self,
|
|
@@ -57,8 +61,9 @@ class HtmlAttrsNode(Node):
|
|
|
57
61
|
attrs_and_defaults_from_kwargs = process_aggregate_kwargs(attrs_and_defaults_from_kwargs)
|
|
58
62
|
|
|
59
63
|
# NOTE: We want to allow to use `html_attrs` even without `attrs` or `defaults` params
|
|
60
|
-
|
|
61
|
-
|
|
64
|
+
# Or when they are None
|
|
65
|
+
attrs = _default(attrs_and_defaults_from_kwargs.get(HTML_ATTRS_ATTRS_KEY, None), {})
|
|
66
|
+
default_attrs = _default(attrs_and_defaults_from_kwargs.get(HTML_ATTRS_DEFAULTS_KEY, None), {})
|
|
62
67
|
|
|
63
68
|
final_attrs = {**default_attrs, **attrs}
|
|
64
69
|
final_attrs = append_attributes(*final_attrs.items(), *append_attrs)
|