django-components 0.68__tar.gz → 0.70__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 (45) hide show
  1. {django_components-0.68/src/django_components.egg-info → django_components-0.70}/PKG-INFO +162 -86
  2. {django_components-0.68 → django_components-0.70}/README.md +161 -85
  3. {django_components-0.68 → django_components-0.70}/pyproject.toml +1 -1
  4. {django_components-0.68 → django_components-0.70}/src/django_components/__init__.py +15 -2
  5. django_components-0.70/src/django_components/app_settings.py +119 -0
  6. {django_components-0.68 → django_components-0.70}/src/django_components/component.py +91 -44
  7. django_components-0.70/src/django_components/context.py +64 -0
  8. {django_components-0.68 → django_components-0.70}/src/django_components/logger.py +2 -2
  9. {django_components-0.68 → django_components-0.70}/src/django_components/middleware.py +21 -0
  10. {django_components-0.68 → django_components-0.70}/src/django_components/node.py +13 -6
  11. django_components-0.70/src/django_components/slots.py +534 -0
  12. {django_components-0.68 → django_components-0.70}/src/django_components/templatetags/component_tags.py +3 -117
  13. {django_components-0.68 → django_components-0.70/src/django_components.egg-info}/PKG-INFO +162 -86
  14. {django_components-0.68 → django_components-0.70}/tests/test_component.py +394 -169
  15. {django_components-0.68 → django_components-0.70}/tests/test_component_as_view.py +17 -5
  16. {django_components-0.68 → django_components-0.70}/tests/test_context.py +185 -26
  17. {django_components-0.68 → django_components-0.70}/tests/test_templatetags.py +401 -43
  18. {django_components-0.68 → django_components-0.70}/tests/testutils.py +25 -2
  19. django_components-0.68/src/django_components/app_settings.py +0 -146
  20. django_components-0.68/src/django_components/context.py +0 -182
  21. django_components-0.68/src/django_components/slots.py +0 -500
  22. {django_components-0.68 → django_components-0.70}/LICENSE +0 -0
  23. {django_components-0.68 → django_components-0.70}/setup.cfg +0 -0
  24. {django_components-0.68 → django_components-0.70}/src/django_components/apps.py +0 -0
  25. {django_components-0.68 → django_components-0.70}/src/django_components/component_registry.py +0 -0
  26. {django_components-0.68 → django_components-0.70}/src/django_components/management/__init__.py +0 -0
  27. {django_components-0.68 → django_components-0.70}/src/django_components/management/commands/__init__.py +0 -0
  28. {django_components-0.68 → django_components-0.70}/src/django_components/management/commands/startcomponent.py +0 -0
  29. {django_components-0.68 → django_components-0.70}/src/django_components/management/commands/upgradecomponent.py +0 -0
  30. {django_components-0.68 → django_components-0.70}/src/django_components/py.typed +0 -0
  31. {django_components-0.68 → django_components-0.70}/src/django_components/safer_staticfiles/__init__.py +0 -0
  32. {django_components-0.68 → django_components-0.70}/src/django_components/safer_staticfiles/apps.py +0 -0
  33. {django_components-0.68 → django_components-0.70}/src/django_components/template_loader.py +0 -0
  34. {django_components-0.68 → django_components-0.70}/src/django_components/templatetags/__init__.py +0 -0
  35. {django_components-0.68 → django_components-0.70}/src/django_components/types.py +0 -0
  36. {django_components-0.68 → django_components-0.70}/src/django_components/utils.py +0 -0
  37. {django_components-0.68 → django_components-0.70}/src/django_components.egg-info/SOURCES.txt +0 -0
  38. {django_components-0.68 → django_components-0.70}/src/django_components.egg-info/dependency_links.txt +0 -0
  39. {django_components-0.68 → django_components-0.70}/src/django_components.egg-info/requires.txt +0 -0
  40. {django_components-0.68 → django_components-0.70}/src/django_components.egg-info/top_level.txt +0 -0
  41. {django_components-0.68 → django_components-0.70}/tests/test_autodiscover.py +0 -0
  42. {django_components-0.68 → django_components-0.70}/tests/test_dependency_rendering.py +0 -0
  43. {django_components-0.68 → django_components-0.70}/tests/test_registry.py +0 -0
  44. {django_components-0.68 → django_components-0.70}/tests/test_settings.py +0 -0
  45. {django_components-0.68 → django_components-0.70}/tests/test_startcomponent_command.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.68
3
+ Version: 0.70
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
@@ -44,7 +44,12 @@ Read on to learn about the details!
44
44
 
