django-components 0.85__tar.gz → 0.87__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 (59) hide show
  1. {django_components-0.85/src/django_components.egg-info → django_components-0.87}/PKG-INFO +132 -131
  2. {django_components-0.85 → django_components-0.87}/README.md +131 -130
  3. {django_components-0.85 → django_components-0.87}/pyproject.toml +1 -1
  4. django_components-0.87/src/django_components/__init__.py +19 -0
  5. {django_components-0.85 → django_components-0.87}/src/django_components/component.py +15 -12
  6. {django_components-0.85 → django_components-0.87}/src/django_components/component_media.py +7 -7
  7. {django_components-0.85 → django_components-0.87}/src/django_components/management/commands/startcomponent.py +3 -3
  8. django_components-0.87/src/django_components/management/commands/upgradecomponent.py +69 -0
  9. {django_components-0.85 → django_components-0.87/src/django_components.egg-info}/PKG-INFO +132 -131
  10. {django_components-0.85 → django_components-0.87}/tests/test_attributes.py +23 -23
  11. {django_components-0.85 → django_components-0.87}/tests/test_autodiscover.py +13 -13
  12. {django_components-0.85 → django_components-0.87}/tests/test_component.py +21 -21
  13. {django_components-0.85 → django_components-0.87}/tests/test_component_as_view.py +9 -9
  14. {django_components-0.85 → django_components-0.87}/tests/test_component_media.py +35 -35
  15. {django_components-0.85 → django_components-0.87}/tests/test_context.py +26 -26
  16. {django_components-0.85 → django_components-0.87}/tests/test_dependency_rendering.py +37 -37
  17. {django_components-0.85 → django_components-0.87}/tests/test_registry.py +11 -11
  18. {django_components-0.85 → django_components-0.87}/tests/test_template_parser.py +3 -3
  19. {django_components-0.85 → django_components-0.87}/tests/test_templatetags.py +38 -38
  20. {django_components-0.85 → django_components-0.87}/tests/test_templatetags_component.py +26 -26
  21. {django_components-0.85 → django_components-0.87}/tests/test_templatetags_provide.py +45 -45
  22. {django_components-0.85 → django_components-0.87}/tests/test_templatetags_slot_fill.py +69 -69
  23. {django_components-0.85 → django_components-0.87}/tests/test_templatetags_templating.py +38 -38
  24. django_components-0.85/src/django_components/__init__.py +0 -7
  25. django_components-0.85/src/django_components/management/commands/upgradecomponent.py +0 -66
  26. {django_components-0.85 → django_components-0.87}/LICENSE +0 -0
  27. {django_components-0.85 → django_components-0.87}/setup.cfg +0 -0
  28. {django_components-0.85 → django_components-0.87}/src/django_components/app_settings.py +0 -0
  29. {django_components-0.85 → django_components-0.87}/src/django_components/apps.py +0 -0
  30. {django_components-0.85 → django_components-0.87}/src/django_components/attributes.py +0 -0
  31. {django_components-0.85 → django_components-0.87}/src/django_components/autodiscover.py +0 -0
  32. {django_components-0.85 → django_components-0.87}/src/django_components/component_registry.py +0 -0
  33. {django_components-0.85 → django_components-0.87}/src/django_components/context.py +0 -0
  34. {django_components-0.85 → django_components-0.87}/src/django_components/expression.py +0 -0
  35. {django_components-0.85 → django_components-0.87}/src/django_components/logger.py +0 -0
  36. {django_components-0.85 → django_components-0.87}/src/django_components/management/__init__.py +0 -0
  37. {django_components-0.85 → django_components-0.87}/src/django_components/management/commands/__init__.py +0 -0
  38. {django_components-0.85 → django_components-0.87}/src/django_components/middleware.py +0 -0
  39. {django_components-0.85 → django_components-0.87}/src/django_components/node.py +0 -0
  40. {django_components-0.85 → django_components-0.87}/src/django_components/provide.py +0 -0
  41. {django_components-0.85 → django_components-0.87}/src/django_components/py.typed +0 -0
  42. {django_components-0.85 → django_components-0.87}/src/django_components/safer_staticfiles/__init__.py +0 -0
  43. {django_components-0.85 → django_components-0.87}/src/django_components/safer_staticfiles/apps.py +0 -0
  44. {django_components-0.85 → django_components-0.87}/src/django_components/slots.py +0 -0
  45. {django_components-0.85 → django_components-0.87}/src/django_components/template_loader.py +0 -0
  46. {django_components-0.85 → django_components-0.87}/src/django_components/template_parser.py +0 -0
  47. {django_components-0.85 → django_components-0.87}/src/django_components/templatetags/__init__.py +0 -0
  48. {django_components-0.85 → django_components-0.87}/src/django_components/templatetags/component_tags.py +0 -0
  49. {django_components-0.85 → django_components-0.87}/src/django_components/types.py +0 -0
  50. {django_components-0.85 → django_components-0.87}/src/django_components/utils.py +0 -0
  51. {django_components-0.85 → django_components-0.87}/src/django_components.egg-info/SOURCES.txt +0 -0
  52. {django_components-0.85 → django_components-0.87}/src/django_components.egg-info/dependency_links.txt +0 -0
  53. {django_components-0.85 → django_components-0.87}/src/django_components.egg-info/requires.txt +0 -0
  54. {django_components-0.85 → django_components-0.87}/src/django_components.egg-info/top_level.txt +0 -0
  55. {django_components-0.85 → django_components-0.87}/tests/test_command_startcomponent.py +0 -0
  56. {django_components-0.85 → django_components-0.87}/tests/test_safer_staticfiles.py +0 -0
  57. {django_components-0.85 → django_components-0.87}/tests/test_settings.py +0 -0
  58. {django_components-0.85 → django_components-0.87}/tests/test_template_loader.py +0 -0
  59. {django_components-0.85 → django_components-0.87}/tests/testutils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.85
