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.
Files changed (54) hide show
  1. {django_components-0.78/src/django_components.egg-info → django_components-0.80}/PKG-INFO +192 -42
  2. {django_components-0.78 → django_components-0.80}/README.md +191 -41
  3. {django_components-0.78 → django_components-0.80}/pyproject.toml +1 -1
  4. {django_components-0.78 → django_components-0.80}/src/django_components/app_settings.py +1 -1
  5. {django_components-0.78 → django_components-0.80}/src/django_components/component.py +64 -4
  6. django_components-0.80/src/django_components/context.py +136 -0
  7. {django_components-0.78 → django_components-0.80}/src/django_components/logger.py +1 -1
  8. django_components-0.80/src/django_components/provide.py +52 -0
  9. {django_components-0.78 → django_components-0.80}/src/django_components/templatetags/component_tags.py +51 -0
  10. {django_components-0.78 → django_components-0.80/src/django_components.egg-info}/PKG-INFO +192 -42
  11. {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/SOURCES.txt +2 -0
  12. {django_components-0.78 → django_components-0.80}/tests/test_templatetags.py +39 -0
  13. django_components-0.80/tests/test_templatetags_provide.py +601 -0
  14. django_components-0.78/src/django_components/context.py +0 -64
  15. {django_components-0.78 → django_components-0.80}/LICENSE +0 -0
  16. {django_components-0.78 → django_components-0.80}/setup.cfg +0 -0
  17. {django_components-0.78 → django_components-0.80}/src/django_components/__init__.py +0 -0
  18. {django_components-0.78 → django_components-0.80}/src/django_components/apps.py +0 -0
  19. {django_components-0.78 → django_components-0.80}/src/django_components/attributes.py +0 -0
  20. {django_components-0.78 → django_components-0.80}/src/django_components/component_registry.py +0 -0
  21. {django_components-0.78 → django_components-0.80}/src/django_components/expression.py +0 -0
  22. {django_components-0.78 → django_components-0.80}/src/django_components/management/__init__.py +0 -0
  23. {django_components-0.78 → django_components-0.80}/src/django_components/management/commands/__init__.py +0 -0
  24. {django_components-0.78 → django_components-0.80}/src/django_components/management/commands/startcomponent.py +0 -0
  25. {django_components-0.78 → django_components-0.80}/src/django_components/management/commands/upgradecomponent.py +0 -0
  26. {django_components-0.78 → django_components-0.80}/src/django_components/middleware.py +0 -0
  27. {django_components-0.78 → django_components-0.80}/src/django_components/node.py +0 -0
  28. {django_components-0.78 → django_components-0.80}/src/django_components/py.typed +0 -0
  29. {django_components-0.78 → django_components-0.80}/src/django_components/safer_staticfiles/__init__.py +0 -0
  30. {django_components-0.78 → django_components-0.80}/src/django_components/safer_staticfiles/apps.py +0 -0
  31. {django_components-0.78 → django_components-0.80}/src/django_components/slots.py +0 -0
  32. {django_components-0.78 → django_components-0.80}/src/django_components/template_loader.py +0 -0
  33. {django_components-0.78 → django_components-0.80}/src/django_components/template_parser.py +0 -0
  34. {django_components-0.78 → django_components-0.80}/src/django_components/templatetags/__init__.py +0 -0
  35. {django_components-0.78 → django_components-0.80}/src/django_components/types.py +0 -0
  36. {django_components-0.78 → django_components-0.80}/src/django_components/utils.py +0 -0
  37. {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/dependency_links.txt +0 -0
  38. {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/requires.txt +0 -0
  39. {django_components-0.78 → django_components-0.80}/src/django_components.egg-info/top_level.txt +0 -0
  40. {django_components-0.78 → django_components-0.80}/tests/test_attributes.py +0 -0
  41. {django_components-0.78 → django_components-0.80}/tests/test_autodiscover.py +0 -0
  42. {django_components-0.78 → django_components-0.80}/tests/test_command_startcomponent.py +0 -0
  43. {django_components-0.78 → django_components-0.80}/tests/test_component.py +0 -0
  44. {django_components-0.78 → django_components-0.80}/tests/test_component_as_view.py +0 -0
  45. {django_components-0.78 → django_components-0.80}/tests/test_component_media.py +0 -0
  46. {django_components-0.78 → django_components-0.80}/tests/test_context.py +0 -0
  47. {django_components-0.78 → django_components-0.80}/tests/test_dependency_rendering.py +0 -0
  48. {django_components-0.78 → django_components-0.80}/tests/test_registry.py +0 -0
  49. {django_components-0.78 → django_components-0.80}/tests/test_settings.py +0 -0
  50. {django_components-0.78 → django_components-0.80}/tests/test_template_parser.py +0 -0
  51. {django_components-0.78 → django_components-0.80}/tests/test_templatetags_component.py +0 -0
  52. {django_components-0.78 → django_components-0.80}/tests/test_templatetags_slot_fill.py +0 -0
  53. {django_components-0.78 → django_components-0.80}/tests/test_templatetags_templating.py +0 -0
  54. {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.78
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, components are ISOLATED and CANNOT access context variables from the parent template. This is useful if you want to make sure that components don't accidentally access the outer context.
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
- You can set the [context_behavior](#context-behavior) option to `"django"`, to make components behave just like templates that are included with the `{% include %}` tag. 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:
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
- Components can also access the outer context in their context methods by accessing the property `outer_context`.
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 and later use the default value `"isolated"`.
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"` - Context variables are taken from its surroundings (default before v0.67)
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"` - Default - Similar behavior to [Vue](https://vuejs.org/guide/components/slots.html#render-scope) or React - variables are taken ONLY from `get_context_data()` method of the component which defines the `{% fill %}` tag. This is useful if you want to make sure that components don't accidentally access the outer context.
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
- { "my_var": 123 }
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" defines context
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 this will render:
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" overrides the variable "my_var",
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
- Given this template
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
- ```django
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
- and this context returned from the `get_context_data()` method
1679
+ Given this template:
1542
1680
 
1543
1681
  ```py
1544
- { "my_var": 123 }
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" defines context
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 this will render:
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 both variables "my_var" and "cheese" are taken from the parent's `get_context_data()`.
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, components are ISOLATED and CANNOT access context variables from the parent template. This is useful if you want to make sure that components don't accidentally access the outer context.
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
- You can set the [context_behavior](#context-behavior) option to `"django"`, to make components behave just like templates that are included with the `{% include %}` tag. 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:
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
- Components can also access the outer context in their context methods by accessing the property `outer_context`.
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 and later use the default value `"isolated"`.
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"` - Context variables are taken from its surroundings (default before v0.67)
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"` - Default - Similar behavior to [Vue](https://vuejs.org/guide/components/slots.html#render-scope) or React - variables are taken ONLY from `get_context_data()` method of the component which defines the `{% fill %}` tag. This is useful if you want to make sure that components don't accidentally access the outer context.
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
- { "my_var": 123 }
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" defines context
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 this will render:
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" overrides the variable "my_var",
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
- Given this template
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
- ```django
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
- and this context returned from the `get_context_data()` method
1655
+ Given this template:
1518
1656
 
1519
1657
  ```py
1520
- { "my_var": 123 }
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" defines context
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 this will render:
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 both variables "my_var" and "cheese" are taken from the parent's `get_context_data()`.
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.78"
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.ISOLATED.value)
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: