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.
Files changed (56) hide show
  1. {django_components-0.81/src/django_components.egg-info → django_components-0.83}/PKG-INFO +231 -11
  2. {django_components-0.81 → django_components-0.83}/README.md +230 -10
  3. {django_components-0.81 → django_components-0.83}/pyproject.toml +1 -1
  4. {django_components-0.81 → django_components-0.83}/src/django_components/attributes.py +7 -2
  5. {django_components-0.81 → django_components-0.83}/src/django_components/component.py +28 -140
  6. django_components-0.83/src/django_components/component_media.py +350 -0
  7. {django_components-0.81 → django_components-0.83}/src/django_components/context.py +1 -1
  8. {django_components-0.81 → django_components-0.83}/src/django_components/safer_staticfiles/apps.py +2 -0
  9. {django_components-0.81 → django_components-0.83}/src/django_components/slots.py +15 -1
  10. {django_components-0.81 → django_components-0.83/src/django_components.egg-info}/PKG-INFO +231 -11
  11. {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/SOURCES.txt +2 -0
  12. {django_components-0.81 → django_components-0.83}/tests/test_attributes.py +2 -0
  13. {django_components-0.81 → django_components-0.83}/tests/test_autodiscover.py +3 -1
  14. django_components-0.83/tests/test_component_media.py +868 -0
  15. django_components-0.83/tests/test_safer_staticfiles.py +103 -0
  16. {django_components-0.81 → django_components-0.83}/tests/test_templatetags_provide.py +41 -0
  17. {django_components-0.81 → django_components-0.83}/tests/test_templatetags_slot_fill.py +23 -23
  18. django_components-0.81/tests/test_component_media.py +0 -386
  19. {django_components-0.81 → django_components-0.83}/LICENSE +0 -0
  20. {django_components-0.81 → django_components-0.83}/setup.cfg +0 -0
  21. {django_components-0.81 → django_components-0.83}/src/django_components/__init__.py +0 -0
  22. {django_components-0.81 → django_components-0.83}/src/django_components/app_settings.py +0 -0
  23. {django_components-0.81 → django_components-0.83}/src/django_components/apps.py +0 -0
  24. {django_components-0.81 → django_components-0.83}/src/django_components/component_registry.py +0 -0
  25. {django_components-0.81 → django_components-0.83}/src/django_components/expression.py +0 -0
  26. {django_components-0.81 → django_components-0.83}/src/django_components/logger.py +0 -0
  27. {django_components-0.81 → django_components-0.83}/src/django_components/management/__init__.py +0 -0
  28. {django_components-0.81 → django_components-0.83}/src/django_components/management/commands/__init__.py +0 -0
  29. {django_components-0.81 → django_components-0.83}/src/django_components/management/commands/startcomponent.py +0 -0
  30. {django_components-0.81 → django_components-0.83}/src/django_components/management/commands/upgradecomponent.py +0 -0
  31. {django_components-0.81 → django_components-0.83}/src/django_components/middleware.py +0 -0
  32. {django_components-0.81 → django_components-0.83}/src/django_components/node.py +0 -0
  33. {django_components-0.81 → django_components-0.83}/src/django_components/provide.py +0 -0
  34. {django_components-0.81 → django_components-0.83}/src/django_components/py.typed +0 -0
  35. {django_components-0.81 → django_components-0.83}/src/django_components/safer_staticfiles/__init__.py +0 -0
  36. {django_components-0.81 → django_components-0.83}/src/django_components/template_loader.py +0 -0
  37. {django_components-0.81 → django_components-0.83}/src/django_components/template_parser.py +0 -0
  38. {django_components-0.81 → django_components-0.83}/src/django_components/templatetags/__init__.py +0 -0
  39. {django_components-0.81 → django_components-0.83}/src/django_components/templatetags/component_tags.py +0 -0
  40. {django_components-0.81 → django_components-0.83}/src/django_components/types.py +0 -0
  41. {django_components-0.81 → django_components-0.83}/src/django_components/utils.py +0 -0
  42. {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/dependency_links.txt +0 -0
  43. {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/requires.txt +0 -0
  44. {django_components-0.81 → django_components-0.83}/src/django_components.egg-info/top_level.txt +0 -0
  45. {django_components-0.81 → django_components-0.83}/tests/test_command_startcomponent.py +0 -0
  46. {django_components-0.81 → django_components-0.83}/tests/test_component.py +0 -0
  47. {django_components-0.81 → django_components-0.83}/tests/test_component_as_view.py +0 -0
  48. {django_components-0.81 → django_components-0.83}/tests/test_context.py +0 -0
  49. {django_components-0.81 → django_components-0.83}/tests/test_dependency_rendering.py +0 -0
  50. {django_components-0.81 → django_components-0.83}/tests/test_registry.py +0 -0
  51. {django_components-0.81 → django_components-0.83}/tests/test_settings.py +0 -0
  52. {django_components-0.81 → django_components-0.83}/tests/test_template_parser.py +0 -0
  53. {django_components-0.81 → django_components-0.83}/tests/test_templatetags.py +0 -0
  54. {django_components-0.81 → django_components-0.83}/tests/test_templatetags_component.py +0 -0
  55. {django_components-0.81 → django_components-0.83}/tests/test_templatetags_templating.py +0 -0
  56. {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.81
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
- Read on to learn about the details!
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 the component in a template](#use-the-component-in-a-template)
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
- - [Rendering JS and CSS dependencies](#rendering-js-and-css-dependencies)
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 will be automatically found. To customize which template to use based on context
290
- # you can override def get_template_name() instead of specifying the below variable.
291
- template_name = "calendar/template.html"
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 = "calendar/style.css"
301
- js = "calendar/script.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
- ## Rendering JS and CSS dependencies
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
- Read on to learn about the details!
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 the component in a template](#use-the-component-in-a-template)
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
- - [Rendering JS and CSS dependencies](#rendering-js-and-css-dependencies)
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 will be automatically found. To customize which template to use based on context
266
- # you can override def get_template_name() instead of specifying the below variable.
267
- template_name = "calendar/template.html"
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 = "calendar/style.css"
277
- js = "calendar/script.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
- ## Rendering JS and CSS dependencies
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.81"
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
- attrs = attrs_and_defaults_from_kwargs.get(HTML_ATTRS_ATTRS_KEY, {})
61
- default_attrs = attrs_and_defaults_from_kwargs.get(HTML_ATTRS_DEFAULTS_KEY, {})
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)