3
+ Version: 0.87
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
@@ -23,6 +23,7 @@ License-File: LICENSE
23
23
  Requires-Dist: Django>=4.2
24
24
 
25
25
  # <img src="logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
26
+
26
27
  <a href="https://github.com/EmilStenstrom/django-components/actions?query=workflow%3A%22Run+tests%22"><img align="right" src="https://github.com/EmilStenstrom/django-components/workflows/Run%20tests/badge.svg" alt="Show test status"></a>
27
28
  <a href="https://pepy.tech/project/django-components"><img align="right" src="https://pepy.tech/badge/django-components" alt="Show download stats"></a>
28
29
 
@@ -71,11 +72,12 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
71
72
  ## Release notes
72
73
 
73
74
  🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
75
+
74
76
  - Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
75
- - To migrate from:
76
- - `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
77
- or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
78
- - `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
77
+ - To migrate from:
78
+ - `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
79
+ or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
80
+ - `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
79
81
  - Previously, autodiscovery handled relative files in `STATICFILES_DIRS`. To align with Django, `STATICFILES_DIRS` now must be full paths ([Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#std-setting-STATICFILES_DIRS)).
80
82
 
81
83
  🚨📢 **Version 0.81** Aligned the `render_to_response` method with the (now public) `render` method of `Component` class. Moreover, slots passed to these can now be rendered also as functions.
@@ -88,12 +90,12 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
88
90
 
89
91
  - BREAKING CHANGE: Default value for the `COMPONENTS.context_behavior` setting was changes from `"isolated"` to `"django"`. If you did not set this value explicitly before, this may be a breaking change. See the rationale for change [here](https://github.com/EmilStenstrom/django-components/issues/498).
90
92
 
91
-
92
93
  🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
94
+
93
95
  - Previously, the syntax was
94
- `{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
96
+ `{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
95
97
  - Now, the syntax is
96
- `{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
98
+ `{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
97
99
 
98
100
  **Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
99
101
 
@@ -104,7 +106,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
104
106
 
105
107
  **Version 0.67** CHANGED the default way how context variables are resolved in slots. See the [documentation](https://github.com/EmilStenstrom/django-components/tree/0.67#isolate-components-slots) for more details.
106
108
 
107
- 🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of components to the new syntax automatically.
109
+ 🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of templates that use components to the new syntax automatically.
108
110
 
109
111
  This change is done to simplify the API in anticipation of a 1.0 release of django_components. After 1.0 we intend to be stricter with big changes like this in point releases.
110
112
 
@@ -112,7 +114,7 @@ This change is done to simplify the API in anticipation of a 1.0 release of djan
112
114
 
113
115
  **Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags.
114
116
 
115
- **Version 0.27** adds a second installable app: *django_components.safer_staticfiles*. It provides the same behavior as *django.contrib.staticfiles* but with extra security guarantees (more info below in Security Notes).
117
+ **Version 0.27** adds a second installable app: _django_components.safer_staticfiles_. It provides the same behavior as _django.contrib.staticfiles_ but with extra security guarantees (more info below in Security Notes).
116
118
 
117
119
  **Version 0.26** changes the syntax for `{% slot %}` tags. From now on, we separate defining a slot (`{% slot %}`) from filling a slot with content (`{% fill %}`). This means you will likely need to change a lot of slot tags to fill. We understand this is annoying, but it's the only way we can get support for nested slots that fill in other slots, which is a very nice featuPpre to have access to. Hoping that this will feel worth it!
118
120
 
@@ -122,7 +124,7 @@ This change is done to simplify the API in anticipation of a 1.0 release of djan
122
124
 
123
125
  ## Security notes 🚨
124
126
 
125
- *You are advised to read this section before using django-components in production.*
127
+ _You are advised to read this section before using django-components in production._
126
128
 
127
129
  ### Static files
128
130
 
@@ -132,12 +134,12 @@ This means that files containing backend logic, such as Python modules and HTML
132
134
 
133
135
  If your are using _django.contrib.staticfiles_ to collect static files, no distinction is made between the different kinds of files.
134
136
  As a result, your Python code and templates may inadvertently become available on your static file server.
135
- You probably don't want this, as parts of your backend logic will be exposed, posing a __potential security vulnerability__.
137
+ You probably don't want this, as parts of your backend logic will be exposed, posing a **potential security vulnerability**.
136
138
 
137
- As of *v0.27*, django-components ships with an additional installable app *django_components.__safer_staticfiles__*.
138
- It is a drop-in replacement for *django.contrib.staticfiles*.
139
+ As of _v0.27_, django-components ships with an additional installable app _django_components.**safer_staticfiles**_.
140
+ It is a drop-in replacement for _django.contrib.staticfiles_.
139
141
  Its behavior is 100% identical except it ignores .py and .html files, meaning these will not end up on your static files server.
140
- To use it, add it to INSTALLED_APPS and remove _django.contrib.staticfiles_.
142
+ To use it, add it to INSTALLED*APPS and remove \_django.contrib.staticfiles*.
141
143
 
142
144
  ```python
143
145
  INSTALLED_APPS = [
@@ -187,7 +189,8 @@ For a step-by-step guide on deploying production server with static files,
187
189
  ```
188
190
 
189
191
  4. Modify `TEMPLATES` section of settings.py as follows:
190
- - *Remove `'APP_DIRS': True,`*
192
+
193
+ - _Remove `'APP_DIRS': True,`_
191
194
  - Add `loaders` to `OPTIONS` list and set it to following value:
192
195
 
193
196
  ```python
@@ -250,13 +253,13 @@ Read on to find out how to build your first component!
250
253
 
251
254
  Django-components supports all supported combinations versions of [Django](https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django) and [Python](https://devguide.python.org/versions/#versions).
252
255
 
253
- | Python version | Django version |
254
- |----------------|--------------------------|
255
- | 3.8 | 4.2 |
256
- | 3.9 | 4.2 |
257
- | 3.10 | 4.2, 5.0 |
258
- | 3.11 | 4.2, 5.0 |
259
- | 3.12 | 4.2, 5.0 |
256
+ | Python version | Django version |
257
+ | -------------- | -------------- |
258
+ | 3.8 | 4.2 |
259
+ | 3.9 | 4.2 |
260
+ | 3.10 | 4.2, 5.0 |
261
+ | 3.11 | 4.2, 5.0 |
262
+ | 3.12 | 4.2, 5.0 |
260
263
 
261
264
  ## Create your first component
262
265
 
@@ -317,10 +320,10 @@ Inside this file we create a Component by inheriting from the Component class an
317
320
 
318
321
  ```python
319
322
  # In a file called [project root]/components/calendar/calendar.py
320
- from django_components import component
323
+ from django_components import Component, register
321
324
 
322
- @component.register("calendar")
323
- class Calendar(component.Component):
325
+ @register("calendar")
326
+ class Calendar(Component):
324
327
  # Templates inside `[your apps]/components` dir and `[project root]/components` dir
325
328
  # will be automatically found. To customize which template to use based on context
326
329
  # you can override method `get_template_name` instead of specifying `template_name`.
@@ -348,26 +351,25 @@ Components can also be defined in a single file, which is useful for small compo
348
351
 
349
352
  ```python
350
353
  # In a file called [project root]/components/calendar.py
351
- from django_components import component
352
- from django_components import types as t
354
+ from django_components import Component, register, types
353
355
 
354
- @component.register("calendar")
355
- class Calendar(component.Component):
356
+ @register("calendar")
357
+ class Calendar(Component):
356
358
  def get_context_data(self, date):
357
359
  return {
358
360
  "date": date,
359
361
  }
360
362
 
361
- template: t.django_html = """
363
+ template: types.django_html = """
362
364
  <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
363
365
  """
364
366
 
365
- css: t.css = """
367
+ css: types.css = """
366
368
  .calendar-component { width: 200px; background: pink; }
367
369
  .calendar-component span { font-weight: bold; }
368
370
  """
369
371
 
370
- js: t.js = """
372
+ js: types.js = """
371
373
  (function(){
372
374
  if (document.querySelector(".calendar-component")) {
373
375
  document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
@@ -389,10 +391,10 @@ Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types
389
391
  If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
390
392
 
391
393
  ```python
392
- from django_components import component
394
+ from django_components import Component, register
393
395
 
394
- @component.register("calendar")
395
- class Calendar(component.Component):
396
+ @register("calendar")
397
+ class Calendar(Component):
396
398
  def get_context_data(self, date):
397
399
  return {
398
400
  "date": date,
@@ -419,8 +421,8 @@ class Calendar(component.Component):
419
421
  """
420
422
  ```
421
423
 
422
- You don't need to use `t.django_html`, `t.css`, `t.js` and `from django_components import types as t` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
423
- You only need to write the comments `# language=<lang>` above the variables.
424
+ You don't need to use `types.django_html`, `types.css`, `types.js` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
425
+ You only need to write the comments `# language=<lang>` above the variables.
424
426
 
425
427
  ## Use components in templates
426
428
 
@@ -476,7 +478,7 @@ Components can be rendered outside of Django templates, calling them as regular
476
478
  The component class defines `render` and `render_to_response` class methods. These methods accept positional args, kwargs, and slots, offering the same flexibility as the `{% component %}` tag:
477
479
 
478
480
  ```py
479
- class SimpleComponent(component.Component):
481
+ class SimpleComponent(Component):
480
482
  template = """
481
483
  {% load component_tags %}
482
484
  hello: {{ hello }}
@@ -524,21 +526,21 @@ Component.render(
524
526
  ```
525
527
 
526
528
  - _`args`_ - Positional args for the component. This is the same as calling the component
527
- as `{% component "my_comp" arg1 arg2 ... %}`
529
+ as `{% component "my_comp" arg1 arg2 ... %}`
528
530
 
529
531
  - _`kwargs`_ - Keyword args for the component. This is the same as calling the component
530
- as `{% component "my_comp" key1=val1 key2=val2 ... %}`
532
+ as `{% component "my_comp" key1=val1 key2=val2 ... %}`
531
533
 
532
534
  - _`slots`_ - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
533
- Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
534
- or [`SlotRenderFunc`](#slotrenderfunc).
535
+ Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
536
+ or [`SlotRenderFunc`](#slotrenderfunc).
535
537
 
536
538
  - _`escape_slots_content`_ - Whether the content from `slots` should be escaped. `True` by default to prevent XSS attacks. If you disable escaping, you should make sure that any content you pass to the slots is safe, especially if it comes from user input.
537
539
 
538
540
  - _`context`_ - A context (dictionary or Django's Context) within which the component
539
- is rendered. The keys on the context can be accessed from within the template.
540
- - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
541
- component's args and kwargs.
541
+ is rendered. The keys on the context can be accessed from within the template.
542
+ - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
543
+ component's args and kwargs.
542
544
 
543
545
  #### `SlotRenderFunc`
544
546
 
@@ -558,9 +560,10 @@ def render_func(
558
560
  - _`context`_ - Django's Context available to the Slot Node.
559
561
  - _`data`_ - Data passed to the `{% slot %}` tag. See [Scoped Slots](#scoped-slots).
560
562
  - _`slot_ref`_ - The default slot content. See [Accessing original content of slots](#accessing-original-content-of-slots).
561
- - NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
563
+ - NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
562
564
 
563
565
  Example:
566
+
564
567
  ```py
565
568
  def footer_slot(ctx, data, slot_ref):
566
569
  return f"""
@@ -589,7 +592,7 @@ class MyResponse(HttpResponse):
589
592
  self.headers = ...
590
593
  self.status = ...
591
594
 
592
- class SimpleComponent(component.Component):
595
+ class SimpleComponent(Component):
593
596
  response_class = MyResponse
594
597
  template: types.django_html = "HELLO"
595
598
 
@@ -609,10 +612,10 @@ Here's an example of a calendar component defined as a view:
609
612
 
610
613
  ```python
611
614
  # In a file called [project root]/components/calendar.py
612
- from django_components import component
615
+ from django_components import Component, register
613
616
 
614
- @component.register("calendar")
615
- class Calendar(component.Component):
617
+ @register("calendar")
618
+ class Calendar(Component):
616
619
 
617
620
  template = """
618
621
  <div class="calendar-component">
@@ -666,13 +669,13 @@ If you're planning on passing an HTML string, check Django's use of [`format_htm
666
669
 
667
670
  ## Autodiscovery
668
671
 
669
- Every component that you want to use in the template with the `{% component %}` tag needs to be registered with the ComponentRegistry. Normally, we use the `@component.register` decorator for that:
672
+ Every component that you want to use in the template with the `{% component %}` tag needs to be registered with the ComponentRegistry. Normally, we use the `@register` decorator for that:
670
673
 
671
674
  ```py
672
- from django_components import component
675
+ from django_components import Component, register
673
676
 
674
- @component.register("calendar")
675
- class Calendar(component.Component):
677
+ @register("calendar")
678
+ class Calendar(Component):
676
679
  ...
677
680
  ```
678
681
 
@@ -703,7 +706,7 @@ Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps
703
706
  If you are using autodiscovery, keep a few points in mind:
704
707
 
705
708
  - Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
706
- - Components inside the auto-imported files still need to be registered with `@component.register()`
709
+ - Components inside the auto-imported files still need to be registered with `@register()`
707
710
  - Auto-imported component files must be valid Python modules, they must use suffix `.py`, and module name should follow [PEP-8](https://peps.python.org/pep-0008/#package-and-module-names).
708
711
 
709
712
  Autodiscovery can be disabled in the [settings](#disable-autodiscovery).
@@ -808,12 +811,8 @@ The rendered result (exactly the same as before):
808
811
 
809
812
  ```html
810
813
  <div class="calendar-component">
811
- <div class="header">
812
- Calendar header
813
- </div>
814
- <div class="body">
815
- Can you believe it's already <span>2020-06-06</span>??
816
- </div>
814
+ <div class="header">Calendar header</div>
815
+ <div class="body">Can you believe it's already <span>2020-06-06</span>??</div>
817
816
  </div>
818
817
  ```
819
818
 
@@ -921,17 +920,20 @@ Which you can then use are regular default slot:
921
920
  _Added in version 0.26_
922
921
 
923
922
  > NOTE: In version 0.77, the syntax was changed from
923
+ >
924
924
  > ```django
925
925
  > {% fill "my_slot" as "alias" %} {{ alias.default }}
926
926
  > ```
927
+ >
927
928
  > to
929
+ >
928
930
  > ```django
929
931
  > {% fill "my_slot" default="slot_default" %} {{ slot_default }}
930
932
  > ```
931
933
 
932
934
  Sometimes you may want to keep the original slot, but only wrap or prepend/append content to it. To do so, you can access the default slot via the `default` kwarg.
933
935
 
934
- Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
936
+ Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
935
937
 
936
938
  For instance, let's say you're filling a slot called 'body'. To render the original slot, assign it to a variable using the `'default'` keyword. You then render this variable to insert the default content:
937
939
 
@@ -983,11 +985,8 @@ explicit fills, the div containing the slot is still rendered, as shown below:
983
985
 
984
986
  ```html
985
987
  <div class="frontmatter-component">
986
- <div class="title">
987
- Title
988
- </div>
989
- <div class="subtitle">
990
- </div>
988
+ <div class="title">Title</div>
989
+ <div class="subtitle"></div>
991
990
  </div>
992
991
  ```
993
992
 
@@ -1057,8 +1056,8 @@ _Added in version 0.76_:
1057
1056
  Consider a component with slot(s). This component may do some processing on the inputs, and then use the processed variable in the slot's default template:
1058
1057
 
1059
1058
  ```py
1060
- @component.register("my_comp")
1061
- class MyComp(component.Component):
1059
+ @register("my_comp")
1060
+ class MyComp(Component):
1062
1061
  template = """
1063
1062
  <div>
1064
1063
  {% slot "content" default %}
@@ -1086,8 +1085,8 @@ Using scoped slots consists of two steps:
1086
1085
  To pass the data to the `slot` tag, simply pass them as keyword attributes (`key=value`):
1087
1086
 
1088
1087
  ```py
1089
- @component.register("my_comp")
1090
- class MyComp(component.Component):
1088
+ @register("my_comp")
1089
+ class MyComp(Component):
1091
1090
  template = """
1092
1091
  <div>
1093
1092
  {% slot "content" default input=input %}
@@ -1177,8 +1176,8 @@ so are still valid:
1177
1176
  These can then be accessed inside `get_context_data` so:
1178
1177
 
1179
1178
  ```py
1180
- @component.register("calendar")
1181
- class Calendar(component.Component):
1179
+ @register("calendar")
1180
+ class Calendar(Component):
1182
1181
  # Since # . @ - are not valid identifiers, we have to
1183
1182
  # use `**kwargs` so the method can accept these args.
1184
1183
  def get_context_data(self, **kwargs):
@@ -1202,8 +1201,8 @@ In such cases, we may want to define some HTML attributes statically, and other
1202
1201
  But for that, we need to define this dictionary on Python side:
1203
1202
 
1204
1203
  ```py
1205
- @component.register("my_comp")
1206
- class MyComp(component.Component):
1204
+ @register("my_comp")
1205
+ class MyComp(Component):
1207
1206
  template = """
1208
1207
  {% component "other" attrs=attrs %}
1209
1208
  {% endcomponent %}
@@ -1230,8 +1229,8 @@ we prefix the key with the name of the dict and `:`. So key `class` of input `at
1230
1229
  `attrs:class`. And our example becomes:
1231
1230
 
1232
1231
  ```py
1233
- @component.register("my_comp")
1234
- class MyComp(component.Component):
1232
+ @register("my_comp")
1233
+ class MyComp(Component):
1235
1234
  template = """
1236
1235
  {% component "other"
1237
1236
  attrs:class="pa-4 flex"
@@ -1320,8 +1319,7 @@ And template:
1320
1319
  Then this renders:
1321
1320
 
1322
1321
  ```html
1323
- <div class="text-green">
1324
- </div>
1322
+ <div class="text-green"></div>
1325
1323
  ```
1326
1324
 
1327
1325
  ### Boolean attributes
@@ -1329,8 +1327,7 @@ Then this renders:
1329
1327
  In HTML, boolean attributes are usually rendered with no value. Consider the example below where the first button is disabled and the second is not:
1330
1328
 
1331
1329
  ```html
1332
- <button disabled> Click me! </button>
1333
- <button> Click me! </button>
1330
+ <button disabled>Click me!</button> <button>Click me!</button>
1334
1331
  ```
1335
1332
 
1336
1333
  HTML rendering with `html_attrs` tag or `attributes_to_string` works the same way, where `key=True` is rendered simply as `key`, and `key=False` is not render at all.
@@ -1354,8 +1351,7 @@ And template:
1354
1351
  Then this renders:
1355
1352
 
1356
1353
  ```html
1357
- <div disabled>
1358
- </div>
1354
+ <div disabled></div>
1359
1355
  ```
1360
1356
 
1361
1357
  ### Default attributes
@@ -1404,8 +1400,7 @@ And on `html_attrs` tag, we set the key `class`:
1404
1400
  Then these will be merged and rendered as:
1405
1401
 
1406
1402
  ```html
1407
- <div data-value="my-class pa-4 some-class">
1408
- </div>
1403
+ <div data-value="my-class pa-4 some-class"></div>
1409
1404
  ```
1410
1405
 
1411
1406
  To simplify merging of variables, you can supply the same key multiple times, and these will be all joined together:
@@ -1523,8 +1518,8 @@ Then:
1523
1518
  ### Full example for `html_attrs`
1524
1519
 
1525
1520
  ```py
1526
- @component.register("my_comp")
1527
- class MyComp(component.Component):
1521
+ @register("my_comp")
1522
+ class MyComp(Component):
1528
1523
  template: t.django_html = """
1529
1524
  <div
1530
1525
  {% html_attrs attrs
@@ -1545,8 +1540,8 @@ class MyComp(component.Component):
1545
1540
  "class_from_var": "extra-class"
1546
1541
  }
1547
1542
 
1548
- @component.register("parent")
1549
- class Parent(component.Component):
1543
+ @register("parent")
1544
+ class Parent(Component):
1550
1545
  template: t.django_html = """
1551
1546
  {% component "my_comp"
1552
1547
  date=date
@@ -1579,8 +1574,7 @@ will be appended to it.
1579
1574
  So by default, `MyComp` renders:
1580
1575
 
1581
1576
  ```html
1582
- <div class="pa-4 text-red my-comp-date extra-class" data-id="123">
1583
- ...
1577
+ <div class="pa-4 text-red my-comp-date extra-class" data-id="123">...</div>
1584
1578
  ```
1585
1579
 
1586
1580
  Next, let's consider what will be rendered when we call `MyComp` from `Parent`
@@ -1650,6 +1644,7 @@ attributes_to_string(attrs)
1650
1644
  _New in version 0.80_:
1651
1645
 
1652
1646
  Django components supports dependency injection with the combination of:
1647
+
1653
1648
  1. `{% provide %}` tag
1654
1649
  1. `inject()` method of the `Component` class
1655
1650
 
@@ -1670,6 +1665,7 @@ This feature is inspired by Vue's [Provide / Inject](https://vuejs.org/guide/com
1670
1665
  ### How to use provide / inject
1671
1666
 
1672
1667
  As the name suggest, using provide / inject consists of 2 steps
1668
+
1673
1669
  1. Providing data
1674
1670
  2. Injecting provided data
1675
1671
 
@@ -1692,6 +1688,7 @@ First we use the `{% provide %}` tag to define the data we want to "provide" (ma
1692
1688
  Notice that the `provide` tag REQUIRES a name as a first argument. This is the _key_ by which we can then access the data passed to this tag.
1693
1689
 
1694
1690
  `provide` tag _key_, similarly to the _name_ argument in `component` or `slot` tags, has these requirements:
1691
+
1695
1692
  - The _key_ must be a string literal
1696
1693
  - It must be a valid identifier (AKA a valid Python variable name)
1697
1694
 
@@ -1699,9 +1696,10 @@ Once you've set the name, you define the data you want to "provide" by passing i
1699
1696
 
1700
1697
  > NOTE: Kwargs passed to `{% provide %}` are NOT added to the context.
1701
1698
  > In the example below, the `{{ key }}` won't render anything:
1699
+ >
1702
1700
  > ```django
1703
1701
  > {% provide "my_data" key="hi" another=123 %}
1704
- > {{ key }}
1702
+ > {{ key }}
1705
1703
  > {% endprovide %}
1706
1704
  > ```
1707
1705
 
@@ -1714,7 +1712,7 @@ For a component to be able to "inject" some data, the component (`{% component %
1714
1712
  In the example from previous section, we've defined two kwargs: `key="hi" another=123`. That means that if we now inject `"my_data"`, we get an object with 2 attributes - `key` and `another`.
1715
1713
 
1716
1714
  ```py
1717
- class ChildComponent(component.Component):
1715
+ class ChildComponent(Component):
1718
1716
  def get_context_data(self):
1719
1717
  my_data = self.inject("my_data")
1720
1718
  print(my_data.key) # hi
@@ -1729,7 +1727,7 @@ with given key is found, `inject` raises a `KeyError`.
1729
1727
  To avoid the error, you can pass a second argument to `inject` to which will act as a default value, similar to `dict.get(key, default)`:
1730
1728
 
1731
1729
  ```py
1732
- class ChildComponent(component.Component):
1730
+ class ChildComponent(Component):
1733
1731
  def get_context_data(self):
1734
1732
  my_data = self.inject("invalid_key", DEFAULT_DATA)
1735
1733
  assert my_data == DEFAUKT_DATA
@@ -1741,12 +1739,11 @@ have all the keys that were passed to the `provide` tag.
1741
1739
 
1742
1740
  > NOTE: `inject()` works strictly only in `get_context_data`. If you try to call it from elsewhere, it will raise an error.
1743
1741
 
1744
-
1745
1742
  ### Full example
1746
1743
 
1747
1744
  ```py
1748
- @component.register("child")
1749
- class ChildComponent(component.Component):
1745
+ @register("child")
1746
+ class ChildComponent(Component):
1750
1747
  template = """
1751
1748
  <div> {{ my_data.key }} </div>
1752
1749
  <div> {{ my_data.another }} </div>
@@ -1768,15 +1765,15 @@ template_str = """
1768
1765
  renders:
1769
1766
 
1770
1767
  ```html
1771
- <div> hi </div>
1772
- <div> 123 </div>
1768
+ <div>hi</div>
1769
+ <div>123</div>
1773
1770
  ```
1774
1771
 
1775
1772
  ## Component context and scope
1776
1773
 
1777
1774
  By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
1778
1775
 
1779
- With this in mind, the `{% component %}` tag behaves similarly to `{% include %}` tag - inside the component tag, you can access all variables that were defined outside of it.
1776
+ With this in mind, the `{% component %}` tag behaves similarly to `{% include %}` tag - inside the component tag, you can access all variables that were defined outside of it.
1780
1777
 
1781
1778
  And just like with `{% include %}`, if you don't want a specific component template to have access to the parent context, add `only` to the end of the `{% component %}` tag:
1782
1779
 
@@ -1795,6 +1792,7 @@ Components can also access the outer context in their context methods like `get_
1795
1792
  django_component's management of files builds on top of [Django's `Media` class](https://docs.djangoproject.com/en/5.0/topics/forms/media/).
1796
1793
 
1797
1794
  To be familiar with how Django handles static files, we recommend reading also:
1795
+
1798
1796
  - [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
1799
1797
 
1800
1798
  ### Defining file paths relative to component or static dirs
@@ -1804,10 +1802,10 @@ files with a component, you set them as `template_name`, `Media.js` and `Media.c
1804
1802
 
1805
1803
  ```py
1806
1804
  # In a file [project root]/components/calendar/calendar.py
1807
- from django_components import component
1805
+ from django_components import Component, register
1808
1806
 
1809
- @component.register("calendar")
1810
- class Calendar(component.Component):
1807
+ @register("calendar")
1808
+ class Calendar(Component):
1811
1809
  template_name = "template.html"
1812
1810
 
1813
1811
  class Media:
@@ -1823,10 +1821,10 @@ Assuming that `STATICFILES_DIRS` contains path `[project root]/components`, we c
1823
1821
 
1824
1822
  ```py
1825
1823
  # In a file [project root]/components/calendar/calendar.py
1826
- from django_components import component
1824
+ from django_components import Component, register
1827
1825
 
1828
- @component.register("calendar")
1829
- class Calendar(component.Component):
1826
+ @register("calendar")
1827
+ class Calendar(Component):
1830
1828
  template_name = "calendar/template.html"
1831
1829
 
1832
1830
  class Media:
@@ -1841,7 +1839,7 @@ NOTE: In case of conflict, the preference goes to resolving the files relative t
1841
1839
  Each component can have only a single template. However, you can define as many JS or CSS files as you want using a list.
1842
1840
 
1843
1841
  ```py
1844
- class MyComponent(component.Component):
1842
+ class MyComponent(Component):
1845
1843
  class Media:
1846
1844
  js = ["path/to/script1.js", "path/to/script2.js"]
1847
1845
  css = ["path/to/style1.css", "path/to/style2.css"]
@@ -1857,7 +1855,7 @@ See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5
1857
1855
  Again, you can set either a single file or a list of files per media type:
1858
1856
 
1859
1857
  ```py
1860
- class MyComponent(component.Component):
1858
+ class MyComponent(Component):
1861
1859
  class Media:
1862
1860
  css = {
1863
1861
  "all": "path/to/style1.css",
@@ -1866,7 +1864,7 @@ class MyComponent(component.Component):
1866
1864
  ```
1867
1865
 
1868
1866
  ```py
1869
- class MyComponent(component.Component):
1867
+ class MyComponent(Component):
1870
1868
  class Media:
1871
1869
  css = {
1872
1870
  "all": ["path/to/style1.css", "path/to/style2.css"],
@@ -1876,10 +1874,10 @@ class MyComponent(component.Component):
1876
1874
 
1877
1875
  NOTE: When you define CSS as a string or a list, the `all` media type is implied.
1878
1876
 
1879
-
1880
1877
  ### Supported types for file paths
1881
1878
 
1882
1879
  File paths can be any of:
1880
+
1883
1881
  - `str`
1884
1882
  - `bytes`
1885
1883
  - `PathLike` (`__fspath__` method)
@@ -1891,7 +1889,7 @@ from pathlib import Path
1891
1889
 
1892
1890
  from django.utils.safestring import mark_safe
1893
1891
 
1894
- class SimpleComponent(component.Component):
1892
+ class SimpleComponent(Component):
1895
1893
  class Media:
1896
1894
  css = [
1897
1895
  mark_safe('<link href="/static/calendar/style.css" rel="stylesheet" />'),
@@ -1930,8 +1928,8 @@ class LazyJsPath:
1930
1928
  f'<script type="module" src="{full_path}"></script>'
1931
1929
  )
1932
1930
 
1933
- @component.register("calendar")
1934
- class Calendar(component.Component):
1931
+ @register("calendar")
1932
+ class Calendar(Component):
1935
1933
  template_name = "calendar/template.html"
1936
1934
 
1937
1935
  def get_context_data(self, date):
@@ -1943,7 +1941,7 @@ class Calendar(component.Component):
1943
1941
  css = "calendar/style.css"
1944
1942
  js = [
1945
1943
  # <script> tag constructed by Media class
1946
- "calendar/script1.js",
1944
+ "calendar/script1.js",
1947
1945
  # Custom <script> tag
1948
1946
  LazyJsPath("calendar/script2.js"),
1949
1947
  ]
@@ -1959,7 +1957,7 @@ To change how the tags are constructed, you can override the [`Media.render_js`
1959
1957
 
1960
1958
  ```py
1961
1959
  from django.forms.widgets import Media
1962
- from django_components import component
1960
+ from django_components import Component, register
1963
1961
 
1964
1962
  class MyMedia(Media):
1965
1963
  # Same as original Media.render_js, except
@@ -1976,14 +1974,14 @@ class MyMedia(Media):
1976
1974
  )
1977
1975
  return tags
1978
1976
 
1979
- @component.register("calendar")
1980
- class Calendar(component.Component):
1977
+ @register("calendar")
1978
+ class Calendar(Component):
1981
1979
  template_name = "calendar/template.html"
1982
1980
 
1983
1981
  class Media:
1984
1982
  css = "calendar/style.css"
1985
1983
  js = "calendar/script.js"
1986
-
1984
+
1987
1985
  # Override the behavior of Media class
1988
1986
  media_class = MyMedia
1989
1987
  ```
@@ -1994,6 +1992,7 @@ NOTE: The instance of the `Media` class (or it's subclass) is available under `C
1994
1992
 
1995
1993
  The JS and CSS files included in components are not automatically rendered.
1996
1994
  Instead, use the following tags to specify where to render the dependencies:
1995
+
1997
1996
  - `component_dependencies` - Renders both JS and CSS
1998
1997
  - `component_js_dependencies` - Renders only JS
1999
1998
  - `component_css_dependencies` - Reneders only CSS
@@ -2045,16 +2044,16 @@ COMPONENTS = {
2045
2044
  Where `mysite/components/forms.py` may look like this:
2046
2045
 
2047
2046
  ```py
2048
- @component.register("form_simple")
2049
- class FormSimple(component.Component):
2047
+ @register("form_simple")
2048
+ class FormSimple(Component):
2050
2049
  template = """
2051
2050
  <form>
2052
2051
  ...
2053
2052
  </form>
2054
2053
  """
2055
2054
 
2056
- @component.register("form_other")
2057
- class FormOther(component.Component):
2055
+ @register("form_other")
2056
+ class FormOther(Component):
2058
2057
  template = """
2059
2058
  <form>
2060
2059
  ...
@@ -2104,15 +2103,17 @@ This has two modes:
2104
2103
 
2105
2104
  - `"django"` - Default - The default Django template behavior.
2106
2105
 
2107
- Inside the `{% fill %}` tag, the context variables you can access are a union of:
2108
- - All the variables that were OUTSIDE the fill tag, including any loops or with tag
2109
- - Data returned from `get_context_data()` of the component that wraps the fill tag.
2106
+ Inside the `{% fill %}` tag, the context variables you can access are a union of:
2107
+
2108
+ - All the variables that were OUTSIDE the fill tag, including any loops or with tag
2109
+ - Data returned from `get_context_data()` of the component that wraps the fill tag.
2110
2110
 
2111
2111
  - `"isolated"` - Similar behavior to [Vue](https://vuejs.org/guide/components/slots.html#render-scope) or React, this is useful if you want to make sure that components don't accidentally access variables defined outside of the component.
2112
2112
 
2113
- Inside the `{% fill %}` tag, you can ONLY access variables from 2 places:
2114
- - `get_context_data()` of the component which defined the template (AKA the "root" component)
2115
- - Any loops (`{% for ... %}`) that the `{% fill %}` tag is part of.
2113
+ Inside the `{% fill %}` tag, you can ONLY access variables from 2 places:
2114
+
2115
+ - `get_context_data()` of the component which defined the template (AKA the "root" component)
2116
+ - Any loops (`{% for ... %}`) that the `{% fill %}` tag is part of.
2116
2117
 
2117
2118
  ```python
2118
2119
  COMPONENTS = {
@@ -2125,7 +2126,7 @@ COMPONENTS = {
2125
2126
  Given this template:
2126
2127
 
2127
2128
  ```py
2128
- class RootComp(component.Component):
2129
+ class RootComp(Component):
2129
2130
  template = """
2130
2131
  {% with cheese="feta" %}
2131
2132
  {% component 'my_comp' %}
@@ -2162,7 +2163,7 @@ all the data defined in the outer layers, like the `{% with %}` tag.
2162
2163
  Given this template:
2163
2164
 
2164
2165
  ```py
2165
- class RootComp(component.Component):
2166
+ class RootComp(Component):
2166
2167
  template = """
2167
2168
  {% with cheese="feta" %}
2168
2169
  {% component 'my_comp' %}