django-components 0.86__tar.gz → 0.88__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.86/src/django_components.egg-info → django_components-0.88}/PKG-INFO +253 -130
- {django_components-0.86 → django_components-0.88}/README.md +252 -129
- {django_components-0.86 → django_components-0.88}/pyproject.toml +1 -1
- django_components-0.88/src/django_components/__init__.py +19 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/component.py +15 -12
- {django_components-0.86 → django_components-0.88}/src/django_components/component_media.py +7 -7
- django_components-0.88/src/django_components/component_registry.py +338 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/management/commands/startcomponent.py +3 -3
- {django_components-0.86 → django_components-0.88/src/django_components.egg-info}/PKG-INFO +253 -130
- {django_components-0.86 → django_components-0.88}/tests/test_attributes.py +28 -31
- {django_components-0.86 → django_components-0.88}/tests/test_autodiscover.py +13 -13
- {django_components-0.86 → django_components-0.88}/tests/test_component.py +21 -21
- {django_components-0.86 → django_components-0.88}/tests/test_component_as_view.py +9 -9
- {django_components-0.86 → django_components-0.88}/tests/test_component_media.py +35 -35
- {django_components-0.86 → django_components-0.88}/tests/test_context.py +25 -29
- {django_components-0.86 → django_components-0.88}/tests/test_dependency_rendering.py +35 -39
- django_components-0.88/tests/test_registry.py +126 -0
- {django_components-0.86 → django_components-0.88}/tests/test_template_parser.py +3 -3
- {django_components-0.86 → django_components-0.88}/tests/test_templatetags.py +37 -44
- {django_components-0.86 → django_components-0.88}/tests/test_templatetags_component.py +32 -42
- {django_components-0.86 → django_components-0.88}/tests/test_templatetags_provide.py +45 -45
- {django_components-0.86 → django_components-0.88}/tests/test_templatetags_slot_fill.py +62 -79
- {django_components-0.86 → django_components-0.88}/tests/test_templatetags_templating.py +34 -46
- django_components-0.86/src/django_components/__init__.py +0 -7
- django_components-0.86/src/django_components/component_registry.py +0 -63
- django_components-0.86/tests/test_registry.py +0 -68
- {django_components-0.86 → django_components-0.88}/LICENSE +0 -0
- {django_components-0.86 → django_components-0.88}/setup.cfg +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/app_settings.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/apps.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/attributes.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/autodiscover.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/context.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/expression.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/logger.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/management/__init__.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/middleware.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/node.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/provide.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/py.typed +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/slots.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/template_loader.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/template_parser.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/templatetags/component_tags.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/types.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components/utils.py +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/SOURCES.txt +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.86 → django_components-0.88}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.86 → django_components-0.88}/tests/test_command_startcomponent.py +0 -0
- {django_components-0.86 → django_components-0.88}/tests/test_safer_staticfiles.py +0 -0
- {django_components-0.86 → django_components-0.88}/tests/test_settings.py +0 -0
- {django_components-0.86 → django_components-0.88}/tests/test_template_loader.py +0 -0
- {django_components-0.86 → django_components-0.88}/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.88
|
|
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
|
|
|
@@ -52,6 +53,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
52
53
|
- [Using single-file components](#using-single-file-components)
|
|
53
54
|
- [Use components in templates](#use-components-in-templates)
|
|
54
55
|
- [Use components outside of templates](#use-components-outside-of-templates)
|
|
56
|
+
- [Registering components](#registering-components)
|
|
55
57
|
- [Use components as views](#use-components-as-views)
|
|
56
58
|
- [Autodiscovery](#autodiscovery)
|
|
57
59
|
- [Using slots in templates](#using-slots-in-templates)
|
|
@@ -71,11 +73,12 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
71
73
|
## Release notes
|
|
72
74
|
|
|
73
75
|
🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
|
|
76
|
+
|
|
74
77
|
- Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
78
|
+
- To migrate from:
|
|
79
|
+
- `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
|
|
80
|
+
or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
|
|
81
|
+
- `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
|
|
79
82
|
- 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
83
|
|
|
81
84
|
🚨📢 **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 +91,12 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
88
91
|
|
|
89
92
|
- 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
93
|
|
|
91
|
-
|
|
92
94
|
🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
|
|
95
|
+
|
|
93
96
|
- Previously, the syntax was
|
|
94
|
-
`{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
|
|
97
|
+
`{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
|
|
95
98
|
- Now, the syntax is
|
|
96
|
-
`{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
|
|
99
|
+
`{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
|
|
97
100
|
|
|
98
101
|
**Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
|
|
99
102
|
|
|
@@ -112,7 +115,7 @@ This change is done to simplify the API in anticipation of a 1.0 release of djan
|
|
|
112
115
|
|
|
113
116
|
**Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags.
|
|
114
117
|
|
|
115
|
-
**Version 0.27** adds a second installable app:
|
|
118
|
+
**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
119
|
|
|
117
120
|
**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
121
|
|
|
@@ -122,7 +125,7 @@ This change is done to simplify the API in anticipation of a 1.0 release of djan
|
|
|
122
125
|
|
|
123
126
|
## Security notes 🚨
|
|
124
127
|
|
|
125
|
-
|
|
128
|
+
_You are advised to read this section before using django-components in production._
|
|
126
129
|
|
|
127
130
|
### Static files
|
|
128
131
|
|
|
@@ -132,12 +135,12 @@ This means that files containing backend logic, such as Python modules and HTML
|
|
|
132
135
|
|
|
133
136
|
If your are using _django.contrib.staticfiles_ to collect static files, no distinction is made between the different kinds of files.
|
|
134
137
|
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
|
|
138
|
+
You probably don't want this, as parts of your backend logic will be exposed, posing a **potential security vulnerability**.
|
|
136
139
|
|
|
137
|
-
As of
|
|
138
|
-
It is a drop-in replacement for
|
|
140
|
+
As of _v0.27_, django-components ships with an additional installable app _django_components.**safer_staticfiles**_.
|
|
141
|
+
It is a drop-in replacement for _django.contrib.staticfiles_.
|
|
139
142
|
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
|
|
143
|
+
To use it, add it to INSTALLED*APPS and remove \_django.contrib.staticfiles*.
|
|
141
144
|
|
|
142
145
|
```python
|
|
143
146
|
INSTALLED_APPS = [
|
|
@@ -187,7 +190,8 @@ For a step-by-step guide on deploying production server with static files,
|
|
|
187
190
|
```
|
|
188
191
|
|
|
189
192
|
4. Modify `TEMPLATES` section of settings.py as follows:
|
|
190
|
-
|
|
193
|
+
|
|
194
|
+
- _Remove `'APP_DIRS': True,`_
|
|
191
195
|
- Add `loaders` to `OPTIONS` list and set it to following value:
|
|
192
196
|
|
|
193
197
|
```python
|
|
@@ -250,13 +254,13 @@ Read on to find out how to build your first component!
|
|
|
250
254
|
|
|
251
255
|
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
256
|
|
|
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
|
|
257
|
+
| Python version | Django version |
|
|
258
|
+
| -------------- | -------------- |
|
|
259
|
+
| 3.8 | 4.2 |
|
|
260
|
+
| 3.9 | 4.2 |
|
|
261
|
+
| 3.10 | 4.2, 5.0 |
|
|
262
|
+
| 3.11 | 4.2, 5.0 |
|
|
263
|
+
| 3.12 | 4.2, 5.0 |
|
|
260
264
|
|
|
261
265
|
## Create your first component
|
|
262
266
|
|
|
@@ -317,10 +321,10 @@ Inside this file we create a Component by inheriting from the Component class an
|
|
|
317
321
|
|
|
318
322
|
```python
|
|
319
323
|
# In a file called [project root]/components/calendar/calendar.py
|
|
320
|
-
from django_components import
|
|
324
|
+
from django_components import Component, register
|
|
321
325
|
|
|
322
|
-
@
|
|
323
|
-
class Calendar(
|
|
326
|
+
@register("calendar")
|
|
327
|
+
class Calendar(Component):
|
|
324
328
|
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
325
329
|
# will be automatically found. To customize which template to use based on context
|
|
326
330
|
# you can override method `get_template_name` instead of specifying `template_name`.
|
|
@@ -348,26 +352,25 @@ Components can also be defined in a single file, which is useful for small compo
|
|
|
348
352
|
|
|
349
353
|
```python
|
|
350
354
|
# In a file called [project root]/components/calendar.py
|
|
351
|
-
from django_components import
|
|
352
|
-
from django_components import types as t
|
|
355
|
+
from django_components import Component, register, types
|
|
353
356
|
|
|
354
|
-
@
|
|
355
|
-
class Calendar(
|
|
357
|
+
@register("calendar")
|
|
358
|
+
class Calendar(Component):
|
|
356
359
|
def get_context_data(self, date):
|
|
357
360
|
return {
|
|
358
361
|
"date": date,
|
|
359
362
|
}
|
|
360
363
|
|
|
361
|
-
template:
|
|
364
|
+
template: types.django_html = """
|
|
362
365
|
<div class="calendar-component">Today's date is <span>{{ date }}</span></div>
|
|
363
366
|
"""
|
|
364
367
|
|
|
365
|
-
css:
|
|
368
|
+
css: types.css = """
|
|
366
369
|
.calendar-component { width: 200px; background: pink; }
|
|
367
370
|
.calendar-component span { font-weight: bold; }
|
|
368
371
|
"""
|
|
369
372
|
|
|
370
|
-
js:
|
|
373
|
+
js: types.js = """
|
|
371
374
|
(function(){
|
|
372
375
|
if (document.querySelector(".calendar-component")) {
|
|
373
376
|
document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
|
|
@@ -389,10 +392,10 @@ Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types
|
|
|
389
392
|
If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
|
|
390
393
|
|
|
391
394
|
```python
|
|
392
|
-
from django_components import
|
|
395
|
+
from django_components import Component, register
|
|
393
396
|
|
|
394
|
-
@
|
|
395
|
-
class Calendar(
|
|
397
|
+
@register("calendar")
|
|
398
|
+
class Calendar(Component):
|
|
396
399
|
def get_context_data(self, date):
|
|
397
400
|
return {
|
|
398
401
|
"date": date,
|
|
@@ -419,8 +422,8 @@ class Calendar(component.Component):
|
|
|
419
422
|
"""
|
|
420
423
|
```
|
|
421
424
|
|
|
422
|
-
You don't need to use `
|
|
423
|
-
You only need to write the comments `# language=<lang>` above the variables.
|
|
425
|
+
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).
|
|
426
|
+
You only need to write the comments `# language=<lang>` above the variables.
|
|
424
427
|
|
|
425
428
|
## Use components in templates
|
|
426
429
|
|
|
@@ -476,7 +479,7 @@ Components can be rendered outside of Django templates, calling them as regular
|
|
|
476
479
|
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
480
|
|
|
478
481
|
```py
|
|
479
|
-
class SimpleComponent(
|
|
482
|
+
class SimpleComponent(Component):
|
|
480
483
|
template = """
|
|
481
484
|
{% load component_tags %}
|
|
482
485
|
hello: {{ hello }}
|
|
@@ -524,21 +527,21 @@ Component.render(
|
|
|
524
527
|
```
|
|
525
528
|
|
|
526
529
|
- _`args`_ - Positional args for the component. This is the same as calling the component
|
|
527
|
-
|
|
530
|
+
as `{% component "my_comp" arg1 arg2 ... %}`
|
|
528
531
|
|
|
529
532
|
- _`kwargs`_ - Keyword args for the component. This is the same as calling the component
|
|
530
|
-
|
|
533
|
+
as `{% component "my_comp" key1=val1 key2=val2 ... %}`
|
|
531
534
|
|
|
532
535
|
- _`slots`_ - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
|
|
533
|
-
|
|
534
|
-
|
|
536
|
+
Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
|
|
537
|
+
or [`SlotRenderFunc`](#slotrenderfunc).
|
|
535
538
|
|
|
536
539
|
- _`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
540
|
|
|
538
541
|
- _`context`_ - A context (dictionary or Django's Context) within which the component
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
+
is rendered. The keys on the context can be accessed from within the template.
|
|
543
|
+
- NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
|
|
544
|
+
component's args and kwargs.
|
|
542
545
|
|
|
543
546
|
#### `SlotRenderFunc`
|
|
544
547
|
|
|
@@ -558,9 +561,10 @@ def render_func(
|
|
|
558
561
|
- _`context`_ - Django's Context available to the Slot Node.
|
|
559
562
|
- _`data`_ - Data passed to the `{% slot %}` tag. See [Scoped Slots](#scoped-slots).
|
|
560
563
|
- _`slot_ref`_ - The default slot content. See [Accessing original content of slots](#accessing-original-content-of-slots).
|
|
561
|
-
|
|
564
|
+
- NOTE: The slot is lazily evaluated. To render the slot, convert it to string with `str(slot_ref)`.
|
|
562
565
|
|
|
563
566
|
Example:
|
|
567
|
+
|
|
564
568
|
```py
|
|
565
569
|
def footer_slot(ctx, data, slot_ref):
|
|
566
570
|
return f"""
|
|
@@ -589,7 +593,7 @@ class MyResponse(HttpResponse):
|
|
|
589
593
|
self.headers = ...
|
|
590
594
|
self.status = ...
|
|
591
595
|
|
|
592
|
-
class SimpleComponent(
|
|
596
|
+
class SimpleComponent(Component):
|
|
593
597
|
response_class = MyResponse
|
|
594
598
|
template: types.django_html = "HELLO"
|
|
595
599
|
|
|
@@ -609,10 +613,10 @@ Here's an example of a calendar component defined as a view:
|
|
|
609
613
|
|
|
610
614
|
```python
|
|
611
615
|
# In a file called [project root]/components/calendar.py
|
|
612
|
-
from django_components import
|
|
616
|
+
from django_components import Component, register
|
|
613
617
|
|
|
614
|
-
@
|
|
615
|
-
class Calendar(
|
|
618
|
+
@register("calendar")
|
|
619
|
+
class Calendar(Component):
|
|
616
620
|
|
|
617
621
|
template = """
|
|
618
622
|
<div class="calendar-component">
|
|
@@ -664,15 +668,136 @@ Note: slots content are automatically escaped by default to prevent XSS attacks.
|
|
|
664
668
|
|
|
665
669
|
If you're planning on passing an HTML string, check Django's use of [`format_html`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.html.format_html) and [`mark_safe`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.safestring.mark_safe).
|
|
666
670
|
|
|
671
|
+
## Registering components
|
|
672
|
+
|
|
673
|
+
In previous examples you could repeatedly see us using `@register()` to "register"
|
|
674
|
+
the components. In this section we dive deeper into what it actually means and how you can
|
|
675
|
+
manage (add or remove) components.
|
|
676
|
+
|
|
677
|
+
As a reminder, we may have a component like this:
|
|
678
|
+
|
|
679
|
+
```python
|
|
680
|
+
from django_components import Component, register
|
|
681
|
+
|
|
682
|
+
@register("calendar")
|
|
683
|
+
class Calendar(Component):
|
|
684
|
+
template_name = "template.html"
|
|
685
|
+
|
|
686
|
+
# This component takes one parameter, a date string to show in the template
|
|
687
|
+
def get_context_data(self, date):
|
|
688
|
+
return {
|
|
689
|
+
"date": date,
|
|
690
|
+
}
|
|
691
|
+
```
|
|
692
|
+
|
|
693
|
+
which we then render in the template as:
|
|
694
|
+
|
|
695
|
+
```django
|
|
696
|
+
{% component "calendar" date="1970-01-01" %}
|
|
697
|
+
{% endcomponent %}
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
As you can see, `@register` links up the component class
|
|
701
|
+
with the `{% component %}` template tag. So when the template tag comes across
|
|
702
|
+
a component called `"calendar"`, it can look up it's class and instantiate it.
|
|
703
|
+
|
|
704
|
+
### What is ComponentRegistry
|
|
705
|
+
|
|
706
|
+
The `@register` decorator is a shortcut for working with the `ComponentRegistry`.
|
|
707
|
+
|
|
708
|
+
`ComponentRegistry` manages which components can be used in the template tags.
|
|
709
|
+
|
|
710
|
+
Each `ComponentRegistry` instance is associated with an instance
|
|
711
|
+
of Django's `Library`. And Libraries are inserted into Django template
|
|
712
|
+
using the `{% load %}` tags.
|
|
713
|
+
|
|
714
|
+
The `@register` decorator accepts an optional kwarg `registry`, which specifies, the `ComponentRegistry` to register components into.
|
|
715
|
+
If omitted, the default `ComponentRegistry` instance defined in django_components is used.
|
|
716
|
+
|
|
717
|
+
```py
|
|
718
|
+
my_registry = ComponentRegistry()
|
|
719
|
+
|
|
720
|
+
@register(registry=my_registry)
|
|
721
|
+
class MyComponent(Component):
|
|
722
|
+
...
|
|
723
|
+
```
|
|
724
|
+
|
|
725
|
+
The default `ComponentRegistry` is associated with the `Library` that
|
|
726
|
+
you load when you call `{% load component_tags %}` inside your template, or when you
|
|
727
|
+
add `django_components.templatetags.component_tags` to the template builtins.
|
|
728
|
+
|
|
729
|
+
So when you register or unregister a component to/from a component registry,
|
|
730
|
+
then behind the scenes the registry automatically adds/removes the component's
|
|
731
|
+
template tags to/from the Library, so you can call the component from within the templates
|
|
732
|
+
such as `{% component "my_comp" %}`.
|
|
733
|
+
|
|
734
|
+
### Working with ComponentRegistry
|
|
735
|
+
|
|
736
|
+
The default `ComponentRegistry` instance can be imported as:
|
|
737
|
+
|
|
738
|
+
```py
|
|
739
|
+
from django_components import registry
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
You can use the registry to manually add/remove/get components:
|
|
743
|
+
|
|
744
|
+
```py
|
|
745
|
+
from django_components import registry
|
|
746
|
+
|
|
747
|
+
# Register components
|
|
748
|
+
registry.register("button", ButtonComponent)
|
|
749
|
+
registry.register("card", CardComponent)
|
|
750
|
+
|
|
751
|
+
# Get all or single
|
|
752
|
+
registry.all() # {"button": ButtonComponent, "card": CardComponent}
|
|
753
|
+
registry.get("card") # CardComponent
|
|
754
|
+
|
|
755
|
+
# Unregister single component
|
|
756
|
+
registry.unregister("card")
|
|
757
|
+
|
|
758
|
+
# Unregister all components
|
|
759
|
+
registry.clear()
|
|
760
|
+
```
|
|
761
|
+
|
|
762
|
+
### Registering components to custom ComponentRegistry
|
|
763
|
+
|
|
764
|
+
In rare cases, you may want to manage your own instance of `ComponentRegistry`,
|
|
765
|
+
or register components onto a different `Library` instance than the default one.
|
|
766
|
+
|
|
767
|
+
The `Library` instance can be set at instantiation of `ComponentRegistry`. If omitted,
|
|
768
|
+
then the default Library instance from django_components is used.
|
|
769
|
+
|
|
770
|
+
```py
|
|
771
|
+
from django.template import Library
|
|
772
|
+
from django_components import ComponentRegistry
|
|
773
|
+
|
|
774
|
+
my_library = Library(...)
|
|
775
|
+
my_registry = ComponentRegistry(library=my_library)
|
|
776
|
+
```
|
|
777
|
+
|
|
778
|
+
When you have defined your own `ComponentRegistry`, you can either register the components
|
|
779
|
+
with `my_registry.register()`, or pass the registry to the `@component.register()` decorator
|
|
780
|
+
via the `registry` kwarg:
|
|
781
|
+
|
|
782
|
+
```py
|
|
783
|
+
from path.to.my.registry import my_registry
|
|
784
|
+
|
|
785
|
+
@register("my_component", registry=my_registry)
|
|
786
|
+
class MyComponent(Component):
|
|
787
|
+
...
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
NOTE: The Library instance can be accessed under `library` attribute of `ComponentRegistry`.
|
|
791
|
+
|
|
667
792
|
## Autodiscovery
|
|
668
793
|
|
|
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 `@
|
|
794
|
+
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
795
|
|
|
671
796
|
```py
|
|
672
|
-
from django_components import
|
|
797
|
+
from django_components import Component, register
|
|
673
798
|
|
|
674
|
-
@
|
|
675
|
-
class Calendar(
|
|
799
|
+
@register("calendar")
|
|
800
|
+
class Calendar(Component):
|
|
676
801
|
...
|
|
677
802
|
```
|
|
678
803
|
|
|
@@ -703,7 +828,7 @@ Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps
|
|
|
703
828
|
If you are using autodiscovery, keep a few points in mind:
|
|
704
829
|
|
|
705
830
|
- 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 `@
|
|
831
|
+
- Components inside the auto-imported files still need to be registered with `@register()`
|
|
707
832
|
- 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
833
|
|
|
709
834
|
Autodiscovery can be disabled in the [settings](#disable-autodiscovery).
|
|
@@ -808,12 +933,8 @@ The rendered result (exactly the same as before):
|
|
|
808
933
|
|
|
809
934
|
```html
|
|
810
935
|
<div class="calendar-component">
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
</div>
|
|
814
|
-
<div class="body">
|
|
815
|
-
Can you believe it's already <span>2020-06-06</span>??
|
|
816
|
-
</div>
|
|
936
|
+
<div class="header">Calendar header</div>
|
|
937
|
+
<div class="body">Can you believe it's already <span>2020-06-06</span>??</div>
|
|
817
938
|
</div>
|
|
818
939
|
```
|
|
819
940
|
|
|
@@ -921,17 +1042,20 @@ Which you can then use are regular default slot:
|
|
|
921
1042
|
_Added in version 0.26_
|
|
922
1043
|
|
|
923
1044
|
> NOTE: In version 0.77, the syntax was changed from
|
|
1045
|
+
>
|
|
924
1046
|
> ```django
|
|
925
1047
|
> {% fill "my_slot" as "alias" %} {{ alias.default }}
|
|
926
1048
|
> ```
|
|
1049
|
+
>
|
|
927
1050
|
> to
|
|
1051
|
+
>
|
|
928
1052
|
> ```django
|
|
929
1053
|
> {% fill "my_slot" default="slot_default" %} {{ slot_default }}
|
|
930
1054
|
> ```
|
|
931
1055
|
|
|
932
1056
|
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
1057
|
|
|
934
|
-
Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
|
|
1058
|
+
Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
|
|
935
1059
|
|
|
936
1060
|
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
1061
|
|
|
@@ -983,11 +1107,8 @@ explicit fills, the div containing the slot is still rendered, as shown below:
|
|
|
983
1107
|
|
|
984
1108
|
```html
|
|
985
1109
|
<div class="frontmatter-component">
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
</div>
|
|
989
|
-
<div class="subtitle">
|
|
990
|
-
</div>
|
|
1110
|
+
<div class="title">Title</div>
|
|
1111
|
+
<div class="subtitle"></div>
|
|
991
1112
|
</div>
|
|
992
1113
|
```
|
|
993
1114
|
|
|
@@ -1057,8 +1178,8 @@ _Added in version 0.76_:
|
|
|
1057
1178
|
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
1179
|
|
|
1059
1180
|
```py
|
|
1060
|
-
@
|
|
1061
|
-
class MyComp(
|
|
1181
|
+
@register("my_comp")
|
|
1182
|
+
class MyComp(Component):
|
|
1062
1183
|
template = """
|
|
1063
1184
|
<div>
|
|
1064
1185
|
{% slot "content" default %}
|
|
@@ -1086,8 +1207,8 @@ Using scoped slots consists of two steps:
|
|
|
1086
1207
|
To pass the data to the `slot` tag, simply pass them as keyword attributes (`key=value`):
|
|
1087
1208
|
|
|
1088
1209
|
```py
|
|
1089
|
-
@
|
|
1090
|
-
class MyComp(
|
|
1210
|
+
@register("my_comp")
|
|
1211
|
+
class MyComp(Component):
|
|
1091
1212
|
template = """
|
|
1092
1213
|
<div>
|
|
1093
1214
|
{% slot "content" default input=input %}
|
|
@@ -1177,8 +1298,8 @@ so are still valid:
|
|
|
1177
1298
|
These can then be accessed inside `get_context_data` so:
|
|
1178
1299
|
|
|
1179
1300
|
```py
|
|
1180
|
-
@
|
|
1181
|
-
class Calendar(
|
|
1301
|
+
@register("calendar")
|
|
1302
|
+
class Calendar(Component):
|
|
1182
1303
|
# Since # . @ - are not valid identifiers, we have to
|
|
1183
1304
|
# use `**kwargs` so the method can accept these args.
|
|
1184
1305
|
def get_context_data(self, **kwargs):
|
|
@@ -1202,8 +1323,8 @@ In such cases, we may want to define some HTML attributes statically, and other
|
|
|
1202
1323
|
But for that, we need to define this dictionary on Python side:
|
|
1203
1324
|
|
|
1204
1325
|
```py
|
|
1205
|
-
@
|
|
1206
|
-
class MyComp(
|
|
1326
|
+
@register("my_comp")
|
|
1327
|
+
class MyComp(Component):
|
|
1207
1328
|
template = """
|
|
1208
1329
|
{% component "other" attrs=attrs %}
|
|
1209
1330
|
{% endcomponent %}
|
|
@@ -1230,8 +1351,8 @@ we prefix the key with the name of the dict and `:`. So key `class` of input `at
|
|
|
1230
1351
|
`attrs:class`. And our example becomes:
|
|
1231
1352
|
|
|
1232
1353
|
```py
|
|
1233
|
-
@
|
|
1234
|
-
class MyComp(
|
|
1354
|
+
@register("my_comp")
|
|
1355
|
+
class MyComp(Component):
|
|
1235
1356
|
template = """
|
|
1236
1357
|
{% component "other"
|
|
1237
1358
|
attrs:class="pa-4 flex"
|
|
@@ -1320,8 +1441,7 @@ And template:
|
|
|
1320
1441
|
Then this renders:
|
|
1321
1442
|
|
|
1322
1443
|
```html
|
|
1323
|
-
<div class="text-green">
|
|
1324
|
-
</div>
|
|
1444
|
+
<div class="text-green"></div>
|
|
1325
1445
|
```
|
|
1326
1446
|
|
|
1327
1447
|
### Boolean attributes
|
|
@@ -1329,8 +1449,7 @@ Then this renders:
|
|
|
1329
1449
|
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
1450
|
|
|
1331
1451
|
```html
|
|
1332
|
-
<button disabled>
|
|
1333
|
-
<button> Click me! </button>
|
|
1452
|
+
<button disabled>Click me!</button> <button>Click me!</button>
|
|
1334
1453
|
```
|
|
1335
1454
|
|
|
1336
1455
|
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 +1473,7 @@ And template:
|
|
|
1354
1473
|
Then this renders:
|
|
1355
1474
|
|
|
1356
1475
|
```html
|
|
1357
|
-
<div disabled>
|
|
1358
|
-
</div>
|
|
1476
|
+
<div disabled></div>
|
|
1359
1477
|
```
|
|
1360
1478
|
|
|
1361
1479
|
### Default attributes
|
|
@@ -1404,8 +1522,7 @@ And on `html_attrs` tag, we set the key `class`:
|
|
|
1404
1522
|
Then these will be merged and rendered as:
|
|
1405
1523
|
|
|
1406
1524
|
```html
|
|
1407
|
-
<div data-value="my-class pa-4 some-class">
|
|
1408
|
-
</div>
|
|
1525
|
+
<div data-value="my-class pa-4 some-class"></div>
|
|
1409
1526
|
```
|
|
1410
1527
|
|
|
1411
1528
|
To simplify merging of variables, you can supply the same key multiple times, and these will be all joined together:
|
|
@@ -1523,8 +1640,8 @@ Then:
|
|
|
1523
1640
|
### Full example for `html_attrs`
|
|
1524
1641
|
|
|
1525
1642
|
```py
|
|
1526
|
-
@
|
|
1527
|
-
class MyComp(
|
|
1643
|
+
@register("my_comp")
|
|
1644
|
+
class MyComp(Component):
|
|
1528
1645
|
template: t.django_html = """
|
|
1529
1646
|
<div
|
|
1530
1647
|
{% html_attrs attrs
|
|
@@ -1545,8 +1662,8 @@ class MyComp(component.Component):
|
|
|
1545
1662
|
"class_from_var": "extra-class"
|
|
1546
1663
|
}
|
|
1547
1664
|
|
|
1548
|
-
@
|
|
1549
|
-
class Parent(
|
|
1665
|
+
@register("parent")
|
|
1666
|
+
class Parent(Component):
|
|
1550
1667
|
template: t.django_html = """
|
|
1551
1668
|
{% component "my_comp"
|
|
1552
1669
|
date=date
|
|
@@ -1579,8 +1696,7 @@ will be appended to it.
|
|
|
1579
1696
|
So by default, `MyComp` renders:
|
|
1580
1697
|
|
|
1581
1698
|
```html
|
|
1582
|
-
<div class="pa-4 text-red my-comp-date extra-class" data-id="123">
|
|
1583
|
-
...
|
|
1699
|
+
<div class="pa-4 text-red my-comp-date extra-class" data-id="123">...</div>
|
|
1584
1700
|
```
|
|
1585
1701
|
|
|
1586
1702
|
Next, let's consider what will be rendered when we call `MyComp` from `Parent`
|
|
@@ -1650,6 +1766,7 @@ attributes_to_string(attrs)
|
|
|
1650
1766
|
_New in version 0.80_:
|
|
1651
1767
|
|
|
1652
1768
|
Django components supports dependency injection with the combination of:
|
|
1769
|
+
|
|
1653
1770
|
1. `{% provide %}` tag
|
|
1654
1771
|
1. `inject()` method of the `Component` class
|
|
1655
1772
|
|
|
@@ -1670,6 +1787,7 @@ This feature is inspired by Vue's [Provide / Inject](https://vuejs.org/guide/com
|
|
|
1670
1787
|
### How to use provide / inject
|
|
1671
1788
|
|
|
1672
1789
|
As the name suggest, using provide / inject consists of 2 steps
|
|
1790
|
+
|
|
1673
1791
|
1. Providing data
|
|
1674
1792
|
2. Injecting provided data
|
|
1675
1793
|
|
|
@@ -1692,6 +1810,7 @@ First we use the `{% provide %}` tag to define the data we want to "provide" (ma
|
|
|
1692
1810
|
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
1811
|
|
|
1694
1812
|
`provide` tag _key_, similarly to the _name_ argument in `component` or `slot` tags, has these requirements:
|
|
1813
|
+
|
|
1695
1814
|
- The _key_ must be a string literal
|
|
1696
1815
|
- It must be a valid identifier (AKA a valid Python variable name)
|
|
1697
1816
|
|
|
@@ -1699,9 +1818,10 @@ Once you've set the name, you define the data you want to "provide" by passing i
|
|
|
1699
1818
|
|
|
1700
1819
|
> NOTE: Kwargs passed to `{% provide %}` are NOT added to the context.
|
|
1701
1820
|
> In the example below, the `{{ key }}` won't render anything:
|
|
1821
|
+
>
|
|
1702
1822
|
> ```django
|
|
1703
1823
|
> {% provide "my_data" key="hi" another=123 %}
|
|
1704
|
-
> {{ key }}
|
|
1824
|
+
> {{ key }}
|
|
1705
1825
|
> {% endprovide %}
|
|
1706
1826
|
> ```
|
|
1707
1827
|
|
|
@@ -1714,7 +1834,7 @@ For a component to be able to "inject" some data, the component (`{% component %
|
|
|
1714
1834
|
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
1835
|
|
|
1716
1836
|
```py
|
|
1717
|
-
class ChildComponent(
|
|
1837
|
+
class ChildComponent(Component):
|
|
1718
1838
|
def get_context_data(self):
|
|
1719
1839
|
my_data = self.inject("my_data")
|
|
1720
1840
|
print(my_data.key) # hi
|
|
@@ -1729,7 +1849,7 @@ with given key is found, `inject` raises a `KeyError`.
|
|
|
1729
1849
|
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
1850
|
|
|
1731
1851
|
```py
|
|
1732
|
-
class ChildComponent(
|
|
1852
|
+
class ChildComponent(Component):
|
|
1733
1853
|
def get_context_data(self):
|
|
1734
1854
|
my_data = self.inject("invalid_key", DEFAULT_DATA)
|
|
1735
1855
|
assert my_data == DEFAUKT_DATA
|
|
@@ -1741,12 +1861,11 @@ have all the keys that were passed to the `provide` tag.
|
|
|
1741
1861
|
|
|
1742
1862
|
> NOTE: `inject()` works strictly only in `get_context_data`. If you try to call it from elsewhere, it will raise an error.
|
|
1743
1863
|
|
|
1744
|
-
|
|
1745
1864
|
### Full example
|
|
1746
1865
|
|
|
1747
1866
|
```py
|
|
1748
|
-
@
|
|
1749
|
-
class ChildComponent(
|
|
1867
|
+
@register("child")
|
|
1868
|
+
class ChildComponent(Component):
|
|
1750
1869
|
template = """
|
|
1751
1870
|
<div> {{ my_data.key }} </div>
|
|
1752
1871
|
<div> {{ my_data.another }} </div>
|
|
@@ -1768,15 +1887,15 @@ template_str = """
|
|
|
1768
1887
|
renders:
|
|
1769
1888
|
|
|
1770
1889
|
```html
|
|
1771
|
-
<div>
|
|
1772
|
-
<div>
|
|
1890
|
+
<div>hi</div>
|
|
1891
|
+
<div>123</div>
|
|
1773
1892
|
```
|
|
1774
1893
|
|
|
1775
1894
|
## Component context and scope
|
|
1776
1895
|
|
|
1777
1896
|
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
1897
|
|
|
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.
|
|
1898
|
+
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
1899
|
|
|
1781
1900
|
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
1901
|
|
|
@@ -1795,6 +1914,7 @@ Components can also access the outer context in their context methods like `get_
|
|
|
1795
1914
|
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
1915
|
|
|
1797
1916
|
To be familiar with how Django handles static files, we recommend reading also:
|
|
1917
|
+
|
|
1798
1918
|
- [How to manage static files (e.g. images, JavaScript, CSS)](https://docs.djangoproject.com/en/5.0/howto/static-files/)
|
|
1799
1919
|
|
|
1800
1920
|
### Defining file paths relative to component or static dirs
|
|
@@ -1804,10 +1924,10 @@ files with a component, you set them as `template_name`, `Media.js` and `Media.c
|
|
|
1804
1924
|
|
|
1805
1925
|
```py
|
|
1806
1926
|
# In a file [project root]/components/calendar/calendar.py
|
|
1807
|
-
from django_components import
|
|
1927
|
+
from django_components import Component, register
|
|
1808
1928
|
|
|
1809
|
-
@
|
|
1810
|
-
class Calendar(
|
|
1929
|
+
@register("calendar")
|
|
1930
|
+
class Calendar(Component):
|
|
1811
1931
|
template_name = "template.html"
|
|
1812
1932
|
|
|
1813
1933
|
class Media:
|
|
@@ -1823,10 +1943,10 @@ Assuming that `STATICFILES_DIRS` contains path `[project root]/components`, we c
|
|
|
1823
1943
|
|
|
1824
1944
|
```py
|
|
1825
1945
|
# In a file [project root]/components/calendar/calendar.py
|
|
1826
|
-
from django_components import
|
|
1946
|
+
from django_components import Component, register
|
|
1827
1947
|
|
|
1828
|
-
@
|
|
1829
|
-
class Calendar(
|
|
1948
|
+
@register("calendar")
|
|
1949
|
+
class Calendar(Component):
|
|
1830
1950
|
template_name = "calendar/template.html"
|
|
1831
1951
|
|
|
1832
1952
|
class Media:
|
|
@@ -1841,7 +1961,7 @@ NOTE: In case of conflict, the preference goes to resolving the files relative t
|
|
|
1841
1961
|
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
1962
|
|
|
1843
1963
|
```py
|
|
1844
|
-
class MyComponent(
|
|
1964
|
+
class MyComponent(Component):
|
|
1845
1965
|
class Media:
|
|
1846
1966
|
js = ["path/to/script1.js", "path/to/script2.js"]
|
|
1847
1967
|
css = ["path/to/style1.css", "path/to/style2.css"]
|
|
@@ -1857,7 +1977,7 @@ See the corresponding [Django Documentation](https://docs.djangoproject.com/en/5
|
|
|
1857
1977
|
Again, you can set either a single file or a list of files per media type:
|
|
1858
1978
|
|
|
1859
1979
|
```py
|
|
1860
|
-
class MyComponent(
|
|
1980
|
+
class MyComponent(Component):
|
|
1861
1981
|
class Media:
|
|
1862
1982
|
css = {
|
|
1863
1983
|
"all": "path/to/style1.css",
|
|
@@ -1866,7 +1986,7 @@ class MyComponent(component.Component):
|
|
|
1866
1986
|
```
|
|
1867
1987
|
|
|
1868
1988
|
```py
|
|
1869
|
-
class MyComponent(
|
|
1989
|
+
class MyComponent(Component):
|
|
1870
1990
|
class Media:
|
|
1871
1991
|
css = {
|
|
1872
1992
|
"all": ["path/to/style1.css", "path/to/style2.css"],
|
|
@@ -1876,10 +1996,10 @@ class MyComponent(component.Component):
|
|
|
1876
1996
|
|
|
1877
1997
|
NOTE: When you define CSS as a string or a list, the `all` media type is implied.
|
|
1878
1998
|
|
|
1879
|
-
|
|
1880
1999
|
### Supported types for file paths
|
|
1881
2000
|
|
|
1882
2001
|
File paths can be any of:
|
|
2002
|
+
|
|
1883
2003
|
- `str`
|
|
1884
2004
|
- `bytes`
|
|
1885
2005
|
- `PathLike` (`__fspath__` method)
|
|
@@ -1891,7 +2011,7 @@ from pathlib import Path
|
|
|
1891
2011
|
|
|
1892
2012
|
from django.utils.safestring import mark_safe
|
|
1893
2013
|
|
|
1894
|
-
class SimpleComponent(
|
|
2014
|
+
class SimpleComponent(Component):
|
|
1895
2015
|
class Media:
|
|
1896
2016
|
css = [
|
|
1897
2017
|
mark_safe('<link href="/static/calendar/style.css" rel="stylesheet" />'),
|
|
@@ -1930,8 +2050,8 @@ class LazyJsPath:
|
|
|
1930
2050
|
f'<script type="module" src="{full_path}"></script>'
|
|
1931
2051
|
)
|
|
1932
2052
|
|
|
1933
|
-
@
|
|
1934
|
-
class Calendar(
|
|
2053
|
+
@register("calendar")
|
|
2054
|
+
class Calendar(Component):
|
|
1935
2055
|
template_name = "calendar/template.html"
|
|
1936
2056
|
|
|
1937
2057
|
def get_context_data(self, date):
|
|
@@ -1943,7 +2063,7 @@ class Calendar(component.Component):
|
|
|
1943
2063
|
css = "calendar/style.css"
|
|
1944
2064
|
js = [
|
|
1945
2065
|
# <script> tag constructed by Media class
|
|
1946
|
-
"calendar/script1.js",
|
|
2066
|
+
"calendar/script1.js",
|
|
1947
2067
|
# Custom <script> tag
|
|
1948
2068
|
LazyJsPath("calendar/script2.js"),
|
|
1949
2069
|
]
|
|
@@ -1959,7 +2079,7 @@ To change how the tags are constructed, you can override the [`Media.render_js`
|
|
|
1959
2079
|
|
|
1960
2080
|
```py
|
|
1961
2081
|
from django.forms.widgets import Media
|
|
1962
|
-
from django_components import
|
|
2082
|
+
from django_components import Component, register
|
|
1963
2083
|
|
|
1964
2084
|
class MyMedia(Media):
|
|
1965
2085
|
# Same as original Media.render_js, except
|
|
@@ -1976,14 +2096,14 @@ class MyMedia(Media):
|
|
|
1976
2096
|
)
|
|
1977
2097
|
return tags
|
|
1978
2098
|
|
|
1979
|
-
@
|
|
1980
|
-
class Calendar(
|
|
2099
|
+
@register("calendar")
|
|
2100
|
+
class Calendar(Component):
|
|
1981
2101
|
template_name = "calendar/template.html"
|
|
1982
2102
|
|
|
1983
2103
|
class Media:
|
|
1984
2104
|
css = "calendar/style.css"
|
|
1985
2105
|
js = "calendar/script.js"
|
|
1986
|
-
|
|
2106
|
+
|
|
1987
2107
|
# Override the behavior of Media class
|
|
1988
2108
|
media_class = MyMedia
|
|
1989
2109
|
```
|
|
@@ -1994,6 +2114,7 @@ NOTE: The instance of the `Media` class (or it's subclass) is available under `C
|
|
|
1994
2114
|
|
|
1995
2115
|
The JS and CSS files included in components are not automatically rendered.
|
|
1996
2116
|
Instead, use the following tags to specify where to render the dependencies:
|
|
2117
|
+
|
|
1997
2118
|
- `component_dependencies` - Renders both JS and CSS
|
|
1998
2119
|
- `component_js_dependencies` - Renders only JS
|
|
1999
2120
|
- `component_css_dependencies` - Reneders only CSS
|
|
@@ -2045,16 +2166,16 @@ COMPONENTS = {
|
|
|
2045
2166
|
Where `mysite/components/forms.py` may look like this:
|
|
2046
2167
|
|
|
2047
2168
|
```py
|
|
2048
|
-
@
|
|
2049
|
-
class FormSimple(
|
|
2169
|
+
@register("form_simple")
|
|
2170
|
+
class FormSimple(Component):
|
|
2050
2171
|
template = """
|
|
2051
2172
|
<form>
|
|
2052
2173
|
...
|
|
2053
2174
|
</form>
|
|
2054
2175
|
"""
|
|
2055
2176
|
|
|
2056
|
-
@
|
|
2057
|
-
class FormOther(
|
|
2177
|
+
@register("form_other")
|
|
2178
|
+
class FormOther(Component):
|
|
2058
2179
|
template = """
|
|
2059
2180
|
<form>
|
|
2060
2181
|
...
|
|
@@ -2104,15 +2225,17 @@ This has two modes:
|
|
|
2104
2225
|
|
|
2105
2226
|
- `"django"` - Default - The default Django template behavior.
|
|
2106
2227
|
|
|
2107
|
-
|
|
2108
|
-
|
|
2109
|
-
|
|
2228
|
+
Inside the `{% fill %}` tag, the context variables you can access are a union of:
|
|
2229
|
+
|
|
2230
|
+
- All the variables that were OUTSIDE the fill tag, including any loops or with tag
|
|
2231
|
+
- Data returned from `get_context_data()` of the component that wraps the fill tag.
|
|
2110
2232
|
|
|
2111
2233
|
- `"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
2234
|
|
|
2113
|
-
|
|
2114
|
-
|
|
2115
|
-
|
|
2235
|
+
Inside the `{% fill %}` tag, you can ONLY access variables from 2 places:
|
|
2236
|
+
|
|
2237
|
+
- `get_context_data()` of the component which defined the template (AKA the "root" component)
|
|
2238
|
+
- Any loops (`{% for ... %}`) that the `{% fill %}` tag is part of.
|
|
2116
2239
|
|
|
2117
2240
|
```python
|
|
2118
2241
|
COMPONENTS = {
|
|
@@ -2125,7 +2248,7 @@ COMPONENTS = {
|
|
|
2125
2248
|
Given this template:
|
|
2126
2249
|
|
|
2127
2250
|
```py
|
|
2128
|
-
class RootComp(
|
|
2251
|
+
class RootComp(Component):
|
|
2129
2252
|
template = """
|
|
2130
2253
|
{% with cheese="feta" %}
|
|
2131
2254
|
{% component 'my_comp' %}
|
|
@@ -2162,7 +2285,7 @@ all the data defined in the outer layers, like the `{% with %}` tag.
|
|
|
2162
2285
|
Given this template:
|
|
2163
2286
|
|
|
2164
2287
|
```py
|
|
2165
|
-
class RootComp(
|
|
2288
|
+
class RootComp(Component):
|
|
2166
2289
|
template = """
|
|
2167
2290
|
{% with cheese="feta" %}
|
|
2168
2291
|
{% component 'my_comp' %}
|