45
45
  ## Release notes
46
46
 
47
- **Version 0.67** CHANGED the default way how context variables are resolved in slots. See the [documentation](#isolate-components-slots) for more details.
47
+ 🚨📢 **Version 0.70**
48
+
49
+ - `{% if_filled "my_slot" %}` tags were replaced with `{{ component_vars.is_filled.my_slot }}` variables.
50
+ - Simplified settings - `slot_context_behavior` and `context_behavior` were merged. See the [documentation](#context-behavior) for more details.
51
+
52
+ **Version 0.67** CHANGED the default way how context variables are resolved in slots. See the [documentation](https://github.com/EmilStenstrom/django-components/tree/0.67#isolate-components-slots) for more details.
48
53
 
49
54
  🚨📢 **Version 0.5** CHANGES THE SYNTAX for components. `component_block` is now `component`, and `component` blocks need an ending `endcomponent` tag. The new `python manage.py upgradecomponent` command can be used to upgrade a directory (use --path argument to point to each dir) of components to the new syntax automatically.
50
55
 
@@ -96,7 +101,7 @@ Both routes are described in the official [docs of the _staticfiles_ app](https:
96
101
 
97
102
  Install the app into your environment:
98
103
 
99
- > ```pip install django_components```
104
+ > `pip install django_components`
100
105
 
101
106
  Then add the app into INSTALLED_APPS in settings.py
102
107
 
@@ -142,7 +147,7 @@ STATICFILES_DIRS = [
142
147
 
143
148
  ### Optional
144
149
 
145
- To avoid loading the app in each template using ``` {% load component_tags %} ```, you can add the tag as a 'builtin' in settings.py
150
+ To avoid loading the app in each template using `{% load component_tags %}`, you can add the tag as a 'builtin' in settings.py
146
151
 
147
152
  ```python
148
153
  TEMPLATES = [
@@ -198,19 +203,26 @@ First you need a CSS file. Be sure to prefix all rules with a unique class so th
198
203
 
199
204
  ```css
200
205
  /* In a file called [project root]/components/calendar/style.css */
201
- .calendar-component { width: 200px; background: pink; }
202
- .calendar-component span { font-weight: bold; }
206
+ .calendar-component {
207
+ width: 200px;
208
+ background: pink;
209
+ }
210
+ .calendar-component span {
211
+ font-weight: bold;
212
+ }
203
213
  ```
204
214
 
205
215
  Then you need a javascript file that specifies how you interact with this component. You are free to use any javascript framework you want. A good way to make sure this component doesn't clash with other components is to define all code inside an anonymous function that calls itself. This makes all variables defined only be defined inside this component and not affect other components.
206
216
 
207
217
  ```js
208
218
  /* In a file called [project root]/components/calendar/script.js */
209
- (function(){
210
- if (document.querySelector(".calendar-component")) {
211
- document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
212
- }
213
- })()
219
+ (function () {
220
+ if (document.querySelector(".calendar-component")) {
221
+ document.querySelector(".calendar-component").onclick = function () {
222
+ alert("Clicked calendar!");
223
+ };
224
+ }
225
+ })();
214
226
  ```
215
227
 
216
228
  Now you need a Django template for your component. Feel free to define more variables like `date` in this example. When creating an instance of this component we will send in the values for these variables. The template will be rendered with whatever template backend you've specified in your Django settings file.
@@ -254,6 +266,7 @@ By default, the Python files in the `components` app are auto-imported in order
254
266
  Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
255
267
 
256
268
  If you are using autodiscovery, keep a few points in mind:
269
+
257
270
  - Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
258
271
  - Components inside the auto-imported files still need to be registered with `@component.register()`
259
272
  - 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).
@@ -284,15 +297,23 @@ The output from the above template will be:
284
297
  ```html
285
298
  <!DOCTYPE html>
286
299
  <html>
287
- <head>
300
+ <head>
288
301
  <title>My example calendar</title>
289
- <link href="/static/calendar/style.css" type="text/css" media="all" rel="stylesheet">
290
- </head>
291
- <body>
292
- <div class="calendar-component">Today's date is <span>2015-06-19</span></div>
302
+ <link
303
+ href="/static/calendar/style.css"
304
+ type="text/css"
305
+ media="all"
306
+ rel="stylesheet"
307
+ />
308
+ </head>
309
+ <body>
310
+ <div class="calendar-component">
311
+ Today's date is <span>2015-06-19</span>
312
+ </div>
293
313
  <script src="/static/calendar/script.js"></script>
294
- </body>
295
- <html>
314
+ </body>
315
+ <html></html>
316
+ </html>
296
317
  ```
297
318
 
298
319
  This makes it possible to organize your front-end around reusable components. Instead of relying on template tags and keeping your CSS and Javascript in the static directory.
@@ -553,11 +574,12 @@ Produces:
553
574
  </div>
554
575
  ```
555
576
 
556
-
557
577
  #### Conditional slots
558
578
 
559
579
  _Added in version 0.26._
560
580
 
581
+ > NOTE: In version 0.70, `{% if_filled %}` tags were replaced with `{{ component_vars.is_filled }}` variables. If your slot name contained special characters, see the section "Accessing slot names with special characters".
582
+
561
583
  In certain circumstances, you may want the behavior of slot filling to depend on
562
584
  whether or not a particular slot is filled.
563
585
 
@@ -590,61 +612,62 @@ explicit fills, the div containing the slot is still rendered, as shown below:
590
612
  This may not be what you want. What if instead the outer 'subtitle' div should only
591
613
  be included when the inner slot is in fact filled?
592
614
 
593
- The answer is to use the `{% if_filled <name> %}` tag. Together with `{% endif_filled %}`,
594
- these define a block whose contents will be rendered only if the component slot with
615
+ The answer is to use the `{{ component_vars.is_filled.<name> }}` variable. You can use this together with Django's `{% if/elif/else/endif %}` tags to define a block whose contents will be rendered only if the component slot with
595
616
  the corresponding 'name' is filled.
596
617
 
597
- This is what our example looks like with an 'if_filled' tag.
618
+ This is what our example looks like with `component_vars.is_filled`.
598
619
 
599
620
  ```htmldjango
600
621
  <div class="frontmatter-component">
601
622
  <div class="title">
602
623
  {% slot "title" %}Title{% endslot %}
603
624
  </div>
604
- {% if_filled "subtitle" %}
625
+ {% if component_vars.is_filled.subtitle %}
605
626
  <div class="subtitle">
606
627
  {% slot "subtitle" %}{# Optional subtitle #}{% endslot %}
607
628
  </div>
608
- {% endif_filled %}
629
+ {% endif %}
609
630
  </div>
610
631
  ```
611
632
 
612
- Just as Django's builtin 'if' tag has 'elif' and 'else' counterparts, so does 'if_filled'
613
- include additional tags for more complex branching. These tags are 'elif_filled' and
614
- 'else_filled'. Here's what our example looks like with them.
633
+ Here's our example with more complex branching.
615
634
 
616
635
  ```htmldjango
617
636
  <div class="frontmatter-component">
618
637
  <div class="title">
619
638
  {% slot "title" %}Title{% endslot %}
620
639
  </div>
621
- {% if_filled "subtitle" %}
640
+ {% if component_vars.is_filled.subtitle %}
622
641
  <div class="subtitle">
623
642
  {% slot "subtitle" %}{# Optional subtitle #}{% endslot %}
624
643
  </div>
625
- {% elif_filled "title" %}
644
+ {% elif component_vars.is_filled.title %}
626
645
  ...
627
- {% else_filled %}
646
+ {% elif component_vars.is_filled.<name> %}
628
647
  ...
629
- {% endif_filled %}
648
+ {% endif %}
630
649
  </div>
631
650
  ```
632
651
 
633
652
  Sometimes you're not interested in whether a slot is filled, but rather that it _isn't_.
634
- To negate the meaning of 'if_filled' in this way, an optional boolean can be passed to
635
- the 'if_filled' and 'elif_filled' tags.
636
-
637
- In the example below we use `False` to indicate that the content should be rendered
638
- only if the slot 'subtitle' is _not_ filled.
653
+ To negate the meaning of `component_vars.is_filled`, simply treat it as boolean and negate it with `not`:
639
654
 
640
655
  ```htmldjango
641
- {% if_filled subtitle False %}
656
+ {% if not component_vars.is_filled.subtitle %}
642
657
  <div class="subtitle">
643
658
  {% slot "subtitle" %}{% endslot %}
644
659
  </div>
645
- {% endif_filled %}
660
+ {% endif %}
646
661
  ```
647
662
 
663
+ **Accessing slot names with special characters**
664
+
665
+ To be able to access a slot name via `component_vars.is_filled`, the slot name needs to be composed of only alphanumeric characters and underscores (e.g. `this__isvalid_123`).
666
+
667
+ However, you can still define slots with other special characters. In such case, the slot name in `component_vars.is_filled` is modified to replace all invalid characters into `_`.
668
+
669
+ So a slot named `"my super-slot :)"` will be available as `component_vars.is_filled.my_super_slot___`.
670
+
648
671
  ### Setting Up `ComponentDependencyMiddleware`
649
672
 
650
673
  `ComponentDependencyMiddleware` is a Django middleware designed to manage and inject CSS/JS dependencies for rendered components dynamically. It ensures that only the necessary stylesheets and scripts are loaded in your HTML responses, based on the components used in your Django templates.
@@ -670,25 +693,25 @@ COMPONENTS = {
670
693
 
671
694
  ## Component context and scope
672
695
 
673
- By default, components can access context variables from the parent template, just like templates that are included with the `{% include %}` tag. Just like with `{% include %}`, if you don't want the component template to have access to the parent context, add `only` to the end of the `{% component %}` tag):
696
+ 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.
697
+
698
+ 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:
674
699
 
675
700
  ```htmldjango
676
- {% component "calendar" date="2015-06-19" only %}{% endcomponent %}
701
+ {% component "calendar" date="2015-06-19" only %}{% endcomponent %}
677
702
  ```
678
703
 
679
704
  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.
680
705
 
681
706
  Components can also access the outer context in their context methods by accessing the property `outer_context`.
682
707
 
683
- You can also set `context_behavior` to `isolated` to make all components isolated by default. This is useful if you want to make sure that components don't accidentally access the outer context.
684
-
685
708
  ## Available settings
686
709
 
687
- All library settings are handled from a global COMPONENTS variable that is read from settings.py. By default you don't need it set, there are resonable defaults.
710
+ All library settings are handled from a global `COMPONENTS` variable that is read from `settings.py`. By default you don't need it set, there are resonable defaults.
688
711
 
689
712
  ### Configure the module where components are loaded from
690
713
 
691
- Configure the location where components are loaded. To do this, add a COMPONENTS variable to you settings.py with a list of python paths to load. This allows you to build a structure of components that are independent from your apps.
714
+ Configure the location where components are loaded. To do this, add a `COMPONENTS` variable to you `settings.py` with a list of python paths to load. This allows you to build a structure of components that are independent from your apps.
692
715
 
693
716
  ```python
694
717
  COMPONENTS = {
@@ -720,9 +743,19 @@ COMPONENTS = {
720
743
  }
721
744
  ```
722
745
 
723
- ### Isolate components' context by default
746
+ ### Context behavior
747
+
748
+ > NOTE: `context_behavior` and `slot_context_behavior` options were merged in v0.70.
749
+ >
750
+ > If you are migrating from BEFORE v0.67, set `context_behavior` to `"django"`. From v0.67 and later use the default value `"isolated"`.
751
+
752
+ You can configure what variables are available inside the `{% fill %}` tags. See [Component context and scope](#component-context-and-scope).
753
+
754
+ This has two modes:
755
+
756
+ - `"django"` - Context variables are taken from its surroundings (default before v0.67)
724
757
 
725
- If you'd like to prevent components from accessing the outer context by default, you can set the `context_behavior` setting to `isolated`. This is useful if you want to make sure that components don't accidentally access the outer context.
758
+ - `"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.
726
759
 
727
760
  ```python
728
761
  COMPONENTS = {
@@ -730,26 +763,77 @@ COMPONENTS = {
730
763
  }
731
764
  ```
732
765
 
733
- ### Isolate components' slots
766
+ #### Example "django"
734
767
 
735
- What variables should be available from inside a component slot?
768
+ Given this template
736
769
 
737
- By default, variables inside component slots are preferentially taken from the root context.
738
- This is similar to [how Vue renders slots](https://vuejs.org/guide/components/slots.html#render-scope),
739
- except that, if variable is not found in the root, then the surrounding context is searched too.
770
+ ```django
771
+ {% with cheese="feta" %}
772
+ {% component 'my_comp' %}
773
+ {{ my_var }} # my_var
774
+ {{ cheese }} # cheese
775
+ {% endcomponent %}
776
+ {% endwith %}
777
+ ```
740
778
 
741
- You can change this with the `slot_contet_behavior` setting. Options are:
742
- - `"prefer_root"` - Default - as described above
743
- - `"isolated"` - Same behavior as Vue - variables are taken ONLY from the root context
744
- - `"allow_override"` - slot context variables are taken from its surroundings (default before v0.67)
779
+ and this context returned from the `get_context_data()` method
745
780
 
746
- ```python
747
- COMPONENTS = {
748
- "slot_context_behavior": "isolated",
749
- }
781
+ ```py
782
+ { "my_var": 123 }
783
+ ```
784
+
785
+ Then if component "my_comp" defines context
786
+
787
+ ```py
788
+ { "my_var": 456 }
789
+ ```
790
+
791
+ Then this will render:
792
+
793
+ ```django
794
+ 456 # my_var
795
+ feta # cheese
796
+ ```
797
+
798
+ Because "my_comp" overrides the variable "my_var",
799
+ so `{{ my_var }}` equals `456`.
800
+ And variable "cheese" equals `feta`, because the fill CAN access
801
+ the current context.
802
+
803
+ #### Example "isolated"
804
+
805
+ Given this template
806
+
807
+ ```django
808
+ {% with cheese="feta" %}
809
+ {% component 'my_comp' %}
810
+ {{ my_var }} # my_var
811
+ {{ cheese }} # cheese
812
+ {% endcomponent %}
813
+ {% endwith %}
814
+ ```
815
+
816
+ and this context returned from the `get_context_data()` method
817
+
818
+ ```py
819
+ { "my_var": 123 }
820
+ ```
821
+
822
+ Then if component "my_comp" defines context
823
+
824
+ ```py
825
+ { "my_var": 456 }
826
+ ```
827
+
828
+ Then this will render:
829
+
830
+ ```django
831
+ 123 # my_var
832
+ # cheese
750
833
  ```
751
834
 
752
- For further details and examples, see [SlotContextBehavior](https://github.com/EmilStenstrom/django-components/blob/master/src/django_components/app_settings.py#L12).
835
+ Because both variables "my_var" and "cheese" are taken from the parent's `get_context_data()`.
836
+ But since "cheese" is not defined there, it's empty.
753
837
 
754
838
  ## Logging and debugging
755
839
 
@@ -861,7 +945,6 @@ One of our goals with `django-components` is to make it easy to share components
861
945
 
862
946
  - [django-htmx-components](https://github.com/iwanalabs/django-htmx-components): A set of components for use with [htmx](https://htmx.org/). Try out the [live demo](https://dhc.iwanalabs.com/).
863
947
 
864
-
865
948
  ## Running django-components project locally
866
949
 
867
950
  ### Install locally and run the tests
@@ -903,25 +986,29 @@ How do you check that your changes to django-components project will work in an
903
986
  Use the [sampleproject](./sampleproject/) demo project to validate the changes:
904
987
 
905
988
  1. Navigate to [sampleproject](./sampleproject/) directory:
906
- ```sh
907
- cd sampleproject
908
- ```
989
+
990
+ ```sh
991
+ cd sampleproject
992
+ ```
909
993
 
910
994
  2. Install dependencies from the [requirements.txt](./sampleproject/requirements.txt) file:
911
- ```sh
912
- pip install -r requirements.txt
913
- ```
995
+
996
+ ```sh
997
+ pip install -r requirements.txt
998
+ ```
914
999
 
915
1000
  3. Link to your local version of django-components:
916
- ```sh
917
- pip install -e ..
918
- ```
919
- NOTE: The path (in this case `..`) must point to the directory that has the `setup.py` file.
1001
+
1002
+ ```sh
1003
+ pip install -e ..
1004
+ ```
1005
+
1006
+ NOTE: The path (in this case `..`) must point to the directory that has the `setup.py` file.
920
1007
 
921
1008
  4. Start Django server
922
- ```sh
923
- python manage.py runserver
924
- ```
1009
+ ```sh
1010
+ python manage.py runserver
1011
+ ```
925
1012
 
926
1013
  Once the server is up, it should be available at <http://127.0.0.1:8000>.
927
1014
 
@@ -929,15 +1016,4 @@ To display individual components, add them to the `urls.py`, like in the case of
929
1016
 
930
1017
  ## Development guides
931
1018
 
932
- ### Slot rendering flow
933
-
934
- 1. Flow starts when a template string is being parsed into Django Template instance.
935
-
936
- 2. When a `{% component %}` template tag is encountered, its body is searched for all `{% fill %}` nodes (explicit or implicit). and this is attached to the created `ComponentNode`.
937
-
938
- See the implementation of `component` template tag for details.
939
-
940
- 3. Template rendering is a separate action from template parsing. When the template is being rendered, the `ComponentNode` creates an instance of the `Component` class and passes it the slot fills.
941
-
942
- It's at this point when `Component.render` is called, and the slots are
943
- rendered.
1019
+ - [Slot rendering flot](./docs/slot_rendering.md)