django-components 0.78__tar.gz → 0.80__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.78/src/django_components.egg-info → django_components-0.80}/PKG-INFO +192 -42
- {django_components-0.78 → django_components-0.80}/README.md +191 -41
- {django_components-0.78 → django_components-0.80}/pyproject.toml +1 -1
- {django_components-0.78 → django_components-0.80}/src/django_components/app_settings.py +1 -1
- {django_components-0.78 → django_components-0.80}/src/django_components/component.py +64 -4
- django_components-0.80/src/django_components/context.py +136 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/logger.py +1 -1
- django_components-0.80/src/django_components/provide.py +52 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/templatetags/component_tags.py +51 -0
- {django_components-0.78 → django_components-0.80/src/django_components.egg-info}/PKG-INFO +192 -42
- {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/SOURCES.txt +2 -0
- {django_components-0.78 → django_components-0.80}/tests/test_templatetags.py +39 -0
- django_components-0.80/tests/test_templatetags_provide.py +601 -0
- django_components-0.78/src/django_components/context.py +0 -64
- {django_components-0.78 → django_components-0.80}/LICENSE +0 -0
- {django_components-0.78 → django_components-0.80}/setup.cfg +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/__init__.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/apps.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/attributes.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/component_registry.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/expression.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/management/__init__.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/middleware.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/node.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/py.typed +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/slots.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/template_loader.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/template_parser.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/types.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components/utils.py +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_attributes.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_autodiscover.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_command_startcomponent.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_component.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_component_as_view.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_component_media.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_context.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_registry.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_settings.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_template_parser.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_templatetags_component.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_templatetags_slot_fill.py +0 -0
- {django_components-0.78 → django_components-0.80}/tests/test_templatetags_templating.py +0 -0
- {django_components-0.78 → django_components-0.80}/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.80
|
|
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
|
|
@@ -57,6 +57,7 @@ Read on to learn about the details!
|
|
|
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
|
+
- [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
|
|
60
61
|
- [Component context and scope](#component-context-and-scope)
|
|
61
62
|
- [Rendering JS and CSS dependencies](#rendering-js-and-css-dependencies)
|
|
62
63
|
- [Available settings](#available-settings)
|
|
@@ -68,6 +69,13 @@ Read on to learn about the details!
|
|
|
68
69
|
|
|
69
70
|
## Release notes
|
|
70
71
|
|
|
72
|
+
**Version 0.80** introduces dependency injection with the `{% provide %}` tag and `inject()` method.
|
|
73
|
+
|
|
74
|
+
🚨📢 **Version 0.79**
|
|
75
|
+
|
|
76
|
+
- 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).
|
|
77
|
+
|
|
78
|
+
|
|
71
79
|
🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
|
|
72
80
|
- Previously, the syntax was
|
|
73
81
|
`{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
|
|
@@ -1382,11 +1390,140 @@ attributes_to_string(attrs)
|
|
|
1382
1390
|
# 'class="my-class text-red pa-4" data-id="123" required'
|
|
1383
1391
|
```
|
|
1384
1392
|
|
|
1393
|
+
## Prop drilling and dependency injection (provide / inject)
|
|
1394
|
+
|
|
1395
|
+
_New in version 0.80_:
|
|
1396
|
+
|
|
1397
|
+
Django components supports dependency injection with the combination of:
|
|
1398
|
+
1. `{% provide %}` tag
|
|
1399
|
+
1. `inject()` method of the `Component` class
|
|
1400
|
+
|
|
1401
|
+
### What is "dependency injection" and "prop drilling"?
|
|
1402
|
+
|
|
1403
|
+
Prop drilling refers to a scenario in UI development where you need to pass data through many layers of a component tree to reach the nested components that actually need the data.
|
|
1404
|
+
|
|
1405
|
+
Normally, you'd use props to send data from a parent component to its children. However, this straightforward method becomes cumbersome and inefficient if the data has to travel through many levels or if several components scattered at different depths all need the same piece of information.
|
|
1406
|
+
|
|
1407
|
+
This results in a situation where the intermediate components, which don't need the data for their own functioning, end up having to manage and pass along these props. This clutters the component tree and makes the code verbose and harder to manage.
|
|
1408
|
+
|
|
1409
|
+
A neat solution to avoid prop drilling is using the "provide and inject" technique, AKA dependency injection.
|
|
1410
|
+
|
|
1411
|
+
With dependency injection, a parent component acts like a data hub for all its descendants. This setup allows any component, no matter how deeply nested it is, to access the required data directly from this centralized provider without having to messily pass props down the chain. This approach significantly cleans up the code and makes it easier to maintain.
|
|
1412
|
+
|
|
1413
|
+
This feature is inspired by Vue's [Provide / Inject](https://vuejs.org/guide/components/provide-inject) and React's [Context / useContext](https://react.dev/learn/passing-data-deeply-with-context).
|
|
1414
|
+
|
|
1415
|
+
### How to use provide / inject
|
|
1416
|
+
|
|
1417
|
+
As the name suggest, using provide / inject consists of 2 steps
|
|
1418
|
+
1. Providing data
|
|
1419
|
+
2. Injecting provided data
|
|
1420
|
+
|
|
1421
|
+
For examples of advanced uses of provide / inject, [see this discussion](https://github.com/EmilStenstrom/django-components/pull/506#issuecomment-2132102584).
|
|
1422
|
+
|
|
1423
|
+
### Using `{% provide %}` tag
|
|
1424
|
+
|
|
1425
|
+
First we use the `{% provide %}` tag to define the data we want to "provide" (make available).
|
|
1426
|
+
|
|
1427
|
+
```django
|
|
1428
|
+
{% provide "my_data" key="hi" another=123 %}
|
|
1429
|
+
{% component "child" %} <--- Can access "my_data"
|
|
1430
|
+
{% endcomponent %}
|
|
1431
|
+
{% endprovide %}
|
|
1432
|
+
|
|
1433
|
+
{% component "child" %} <--- Cannot access "my_data"
|
|
1434
|
+
{% endcomponent %}
|
|
1435
|
+
```
|
|
1436
|
+
|
|
1437
|
+
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.
|
|
1438
|
+
|
|
1439
|
+
`provide` tag _key_, similarly to the _name_ argument in `component` or `slot` tags, has these requirements:
|
|
1440
|
+
- The _key_ must be a string literal
|
|
1441
|
+
- It must be a valid identifier (AKA a valid Python variable name)
|
|
1442
|
+
|
|
1443
|
+
Once you've set the name, you define the data you want to "provide" by passing it as keyword arguments. This is similar to how you pass data to the `{% with %}` tag.
|
|
1444
|
+
|
|
1445
|
+
> NOTE: Kwargs passed to `{% provide %}` are NOT added to the context.
|
|
1446
|
+
> In the example below, the `{{ key }}` won't render anything:
|
|
1447
|
+
> ```django
|
|
1448
|
+
> {% provide "my_data" key="hi" another=123 %}
|
|
1449
|
+
> {{ key }}
|
|
1450
|
+
> {% endprovide %}
|
|
1451
|
+
> ```
|
|
1452
|
+
|
|
1453
|
+
### Using `inject()` method
|
|
1454
|
+
|
|
1455
|
+
To "inject" (access) the data defined on the `provide` tag, you can use the `inject()` method inside of `get_context_data()`.
|
|
1456
|
+
|
|
1457
|
+
For a component to be able to "inject" some data, the component (`{% component %}` tag) must be nested inside the `{% provide %}` tag.
|
|
1458
|
+
|
|
1459
|
+
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`.
|
|
1460
|
+
|
|
1461
|
+
```py
|
|
1462
|
+
class ChildComponent(component.Component):
|
|
1463
|
+
def get_context_data(self):
|
|
1464
|
+
my_data = self.inject("my_data")
|
|
1465
|
+
print(my_data.key) # hi
|
|
1466
|
+
print(my_data.another) # 123
|
|
1467
|
+
return {}
|
|
1468
|
+
```
|
|
1469
|
+
|
|
1470
|
+
First argument to `inject` is the _key_ of the provided data. This
|
|
1471
|
+
must match the string that you used in the `provide` tag. If no provider
|
|
1472
|
+
with given key is found, `inject` raises a `KeyError`.
|
|
1473
|
+
|
|
1474
|
+
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)`:
|
|
1475
|
+
|
|
1476
|
+
```py
|
|
1477
|
+
class ChildComponent(component.Component):
|
|
1478
|
+
def get_context_data(self):
|
|
1479
|
+
my_data = self.inject("invalid_key", DEFAULT_DATA)
|
|
1480
|
+
assert my_data == DEFAUKT_DATA
|
|
1481
|
+
return {}
|
|
1482
|
+
```
|
|
1483
|
+
|
|
1484
|
+
The instance returned from `inject()` is a subclass of `NamedTuple`, so the instance is immutable. This ensures that the data returned from `inject` will always
|
|
1485
|
+
have all the keys that were passed to the `provide` tag.
|
|
1486
|
+
|
|
1487
|
+
> NOTE: `inject()` works strictly only in `get_context_data`. If you try to call it from elsewhere, it will raise an error.
|
|
1488
|
+
|
|
1489
|
+
|
|
1490
|
+
### Full example
|
|
1491
|
+
|
|
1492
|
+
```py
|
|
1493
|
+
@component.register("child")
|
|
1494
|
+
class ChildComponent(component.Component):
|
|
1495
|
+
template = """
|
|
1496
|
+
<div> {{ my_data.key }} </div>
|
|
1497
|
+
<div> {{ my_data.another }} </div>
|
|
1498
|
+
"""
|
|
1499
|
+
|
|
1500
|
+
def get_context_data(self):
|
|
1501
|
+
my_data = self.inject("my_data", "default")
|
|
1502
|
+
return {"my_data": my_data}
|
|
1503
|
+
|
|
1504
|
+
template_str = """
|
|
1505
|
+
{% load component_tags %}
|
|
1506
|
+
{% provide "my_data" key="hi" another=123 %}
|
|
1507
|
+
{% component "child" %}
|
|
1508
|
+
{% endcomponent %}
|
|
1509
|
+
{% endprovide %}
|
|
1510
|
+
"""
|
|
1511
|
+
```
|
|
1512
|
+
|
|
1513
|
+
renders:
|
|
1514
|
+
|
|
1515
|
+
```html
|
|
1516
|
+
<div> hi </div>
|
|
1517
|
+
<div> 123 </div>
|
|
1518
|
+
```
|
|
1519
|
+
|
|
1385
1520
|
## Component context and scope
|
|
1386
1521
|
|
|
1387
|
-
By default,
|
|
1522
|
+
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.
|
|
1523
|
+
|
|
1524
|
+
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.
|
|
1388
1525
|
|
|
1389
|
-
|
|
1526
|
+
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:
|
|
1390
1527
|
|
|
1391
1528
|
```htmldjango
|
|
1392
1529
|
{% component "calendar" date="2015-06-19" only %}{% endcomponent %}
|
|
@@ -1394,7 +1531,9 @@ You can set the [context_behavior](#context-behavior) option to `"django"`, to m
|
|
|
1394
1531
|
|
|
1395
1532
|
NOTE: `{% csrf_token %}` tags need access to the top-level context, and they will not function properly if they are rendered in a component that is called with the `only` modifier.
|
|
1396
1533
|
|
|
1397
|
-
|
|
1534
|
+
If you find yourself using the `only` modifier often, you can set the [context_behavior](#context-behavior) option to `"isolated"`, which automatically applies the `only` modifier. This is useful if you want to make sure that components don't accidentally access the outer context.
|
|
1535
|
+
|
|
1536
|
+
Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
|
|
1398
1537
|
|
|
1399
1538
|
## Rendering JS and CSS dependencies
|
|
1400
1539
|
|
|
@@ -1472,15 +1611,25 @@ COMPONENTS = {
|
|
|
1472
1611
|
|
|
1473
1612
|
> NOTE: `context_behavior` and `slot_context_behavior` options were merged in v0.70.
|
|
1474
1613
|
>
|
|
1475
|
-
> If you are migrating from BEFORE v0.67, set `context_behavior` to `"django"`. From v0.67
|
|
1614
|
+
> If you are migrating from BEFORE v0.67, set `context_behavior` to `"django"`. From v0.67 to v0.78 (incl) the default value was `"isolated"`.
|
|
1615
|
+
>
|
|
1616
|
+
> For v0.79 and later, the default is again `"django"`. See the rationale for change [here](https://github.com/EmilStenstrom/django-components/issues/498).
|
|
1476
1617
|
|
|
1477
1618
|
You can configure what variables are available inside the `{% fill %}` tags. See [Component context and scope](#component-context-and-scope).
|
|
1478
1619
|
|
|
1479
1620
|
This has two modes:
|
|
1480
1621
|
|
|
1481
|
-
- `"django"` -
|
|
1622
|
+
- `"django"` - Default - The default Django template behavior.
|
|
1623
|
+
|
|
1624
|
+
Inside the `{% fill %}` tag, the context variables you can access are a union of:
|
|
1625
|
+
- All the variables that were OUTSIDE the fill tag, including any loops or with tag
|
|
1626
|
+
- Data returned from `get_context_data()` of the component that wraps the fill tag.
|
|
1482
1627
|
|
|
1483
|
-
- `"isolated"` -
|
|
1628
|
+
- `"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.
|
|
1629
|
+
|
|
1630
|
+
Inside the `{% fill %}` tag, you can ONLY access variables from 2 places:
|
|
1631
|
+
- `get_context_data()` of the component which defined the template (AKA the "root" component)
|
|
1632
|
+
- Any loops (`{% for ... %}`) that the `{% fill %}` tag is part of.
|
|
1484
1633
|
|
|
1485
1634
|
```python
|
|
1486
1635
|
COMPONENTS = {
|
|
@@ -1490,75 +1639,76 @@ COMPONENTS = {
|
|
|
1490
1639
|
|
|
1491
1640
|
#### Example "django"
|
|
1492
1641
|
|
|
1493
|
-
Given this template
|
|
1494
|
-
|
|
1495
|
-
```django
|
|
1496
|
-
{% with cheese="feta" %}
|
|
1497
|
-
{% component 'my_comp' %}
|
|
1498
|
-
{{ my_var }} # my_var
|
|
1499
|
-
{{ cheese }} # cheese
|
|
1500
|
-
{% endcomponent %}
|
|
1501
|
-
{% endwith %}
|
|
1502
|
-
```
|
|
1503
|
-
|
|
1504
|
-
and this context returned from the `get_context_data()` method
|
|
1642
|
+
Given this template:
|
|
1505
1643
|
|
|
1506
1644
|
```py
|
|
1507
|
-
|
|
1645
|
+
class RootComp(component.Component):
|
|
1646
|
+
template = """
|
|
1647
|
+
{% with cheese="feta" %}
|
|
1648
|
+
{% component 'my_comp' %}
|
|
1649
|
+
{{ my_var }} # my_var
|
|
1650
|
+
{{ cheese }} # cheese
|
|
1651
|
+
{% endcomponent %}
|
|
1652
|
+
{% endwith %}
|
|
1653
|
+
"""
|
|
1654
|
+
def get_context_data(self):
|
|
1655
|
+
return { "my_var": 123 }
|
|
1508
1656
|
```
|
|
1509
1657
|
|
|
1510
|
-
Then if component "my_comp"
|
|
1658
|
+
Then if `get_context_data()` of the component `"my_comp"` returns following data:
|
|
1511
1659
|
|
|
1512
1660
|
```py
|
|
1513
1661
|
{ "my_var": 456 }
|
|
1514
1662
|
```
|
|
1515
1663
|
|
|
1516
|
-
Then
|
|
1664
|
+
Then the template will be rendered as:
|
|
1517
1665
|
|
|
1518
1666
|
```django
|
|
1519
1667
|
456 # my_var
|
|
1520
1668
|
feta # cheese
|
|
1521
1669
|
```
|
|
1522
1670
|
|
|
1523
|
-
Because "my_comp"
|
|
1671
|
+
Because `"my_comp"` overshadows the variable `"my_var"`,
|
|
1524
1672
|
so `{{ my_var }}` equals `456`.
|
|
1525
|
-
And variable "cheese" equals `feta`, because the fill CAN access
|
|
1526
|
-
the current context.
|
|
1527
|
-
|
|
1528
|
-
#### Example "isolated"
|
|
1529
1673
|
|
|
1530
|
-
|
|
1674
|
+
And variable `"cheese"` equals `feta`, because the fill CAN access
|
|
1675
|
+
all the data defined in the outer layers, like the `{% with %}` tag.
|
|
1531
1676
|
|
|
1532
|
-
|
|
1533
|
-
{% with cheese="feta" %}
|
|
1534
|
-
{% component 'my_comp' %}
|
|
1535
|
-
{{ my_var }} # my_var
|
|
1536
|
-
{{ cheese }} # cheese
|
|
1537
|
-
{% endcomponent %}
|
|
1538
|
-
{% endwith %}
|
|
1539
|
-
```
|
|
1677
|
+
#### Example "isolated"
|
|
1540
1678
|
|
|
1541
|
-
|
|
1679
|
+
Given this template:
|
|
1542
1680
|
|
|
1543
1681
|
```py
|
|
1544
|
-
|
|
1682
|
+
class RootComp(component.Component):
|
|
1683
|
+
template = """
|
|
1684
|
+
{% with cheese="feta" %}
|
|
1685
|
+
{% component 'my_comp' %}
|
|
1686
|
+
{{ my_var }} # my_var
|
|
1687
|
+
{{ cheese }} # cheese
|
|
1688
|
+
{% endcomponent %}
|
|
1689
|
+
{% endwith %}
|
|
1690
|
+
"""
|
|
1691
|
+
def get_context_data(self):
|
|
1692
|
+
return { "my_var": 123 }
|
|
1545
1693
|
```
|
|
1546
1694
|
|
|
1547
|
-
Then if component "my_comp"
|
|
1695
|
+
Then if `get_context_data()` of the component `"my_comp"` returns following data:
|
|
1548
1696
|
|
|
1549
1697
|
```py
|
|
1550
1698
|
{ "my_var": 456 }
|
|
1551
1699
|
```
|
|
1552
1700
|
|
|
1553
|
-
Then
|
|
1701
|
+
Then the template will be rendered as:
|
|
1554
1702
|
|
|
1555
1703
|
```django
|
|
1556
1704
|
123 # my_var
|
|
1557
1705
|
# cheese
|
|
1558
1706
|
```
|
|
1559
1707
|
|
|
1560
|
-
Because
|
|
1561
|
-
But since "cheese" is not defined there, it's empty.
|
|
1708
|
+
Because variables `"my_var"` and `"cheese"` are searched only inside `RootComponent.get_context_data()`.
|
|
1709
|
+
But since `"cheese"` is not defined there, it's empty.
|
|
1710
|
+
|
|
1711
|
+
Notice that the variables defined with the `{% with %}` tag are ignored inside the `{% fill %}` tag with the `"isolated"` mode.
|
|
1562
1712
|
|
|
1563
1713
|
## Logging and debugging
|
|
1564
1714
|
|
|
@@ -33,6 +33,7 @@ Read on to learn about the details!
|
|
|
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
|
+
- [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
|
|
36
37
|
- [Component context and scope](#component-context-and-scope)
|
|
37
38
|
- [Rendering JS and CSS dependencies](#rendering-js-and-css-dependencies)
|
|
38
39
|
- [Available settings](#available-settings)
|
|
@@ -44,6 +45,13 @@ Read on to learn about the details!
|
|
|
44
45
|
|
|
45
46
|
## Release notes
|
|
46
47
|
|
|
48
|
+
**Version 0.80** introduces dependency injection with the `{% provide %}` tag and `inject()` method.
|
|
49
|
+
|
|
50
|
+
🚨📢 **Version 0.79**
|
|
51
|
+
|
|
52
|
+
- 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).
|
|
53
|
+
|
|
54
|
+
|
|
47
55
|
🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
|
|
48
56
|
- Previously, the syntax was
|
|
49
57
|
`{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
|
|
@@ -1358,11 +1366,140 @@ attributes_to_string(attrs)
|
|
|
1358
1366
|
# 'class="my-class text-red pa-4" data-id="123" required'
|
|
1359
1367
|
```
|
|
1360
1368
|
|
|
1369
|
+
## Prop drilling and dependency injection (provide / inject)
|
|
1370
|
+
|
|
1371
|
+
_New in version 0.80_:
|
|
1372
|
+
|
|
1373
|
+
Django components supports dependency injection with the combination of:
|
|
1374
|
+
1. `{% provide %}` tag
|
|
1375
|
+
1. `inject()` method of the `Component` class
|
|
1376
|
+
|
|
1377
|
+
### What is "dependency injection" and "prop drilling"?
|
|
1378
|
+
|
|
1379
|
+
Prop drilling refers to a scenario in UI development where you need to pass data through many layers of a component tree to reach the nested components that actually need the data.
|
|
1380
|
+
|
|
1381
|
+
Normally, you'd use props to send data from a parent component to its children. However, this straightforward method becomes cumbersome and inefficient if the data has to travel through many levels or if several components scattered at different depths all need the same piece of information.
|
|
1382
|
+
|
|
1383
|
+
This results in a situation where the intermediate components, which don't need the data for their own functioning, end up having to manage and pass along these props. This clutters the component tree and makes the code verbose and harder to manage.
|
|
1384
|
+
|
|
1385
|
+
A neat solution to avoid prop drilling is using the "provide and inject" technique, AKA dependency injection.
|
|
1386
|
+
|
|
1387
|
+
With dependency injection, a parent component acts like a data hub for all its descendants. This setup allows any component, no matter how deeply nested it is, to access the required data directly from this centralized provider without having to messily pass props down the chain. This approach significantly cleans up the code and makes it easier to maintain.
|
|
1388
|
+
|
|
1389
|
+
This feature is inspired by Vue's [Provide / Inject](https://vuejs.org/guide/components/provide-inject) and React's [Context / useContext](https://react.dev/learn/passing-data-deeply-with-context).
|
|
1390
|
+
|
|
1391
|
+
### How to use provide / inject
|
|
1392
|
+
|
|
1393
|
+
As the name suggest, using provide / inject consists of 2 steps
|
|
1394
|
+
1. Providing data
|
|
1395
|
+
2. Injecting provided data
|
|
1396
|
+
|
|
1397
|
+
For examples of advanced uses of provide / inject, [see this discussion](https://github.com/EmilStenstrom/django-components/pull/506#issuecomment-2132102584).
|
|
1398
|
+
|
|
1399
|
+
### Using `{% provide %}` tag
|
|
1400
|
+
|
|
1401
|
+
First we use the `{% provide %}` tag to define the data we want to "provide" (make available).
|
|
1402
|
+
|
|
1403
|
+
```django
|
|
1404
|
+
{% provide "my_data" key="hi" another=123 %}
|
|
1405
|
+
{% component "child" %} <--- Can access "my_data"
|
|
1406
|
+
{% endcomponent %}
|
|
1407
|
+
{% endprovide %}
|
|
1408
|
+
|
|
1409
|
+
{% component "child" %} <--- Cannot access "my_data"
|
|
1410
|
+
{% endcomponent %}
|
|
1411
|
+
```
|
|
1412
|
+
|
|
1413
|
+
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.
|
|
1414
|
+
|
|
1415
|
+
`provide` tag _key_, similarly to the _name_ argument in `component` or `slot` tags, has these requirements:
|
|
1416
|
+
- The _key_ must be a string literal
|
|
1417
|
+
- It must be a valid identifier (AKA a valid Python variable name)
|
|
1418
|
+
|
|
1419
|
+
Once you've set the name, you define the data you want to "provide" by passing it as keyword arguments. This is similar to how you pass data to the `{% with %}` tag.
|
|
1420
|
+
|
|
1421
|
+
> NOTE: Kwargs passed to `{% provide %}` are NOT added to the context.
|
|
1422
|
+
> In the example below, the `{{ key }}` won't render anything:
|
|
1423
|
+
> ```django
|
|
1424
|
+
> {% provide "my_data" key="hi" another=123 %}
|
|
1425
|
+
> {{ key }}
|
|
1426
|
+
> {% endprovide %}
|
|
1427
|
+
> ```
|
|
1428
|
+
|
|
1429
|
+
### Using `inject()` method
|
|
1430
|
+
|
|
1431
|
+
To "inject" (access) the data defined on the `provide` tag, you can use the `inject()` method inside of `get_context_data()`.
|
|
1432
|
+
|
|
1433
|
+
For a component to be able to "inject" some data, the component (`{% component %}` tag) must be nested inside the `{% provide %}` tag.
|
|
1434
|
+
|
|
1435
|
+
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`.
|
|
1436
|
+
|
|
1437
|
+
```py
|
|
1438
|
+
class ChildComponent(component.Component):
|
|
1439
|
+
def get_context_data(self):
|
|
1440
|
+
my_data = self.inject("my_data")
|
|
1441
|
+
print(my_data.key) # hi
|
|
1442
|
+
print(my_data.another) # 123
|
|
1443
|
+
return {}
|
|
1444
|
+
```
|
|
1445
|
+
|
|
1446
|
+
First argument to `inject` is the _key_ of the provided data. This
|
|
1447
|
+
must match the string that you used in the `provide` tag. If no provider
|
|
1448
|
+
with given key is found, `inject` raises a `KeyError`.
|
|
1449
|
+
|
|
1450
|
+
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)`:
|
|
1451
|
+
|
|
1452
|
+
```py
|
|
1453
|
+
class ChildComponent(component.Component):
|
|
1454
|
+
def get_context_data(self):
|
|
1455
|
+
my_data = self.inject("invalid_key", DEFAULT_DATA)
|
|
1456
|
+
assert my_data == DEFAUKT_DATA
|
|
1457
|
+
return {}
|
|
1458
|
+
```
|
|
1459
|
+
|
|
1460
|
+
The instance returned from `inject()` is a subclass of `NamedTuple`, so the instance is immutable. This ensures that the data returned from `inject` will always
|
|
1461
|
+
have all the keys that were passed to the `provide` tag.
|
|
1462
|
+
|
|
1463
|
+
> NOTE: `inject()` works strictly only in `get_context_data`. If you try to call it from elsewhere, it will raise an error.
|
|
1464
|
+
|
|
1465
|
+
|
|
1466
|
+
### Full example
|
|
1467
|
+
|
|
1468
|
+
```py
|
|
1469
|
+
@component.register("child")
|
|
1470
|
+
class ChildComponent(component.Component):
|
|
1471
|
+
template = """
|
|
1472
|
+
<div> {{ my_data.key }} </div>
|
|
1473
|
+
<div> {{ my_data.another }} </div>
|
|
1474
|
+
"""
|
|
1475
|
+
|
|
1476
|
+
def get_context_data(self):
|
|
1477
|
+
my_data = self.inject("my_data", "default")
|
|
1478
|
+
return {"my_data": my_data}
|
|
1479
|
+
|
|
1480
|
+
template_str = """
|
|
1481
|
+
{% load component_tags %}
|
|
1482
|
+
{% provide "my_data" key="hi" another=123 %}
|
|
1483
|
+
{% component "child" %}
|
|
1484
|
+
{% endcomponent %}
|
|
1485
|
+
{% endprovide %}
|
|
1486
|
+
"""
|
|
1487
|
+
```
|
|
1488
|
+
|
|
1489
|
+
renders:
|
|
1490
|
+
|
|
1491
|
+
```html
|
|
1492
|
+
<div> hi </div>
|
|
1493
|
+
<div> 123 </div>
|
|
1494
|
+
```
|
|
1495
|
+
|
|
1361
1496
|
## Component context and scope
|
|
1362
1497
|
|
|
1363
|
-
By default,
|
|
1498
|
+
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.
|
|
1499
|
+
|
|
1500
|
+
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.
|
|
1364
1501
|
|
|
1365
|
-
|
|
1502
|
+
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:
|
|
1366
1503
|
|
|
1367
1504
|
```htmldjango
|
|
1368
1505
|
{% component "calendar" date="2015-06-19" only %}{% endcomponent %}
|
|
@@ -1370,7 +1507,9 @@ You can set the [context_behavior](#context-behavior) option to `"django"`, to m
|
|
|
1370
1507
|
|
|
1371
1508
|
NOTE: `{% csrf_token %}` tags need access to the top-level context, and they will not function properly if they are rendered in a component that is called with the `only` modifier.
|
|
1372
1509
|
|
|
1373
|
-
|
|
1510
|
+
If you find yourself using the `only` modifier often, you can set the [context_behavior](#context-behavior) option to `"isolated"`, which automatically applies the `only` modifier. This is useful if you want to make sure that components don't accidentally access the outer context.
|
|
1511
|
+
|
|
1512
|
+
Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
|
|
1374
1513
|
|
|
1375
1514
|
## Rendering JS and CSS dependencies
|
|
1376
1515
|
|
|
@@ -1448,15 +1587,25 @@ COMPONENTS = {
|
|
|
1448
1587
|
|
|
1449
1588
|
> NOTE: `context_behavior` and `slot_context_behavior` options were merged in v0.70.
|
|
1450
1589
|
>
|
|
1451
|
-
> If you are migrating from BEFORE v0.67, set `context_behavior` to `"django"`. From v0.67
|
|
1590
|
+
> If you are migrating from BEFORE v0.67, set `context_behavior` to `"django"`. From v0.67 to v0.78 (incl) the default value was `"isolated"`.
|
|
1591
|
+
>
|
|
1592
|
+
> For v0.79 and later, the default is again `"django"`. See the rationale for change [here](https://github.com/EmilStenstrom/django-components/issues/498).
|
|
1452
1593
|
|
|
1453
1594
|
You can configure what variables are available inside the `{% fill %}` tags. See [Component context and scope](#component-context-and-scope).
|
|
1454
1595
|
|
|
1455
1596
|
This has two modes:
|
|
1456
1597
|
|
|
1457
|
-
- `"django"` -
|
|
1598
|
+
- `"django"` - Default - The default Django template behavior.
|
|
1599
|
+
|
|
1600
|
+
Inside the `{% fill %}` tag, the context variables you can access are a union of:
|
|
1601
|
+
- All the variables that were OUTSIDE the fill tag, including any loops or with tag
|
|
1602
|
+
- Data returned from `get_context_data()` of the component that wraps the fill tag.
|
|
1458
1603
|
|
|
1459
|
-
- `"isolated"` -
|
|
1604
|
+
- `"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.
|
|
1605
|
+
|
|
1606
|
+
Inside the `{% fill %}` tag, you can ONLY access variables from 2 places:
|
|
1607
|
+
- `get_context_data()` of the component which defined the template (AKA the "root" component)
|
|
1608
|
+
- Any loops (`{% for ... %}`) that the `{% fill %}` tag is part of.
|
|
1460
1609
|
|
|
1461
1610
|
```python
|
|
1462
1611
|
COMPONENTS = {
|
|
@@ -1466,75 +1615,76 @@ COMPONENTS = {
|
|
|
1466
1615
|
|
|
1467
1616
|
#### Example "django"
|
|
1468
1617
|
|
|
1469
|
-
Given this template
|
|
1470
|
-
|
|
1471
|
-
```django
|
|
1472
|
-
{% with cheese="feta" %}
|
|
1473
|
-
{% component 'my_comp' %}
|
|
1474
|
-
{{ my_var }} # my_var
|
|
1475
|
-
{{ cheese }} # cheese
|
|
1476
|
-
{% endcomponent %}
|
|
1477
|
-
{% endwith %}
|
|
1478
|
-
```
|
|
1479
|
-
|
|
1480
|
-
and this context returned from the `get_context_data()` method
|
|
1618
|
+
Given this template:
|
|
1481
1619
|
|
|
1482
1620
|
```py
|
|
1483
|
-
|
|
1621
|
+
class RootComp(component.Component):
|
|
1622
|
+
template = """
|
|
1623
|
+
{% with cheese="feta" %}
|
|
1624
|
+
{% component 'my_comp' %}
|
|
1625
|
+
{{ my_var }} # my_var
|
|
1626
|
+
{{ cheese }} # cheese
|
|
1627
|
+
{% endcomponent %}
|
|
1628
|
+
{% endwith %}
|
|
1629
|
+
"""
|
|
1630
|
+
def get_context_data(self):
|
|
1631
|
+
return { "my_var": 123 }
|
|
1484
1632
|
```
|
|
1485
1633
|
|
|
1486
|
-
Then if component "my_comp"
|
|
1634
|
+
Then if `get_context_data()` of the component `"my_comp"` returns following data:
|
|
1487
1635
|
|
|
1488
1636
|
```py
|
|
1489
1637
|
{ "my_var": 456 }
|
|
1490
1638
|
```
|
|
1491
1639
|
|
|
1492
|
-
Then
|
|
1640
|
+
Then the template will be rendered as:
|
|
1493
1641
|
|
|
1494
1642
|
```django
|
|
1495
1643
|
456 # my_var
|
|
1496
1644
|
feta # cheese
|
|
1497
1645
|
```
|
|
1498
1646
|
|
|
1499
|
-
Because "my_comp"
|
|
1647
|
+
Because `"my_comp"` overshadows the variable `"my_var"`,
|
|
1500
1648
|
so `{{ my_var }}` equals `456`.
|
|
1501
|
-
And variable "cheese" equals `feta`, because the fill CAN access
|
|
1502
|
-
the current context.
|
|
1503
|
-
|
|
1504
|
-
#### Example "isolated"
|
|
1505
1649
|
|
|
1506
|
-
|
|
1650
|
+
And variable `"cheese"` equals `feta`, because the fill CAN access
|
|
1651
|
+
all the data defined in the outer layers, like the `{% with %}` tag.
|
|
1507
1652
|
|
|
1508
|
-
|
|
1509
|
-
{% with cheese="feta" %}
|
|
1510
|
-
{% component 'my_comp' %}
|
|
1511
|
-
{{ my_var }} # my_var
|
|
1512
|
-
{{ cheese }} # cheese
|
|
1513
|
-
{% endcomponent %}
|
|
1514
|
-
{% endwith %}
|
|
1515
|
-
```
|
|
1653
|
+
#### Example "isolated"
|
|
1516
1654
|
|
|
1517
|
-
|
|
1655
|
+
Given this template:
|
|
1518
1656
|
|
|
1519
1657
|
```py
|
|
1520
|
-
|
|
1658
|
+
class RootComp(component.Component):
|
|
1659
|
+
template = """
|
|
1660
|
+
{% with cheese="feta" %}
|
|
1661
|
+
{% component 'my_comp' %}
|
|
1662
|
+
{{ my_var }} # my_var
|
|
1663
|
+
{{ cheese }} # cheese
|
|
1664
|
+
{% endcomponent %}
|
|
1665
|
+
{% endwith %}
|
|
1666
|
+
"""
|
|
1667
|
+
def get_context_data(self):
|
|
1668
|
+
return { "my_var": 123 }
|
|
1521
1669
|
```
|
|
1522
1670
|
|
|
1523
|
-
Then if component "my_comp"
|
|
1671
|
+
Then if `get_context_data()` of the component `"my_comp"` returns following data:
|
|
1524
1672
|
|
|
1525
1673
|
```py
|
|
1526
1674
|
{ "my_var": 456 }
|
|
1527
1675
|
```
|
|
1528
1676
|
|
|
1529
|
-
Then
|
|
1677
|
+
Then the template will be rendered as:
|
|
1530
1678
|
|
|
1531
1679
|
```django
|
|
1532
1680
|
123 # my_var
|
|
1533
1681
|
# cheese
|
|
1534
1682
|
```
|
|
1535
1683
|
|
|
1536
|
-
Because
|
|
1537
|
-
But since "cheese" is not defined there, it's empty.
|
|
1684
|
+
Because variables `"my_var"` and `"cheese"` are searched only inside `RootComponent.get_context_data()`.
|
|
1685
|
+
But since `"cheese"` is not defined there, it's empty.
|
|
1686
|
+
|
|
1687
|
+
Notice that the variables defined with the `{% with %}` tag are ignored inside the `{% fill %}` tag with the `"isolated"` mode.
|
|
1538
1688
|
|
|
1539
1689
|
## Logging and debugging
|
|
1540
1690
|
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "django_components"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.80"
|
|
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"]
|
|
@@ -105,7 +105,7 @@ class AppSettings:
|
|
|
105
105
|
|
|
106
106
|
@property
|
|
107
107
|
def CONTEXT_BEHAVIOR(self) -> ContextBehavior:
|
|
108
|
-
raw_value = self.settings.get("context_behavior", ContextBehavior.
|
|
108
|
+
raw_value = self.settings.get("context_behavior", ContextBehavior.DJANGO.value)
|
|
109
109
|
return self._validate_context_behavior(raw_value)
|
|
110
110
|
|
|
111
111
|
def _validate_context_behavior(self, raw_value: ContextBehavior) -> ContextBehavior:
|