django-components 0.93__tar.gz → 0.95__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 (65) hide show
  1. {django_components-0.93/src/django_components.egg-info → django_components-0.95}/PKG-INFO +157 -5
  2. {django_components-0.93 → django_components-0.95}/README.md +156 -4
  3. {django_components-0.93 → django_components-0.95}/pyproject.toml +1 -1
  4. {django_components-0.93 → django_components-0.95}/src/django_components/__init__.py +1 -0
  5. {django_components-0.93 → django_components-0.95}/src/django_components/app_settings.py +13 -1
  6. django_components-0.95/src/django_components/apps.py +50 -0
  7. {django_components-0.93 → django_components-0.95}/src/django_components/component.py +7 -2
  8. {django_components-0.93 → django_components-0.95}/src/django_components/component_registry.py +9 -1
  9. django_components-0.95/src/django_components/components/__init__.py +3 -0
  10. django_components-0.95/src/django_components/components/dynamic.py +89 -0
  11. {django_components-0.93 → django_components-0.95}/src/django_components/slots.py +8 -2
  12. {django_components-0.93 → django_components-0.95}/src/django_components/templatetags/component_tags.py +29 -31
  13. {django_components-0.93 → django_components-0.95}/src/django_components/utils.py +14 -1
  14. {django_components-0.93 → django_components-0.95/src/django_components.egg-info}/PKG-INFO +157 -5
  15. {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/SOURCES.txt +2 -0
  16. {django_components-0.93 → django_components-0.95}/tests/test_templatetags.py +32 -1
  17. {django_components-0.93 → django_components-0.95}/tests/test_templatetags_component.py +298 -14
  18. django_components-0.93/src/django_components/apps.py +0 -17
  19. {django_components-0.93 → django_components-0.95}/LICENSE +0 -0
  20. {django_components-0.93 → django_components-0.95}/setup.cfg +0 -0
  21. {django_components-0.93 → django_components-0.95}/src/django_components/attributes.py +0 -0
  22. {django_components-0.93 → django_components-0.95}/src/django_components/autodiscover.py +0 -0
  23. {django_components-0.93 → django_components-0.95}/src/django_components/component_media.py +0 -0
  24. {django_components-0.93 → django_components-0.95}/src/django_components/context.py +0 -0
  25. {django_components-0.93 → django_components-0.95}/src/django_components/expression.py +0 -0
  26. {django_components-0.93 → django_components-0.95}/src/django_components/library.py +0 -0
  27. {django_components-0.93 → django_components-0.95}/src/django_components/logger.py +0 -0
  28. {django_components-0.93 → django_components-0.95}/src/django_components/management/__init__.py +0 -0
  29. {django_components-0.93 → django_components-0.95}/src/django_components/management/commands/__init__.py +0 -0
  30. {django_components-0.93 → django_components-0.95}/src/django_components/management/commands/startcomponent.py +0 -0
  31. {django_components-0.93 → django_components-0.95}/src/django_components/management/commands/upgradecomponent.py +0 -0
  32. {django_components-0.93 → django_components-0.95}/src/django_components/middleware.py +0 -0
  33. {django_components-0.93 → django_components-0.95}/src/django_components/node.py +0 -0
  34. {django_components-0.93 → django_components-0.95}/src/django_components/provide.py +0 -0
  35. {django_components-0.93 → django_components-0.95}/src/django_components/py.typed +0 -0
  36. {django_components-0.93 → django_components-0.95}/src/django_components/safer_staticfiles/__init__.py +0 -0
  37. {django_components-0.93 → django_components-0.95}/src/django_components/safer_staticfiles/apps.py +0 -0
  38. {django_components-0.93 → django_components-0.95}/src/django_components/tag_formatter.py +0 -0
  39. {django_components-0.93 → django_components-0.95}/src/django_components/template_loader.py +0 -0
  40. {django_components-0.93 → django_components-0.95}/src/django_components/template_parser.py +0 -0
  41. {django_components-0.93 → django_components-0.95}/src/django_components/templatetags/__init__.py +0 -0
  42. {django_components-0.93 → django_components-0.95}/src/django_components/types.py +0 -0
  43. {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/dependency_links.txt +0 -0
  44. {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/requires.txt +0 -0
  45. {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/top_level.txt +0 -0
  46. {django_components-0.93 → django_components-0.95}/tests/test_attributes.py +0 -0
  47. {django_components-0.93 → django_components-0.95}/tests/test_autodiscover.py +0 -0
  48. {django_components-0.93 → django_components-0.95}/tests/test_command_startcomponent.py +0 -0
  49. {django_components-0.93 → django_components-0.95}/tests/test_component.py +0 -0
  50. {django_components-0.93 → django_components-0.95}/tests/test_component_as_view.py +0 -0
  51. {django_components-0.93 → django_components-0.95}/tests/test_component_media.py +0 -0
  52. {django_components-0.93 → django_components-0.95}/tests/test_context.py +0 -0
  53. {django_components-0.93 → django_components-0.95}/tests/test_dependency_rendering.py +0 -0
  54. {django_components-0.93 → django_components-0.95}/tests/test_expression.py +0 -0
  55. {django_components-0.93 → django_components-0.95}/tests/test_registry.py +0 -0
  56. {django_components-0.93 → django_components-0.95}/tests/test_safer_staticfiles.py +0 -0
  57. {django_components-0.93 → django_components-0.95}/tests/test_settings.py +0 -0
  58. {django_components-0.93 → django_components-0.95}/tests/test_tag_formatter.py +0 -0
  59. {django_components-0.93 → django_components-0.95}/tests/test_template_loader.py +0 -0
  60. {django_components-0.93 → django_components-0.95}/tests/test_template_parser.py +0 -0
  61. {django_components-0.93 → django_components-0.95}/tests/test_templatetags_provide.py +0 -0
  62. {django_components-0.93 → django_components-0.95}/tests/test_templatetags_slot_fill.py +0 -0
  63. {django_components-0.93 → django_components-0.95}/tests/test_templatetags_templating.py +0 -0
  64. {django_components-0.93 → django_components-0.95}/tests/test_utils.py +0 -0
  65. {django_components-0.93 → django_components-0.95}/tests/testutils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.93
3
+ Version: 0.95
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
@@ -68,8 +68,9 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
68
68
  - [Using single-file components](#using-single-file-components)
69
69
  - [Use components in templates](#use-components-in-templates)
70
70
  - [Use components outside of templates](#use-components-outside-of-templates)
71
- - [Registering components](#registering-components)
72
71
  - [Use components as views](#use-components-as-views)
72
+ - [Pre-defined components](#pre-defined-components)
73
+ - [Registering components](#registering-components)
73
74
  - [Autodiscovery](#autodiscovery)
74
75
  - [Using slots in templates](#using-slots-in-templates)
75
76
  - [Accessing data passed to the component](#accessing-data-passed-to-the-component)
@@ -81,6 +82,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
81
82
  - [Defining HTML/JS/CSS files](#defining-htmljscss-files)
82
83
  - [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
83
84
  - [Available settings](#available-settings)
85
+ - [Running with development server](#running-with-development-server)
84
86
  - [Logging and debugging](#logging-and-debugging)
85
87
  - [Management Command](#management-command)
86
88
  - [Writing and sharing component libraries](#writing-and-sharing-component-libraries)
@@ -90,9 +92,17 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
90
92
 
91
93
  ## Release notes
92
94
 
95
+ **Version 0.95**
96
+ - Added support for dynamic components, where the component name is passed as a variable. (See [Dynamic components](#dynamic-components))
97
+ - Changed `Component.input` to raise `RuntimeError` if accessed outside of render context. Previously it returned `None` if unset.
98
+
99
+ **Version 0.94**
100
+ - django_components now automatically configures Django to support multi-line tags. (See [Multi-line tags](#multi-line-tags))
101
+ - New setting `reload_on_template_change`. Set this to `True` to reload the dev server on changes to component template files. (See [Reload dev server on component file changes](#reload-dev-server-on-component-file-changes))
102
+
93
103
  **Version 0.93**
94
- - Spread operator `...dict` inside template tags. See [Spread operator](#spread-operator))
95
- - Use template tags inside string literals in component inputs. See [Use template tags inside component inputs](#use-template-tags-inside-component-inputs))
104
+ - Spread operator `...dict` inside template tags. (See [Spread operator](#spread-operator))
105
+ - Use template tags inside string literals in component inputs. (See [Use template tags inside component inputs](#use-template-tags-inside-component-inputs))
96
106
  - Dynamic slots, fills and provides - The `name` argument for these can now be a variable, a template expression, or via spread operator
97
107
  - Component library authors can now configure `CONTEXT_BEHAVIOR` and `TAG_FORMATTER` settings independently from user settings.
98
108
 
@@ -251,6 +261,7 @@ For a step-by-step guide on deploying production server with static files,
251
261
  4. Modify `TEMPLATES` section of settings.py as follows:
252
262
 
253
263
  - _Remove `'APP_DIRS': True,`_
264
+ - NOTE: Instead of APP_DIRS, for the same effect, we will use [`django.template.loaders.app_directories.Loader`](https://docs.djangoproject.com/en/5.1/ref/templates/api/#django.template.loaders.app_directories.Loader)
254
265
  - Add `loaders` to `OPTIONS` list and set it to following value:
255
266
 
256
267
  ```python
@@ -263,8 +274,11 @@ For a step-by-step guide on deploying production server with static files,
263
274
  ],
264
275
  'loaders':[(
265
276
  'django.template.loaders.cached.Loader', [
277
+ # Default Django loader
266
278
  'django.template.loaders.filesystem.Loader',
279
+ # Inluding this is the same as APP_DIRS=True
267
280
  'django.template.loaders.app_directories.Loader',
281
+ # Components loader
268
282
  'django_components.template_loader.Loader',
269
283
  ]
270
284
  )],
@@ -865,6 +879,54 @@ class MyComponent(Component):
865
879
  do_something_extra(request, *args, **kwargs)
866
880
  ```
867
881
 
882
+ ## Pre-defined components
883
+
884
+ ### Dynamic components
885
+
886
+ If you are writing something like a form component, you may design it such that users
887
+ give you the component names, and your component renders it.
888
+
889
+ While you can handle this with a series of if / else statements, this is not an extensible solution.
890
+
891
+ Instead, you can use **dynamic components**. Dynamic components are used in place of normal components.
892
+
893
+ ```django
894
+ {% load component_tags %}
895
+ {% component "dynamic" is=component_name title="Cat Museum" %}
896
+ {% fill "content" %}
897
+ HELLO_FROM_SLOT_1
898
+ {% endfill %}
899
+ {% fill "sidebar" %}
900
+ HELLO_FROM_SLOT_2
901
+ {% endfill %}
902
+ {% endcomponent %}
903
+ ```
904
+
905
+ These behave same way as regular components. You pass it the same args, kwargs, and slots as you would
906
+ to the component that you want to render.
907
+
908
+ The only exception is that also you supply 1-2 additional inputs:
909
+ - `is` - Required - The component name or a component class to render
910
+ - `registry` - Optional - The `ComponentRegistry` that will be searched if `is` is a component name. If omitted, ALL registries are searched.
911
+
912
+ By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict, you can change the name used for the dynamic components by defining the [`COMPONENTS.dynamic_component_name` setting](#dynamic_component_name).
913
+
914
+ If you need to use the dynamic components in Python, you can also import it from `django_components`:
915
+ ```py
916
+ from django_components import DynamicComponent
917
+
918
+ comp = SimpleTableComp if is_readonly else TableComp
919
+
920
+ output = DynamicComponent.render(
921
+ kwargs={
922
+ "is": comp,
923
+ # Other kwargs...
924
+ },
925
+ # args: [...],
926
+ # slots: {...},
927
+ )
928
+ ```
929
+
868
930
  ## Registering components
869
931
 
870
932
  In previous examples you could repeatedly see us using `@register()` to "register"
@@ -1574,7 +1636,7 @@ This means that you can use `self.input` inside:
1574
1636
  - `get_template_name`
1575
1637
  - `get_template_string`
1576
1638
 
1577
- `self.input` is defined only for the duration of `Component.render`, and returns `None` when called outside of this.
1639
+ `self.input` is defined only for the duration of `Component.render`, and raises `RuntimeError` when called outside of this.
1578
1640
 
1579
1641
  `self.input` has the same fields as the input to `Component.render`:
1580
1642
 
@@ -2233,6 +2295,34 @@ Sweet! Now all the relevant HTML is inside the template, and we can move it to a
2233
2295
  > {"attrs": {"my_key:two": 2}}
2234
2296
  > ```
2235
2297
 
2298
+ ### Multi-line tags
2299
+
2300
+ By default, Django expects a template tag to be defined on a single line.
2301
+
2302
+ However, this can become unwieldy if you have a component with a lot of inputs:
2303
+
2304
+ ```django
2305
+ {% component "card" title="Joanne Arc" subtitle="Head of Kitty Relations" date_last_active="2024-09-03" ... %}
2306
+ ```
2307
+
2308
+ Instead, when you install django_components, it automatically configures Django
2309
+ to suport multi-line tags.
2310
+
2311
+ So we can rewrite the above as:
2312
+
2313
+ ```django
2314
+ {% component "card"
2315
+ title="Joanne Arc"
2316
+ subtitle="Head of Kitty Relations"
2317
+ date_last_active="2024-09-03"
2318
+ ...
2319
+ %}
2320
+ ```
2321
+
2322
+ Much better!
2323
+
2324
+ To disable this behavior, set [`COMPONENTS.multiline_tag`](#multiline_tags---enabledisable-multiline-support) to `False`
2325
+
2236
2326
  ## Prop drilling and dependency injection (provide / inject)
2237
2327
 
2238
2328
  _New in version 0.80_:
@@ -2773,6 +2863,21 @@ COMPONENTS = {
2773
2863
 
2774
2864
  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.
2775
2865
 
2866
+ Here's overview of all available settings and their defaults:
2867
+
2868
+ ```py
2869
+ COMPONENTS = {
2870
+ "autodiscover": True,
2871
+ "context_behavior": "django", # "django" | "isolated"
2872
+ "dynamic_component_name": "dynamic",
2873
+ "libraries": [], # ["mysite.components.forms", ...]
2874
+ "multiline_tags": True,
2875
+ "reload_on_template_change": False,
2876
+ "tag_formatter": "django_components.component_formatter",
2877
+ "template_cache_size": 128,
2878
+ }
2879
+ ```
2880
+
2776
2881
  ### `libraries` - Load component modules
2777
2882
 
2778
2883
  Configure the locations 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.
@@ -2825,6 +2930,26 @@ COMPONENTS = {
2825
2930
  }
2826
2931
  ```
2827
2932
 
2933
+ ### `dynamic_component_name`
2934
+
2935
+ By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict, use this setting to change the name used for the dynamic components.
2936
+
2937
+ ```python
2938
+ COMPONENTS = {
2939
+ "dynamic_component_name": "new_dynamic",
2940
+ }
2941
+ ```
2942
+
2943
+ ### `multiline_tags` - Enable/Disable multiline support
2944
+
2945
+ If `True`, template tags can span multiple lines. Default: `True`
2946
+
2947
+ ```python
2948
+ COMPONENTS = {
2949
+ "multiline_tags": True,
2950
+ }
2951
+ ```
2952
+
2828
2953
  ### `template_cache_size` - Tune the template cache
2829
2954
 
2830
2955
  Each time a template is rendered it is cached to a global in-memory cache (using Python's `lru_cache` decorator). This speeds up the next render of the component. As the same component is often used many times on the same page, these savings add up.
@@ -2942,6 +3067,13 @@ But since `"cheese"` is not defined there, it's empty.
2942
3067
 
2943
3068
  Notice that the variables defined with the `{% with %}` tag are ignored inside the `{% fill %}` tag with the `"isolated"` mode.
2944
3069
 
3070
+ ### `reload_on_template_change` - Reload dev server on component file changes
3071
+
3072
+ If `True`, configures Django to reload on component files. See
3073
+ [Reload dev server on component file changes](#reload-dev-server-on-component-file-changes).
3074
+
3075
+ NOTE: This setting should be enabled only for the dev environment!
3076
+
2945
3077
  ### `tag_formatter` - Change how components are used in templates
2946
3078
  Sets the [`TagFormatter`](#available-tagformatters) instance. See the section [Customizing component tags with TagFormatter](#customizing-component-tags-with-tagformatter).
2947
3079
 
@@ -2963,6 +3095,26 @@ COMPONENTS = {
2963
3095
  }
2964
3096
  ```
2965
3097
 
3098
+ ## Running with development server
3099
+
3100
+ ### Reload dev server on component file changes
3101
+
3102
+ This is relevant if you are using the project structure as shown in our examples, where
3103
+ HTML, JS, CSS and Python are separate and nested in a directory.
3104
+
3105
+ In this case you may notice that when you are running a development server,
3106
+ the server sometimes does not reload when you change comoponent files.
3107
+
3108
+ From relevant [StackOverflow thread](https://stackoverflow.com/a/76722393/9788634):
3109
+
3110
+ > TL;DR is that the server won't reload if it thinks the changed file is in a templates directory,
3111
+ > or in a nested sub directory of a templates directory. This is by design.
3112
+
3113
+ To make the dev server reload on all component files, set [`reload_on_template_change`](#reload_on_template_change---reload-dev-server-on-component-file-changes) to `True`.
3114
+ This configures Django to watch for component files too.
3115
+
3116
+ NOTE: This setting should be enabled only for the dev environment!
3117
+
2966
3118
  ## Logging and debugging
2967
3119
 
2968
3120
  Django components supports [logging with Django](https://docs.djangoproject.com/en/5.0/howto/logging/#logging-how-to). This can help with troubleshooting.
@@ -44,8 +44,9 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
44
44
  - [Using single-file components](#using-single-file-components)
45
45
  - [Use components in templates](#use-components-in-templates)
46
46
  - [Use components outside of templates](#use-components-outside-of-templates)
47
- - [Registering components](#registering-components)
48
47
  - [Use components as views](#use-components-as-views)
48
+ - [Pre-defined components](#pre-defined-components)
49
+ - [Registering components](#registering-components)
49
50
  - [Autodiscovery](#autodiscovery)
50
51
  - [Using slots in templates](#using-slots-in-templates)
51
52
  - [Accessing data passed to the component](#accessing-data-passed-to-the-component)
@@ -57,6 +58,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
57
58
  - [Defining HTML/JS/CSS files](#defining-htmljscss-files)
58
59
  - [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
59
60
  - [Available settings](#available-settings)
61
+ - [Running with development server](#running-with-development-server)
60
62
  - [Logging and debugging](#logging-and-debugging)
61
63
  - [Management Command](#management-command)
62
64
  - [Writing and sharing component libraries](#writing-and-sharing-component-libraries)
@@ -66,9 +68,17 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
66
68
 
67
69
  ## Release notes
68
70
 
71
+ **Version 0.95**
72
+ - Added support for dynamic components, where the component name is passed as a variable. (See [Dynamic components](#dynamic-components))
73
+ - Changed `Component.input` to raise `RuntimeError` if accessed outside of render context. Previously it returned `None` if unset.
74
+
75
+ **Version 0.94**
76
+ - django_components now automatically configures Django to support multi-line tags. (See [Multi-line tags](#multi-line-tags))
77
+ - New setting `reload_on_template_change`. Set this to `True` to reload the dev server on changes to component template files. (See [Reload dev server on component file changes](#reload-dev-server-on-component-file-changes))
78
+
69
79
  **Version 0.93**
70
- - Spread operator `...dict` inside template tags. See [Spread operator](#spread-operator))
71
- - Use template tags inside string literals in component inputs. See [Use template tags inside component inputs](#use-template-tags-inside-component-inputs))
80
+ - Spread operator `...dict` inside template tags. (See [Spread operator](#spread-operator))
81
+ - Use template tags inside string literals in component inputs. (See [Use template tags inside component inputs](#use-template-tags-inside-component-inputs))
72
82
  - Dynamic slots, fills and provides - The `name` argument for these can now be a variable, a template expression, or via spread operator
73
83
  - Component library authors can now configure `CONTEXT_BEHAVIOR` and `TAG_FORMATTER` settings independently from user settings.
74
84
 
@@ -227,6 +237,7 @@ For a step-by-step guide on deploying production server with static files,
227
237
  4. Modify `TEMPLATES` section of settings.py as follows:
228
238
 
229
239
  - _Remove `'APP_DIRS': True,`_
240
+ - NOTE: Instead of APP_DIRS, for the same effect, we will use [`django.template.loaders.app_directories.Loader`](https://docs.djangoproject.com/en/5.1/ref/templates/api/#django.template.loaders.app_directories.Loader)
230
241
  - Add `loaders` to `OPTIONS` list and set it to following value:
231
242
 
232
243
  ```python
@@ -239,8 +250,11 @@ For a step-by-step guide on deploying production server with static files,
239
250
  ],
240
251
  'loaders':[(
241
252
  'django.template.loaders.cached.Loader', [
253
+ # Default Django loader
242
254
  'django.template.loaders.filesystem.Loader',
255
+ # Inluding this is the same as APP_DIRS=True
243
256
  'django.template.loaders.app_directories.Loader',
257
+ # Components loader
244
258
  'django_components.template_loader.Loader',
245
259
  ]
246
260
  )],
@@ -841,6 +855,54 @@ class MyComponent(Component):
841
855
  do_something_extra(request, *args, **kwargs)
842
856
  ```
843
857
 
858
+ ## Pre-defined components
859
+
860
+ ### Dynamic components
861
+
862
+ If you are writing something like a form component, you may design it such that users
863
+ give you the component names, and your component renders it.
864
+
865
+ While you can handle this with a series of if / else statements, this is not an extensible solution.
866
+
867
+ Instead, you can use **dynamic components**. Dynamic components are used in place of normal components.
868
+
869
+ ```django
870
+ {% load component_tags %}
871
+ {% component "dynamic" is=component_name title="Cat Museum" %}
872
+ {% fill "content" %}
873
+ HELLO_FROM_SLOT_1
874
+ {% endfill %}
875
+ {% fill "sidebar" %}
876
+ HELLO_FROM_SLOT_2
877
+ {% endfill %}
878
+ {% endcomponent %}
879
+ ```
880
+
881
+ These behave same way as regular components. You pass it the same args, kwargs, and slots as you would
882
+ to the component that you want to render.
883
+
884
+ The only exception is that also you supply 1-2 additional inputs:
885
+ - `is` - Required - The component name or a component class to render
886
+ - `registry` - Optional - The `ComponentRegistry` that will be searched if `is` is a component name. If omitted, ALL registries are searched.
887
+
888
+ By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict, you can change the name used for the dynamic components by defining the [`COMPONENTS.dynamic_component_name` setting](#dynamic_component_name).
889
+
890
+ If you need to use the dynamic components in Python, you can also import it from `django_components`:
891
+ ```py
892
+ from django_components import DynamicComponent
893
+
894
+ comp = SimpleTableComp if is_readonly else TableComp
895
+
896
+ output = DynamicComponent.render(
897
+ kwargs={
898
+ "is": comp,
899
+ # Other kwargs...
900
+ },
901
+ # args: [...],
902
+ # slots: {...},
903
+ )
904
+ ```
905
+
844
906
  ## Registering components
845
907
 
846
908
  In previous examples you could repeatedly see us using `@register()` to "register"
@@ -1550,7 +1612,7 @@ This means that you can use `self.input` inside:
1550
1612
  - `get_template_name`
1551
1613
  - `get_template_string`
1552
1614
 
1553
- `self.input` is defined only for the duration of `Component.render`, and returns `None` when called outside of this.
1615
+ `self.input` is defined only for the duration of `Component.render`, and raises `RuntimeError` when called outside of this.
1554
1616
 
1555
1617
  `self.input` has the same fields as the input to `Component.render`:
1556
1618
 
@@ -2209,6 +2271,34 @@ Sweet! Now all the relevant HTML is inside the template, and we can move it to a
2209
2271
  > {"attrs": {"my_key:two": 2}}
2210
2272
  > ```
2211
2273
 
2274
+ ### Multi-line tags
2275
+
2276
+ By default, Django expects a template tag to be defined on a single line.
2277
+
2278
+ However, this can become unwieldy if you have a component with a lot of inputs:
2279
+
2280
+ ```django
2281
+ {% component "card" title="Joanne Arc" subtitle="Head of Kitty Relations" date_last_active="2024-09-03" ... %}
2282
+ ```
2283
+
2284
+ Instead, when you install django_components, it automatically configures Django
2285
+ to suport multi-line tags.
2286
+
2287
+ So we can rewrite the above as:
2288
+
2289
+ ```django
2290
+ {% component "card"
2291
+ title="Joanne Arc"
2292
+ subtitle="Head of Kitty Relations"
2293
+ date_last_active="2024-09-03"
2294
+ ...
2295
+ %}
2296
+ ```
2297
+
2298
+ Much better!
2299
+
2300
+ To disable this behavior, set [`COMPONENTS.multiline_tag`](#multiline_tags---enabledisable-multiline-support) to `False`
2301
+
2212
2302
  ## Prop drilling and dependency injection (provide / inject)
2213
2303
 
2214
2304
  _New in version 0.80_:
@@ -2749,6 +2839,21 @@ COMPONENTS = {
2749
2839
 
2750
2840
  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.
2751
2841
 
2842
+ Here's overview of all available settings and their defaults:
2843
+
2844
+ ```py
2845
+ COMPONENTS = {
2846
+ "autodiscover": True,
2847
+ "context_behavior": "django", # "django" | "isolated"
2848
+ "dynamic_component_name": "dynamic",
2849
+ "libraries": [], # ["mysite.components.forms", ...]
2850
+ "multiline_tags": True,
2851
+ "reload_on_template_change": False,
2852
+ "tag_formatter": "django_components.component_formatter",
2853
+ "template_cache_size": 128,
2854
+ }
2855
+ ```
2856
+
2752
2857
  ### `libraries` - Load component modules
2753
2858
 
2754
2859
  Configure the locations 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.
@@ -2801,6 +2906,26 @@ COMPONENTS = {
2801
2906
  }
2802
2907
  ```
2803
2908
 
2909
+ ### `dynamic_component_name`
2910
+
2911
+ By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict, use this setting to change the name used for the dynamic components.
2912
+
2913
+ ```python
2914
+ COMPONENTS = {
2915
+ "dynamic_component_name": "new_dynamic",
2916
+ }
2917
+ ```
2918
+
2919
+ ### `multiline_tags` - Enable/Disable multiline support
2920
+
2921
+ If `True`, template tags can span multiple lines. Default: `True`
2922
+
2923
+ ```python
2924
+ COMPONENTS = {
2925
+ "multiline_tags": True,
2926
+ }
2927
+ ```
2928
+
2804
2929
  ### `template_cache_size` - Tune the template cache
2805
2930
 
2806
2931
  Each time a template is rendered it is cached to a global in-memory cache (using Python's `lru_cache` decorator). This speeds up the next render of the component. As the same component is often used many times on the same page, these savings add up.
@@ -2918,6 +3043,13 @@ But since `"cheese"` is not defined there, it's empty.
2918
3043
 
2919
3044
  Notice that the variables defined with the `{% with %}` tag are ignored inside the `{% fill %}` tag with the `"isolated"` mode.
2920
3045
 
3046
+ ### `reload_on_template_change` - Reload dev server on component file changes
3047
+
3048
+ If `True`, configures Django to reload on component files. See
3049
+ [Reload dev server on component file changes](#reload-dev-server-on-component-file-changes).
3050
+
3051
+ NOTE: This setting should be enabled only for the dev environment!
3052
+
2921
3053
  ### `tag_formatter` - Change how components are used in templates
2922
3054
  Sets the [`TagFormatter`](#available-tagformatters) instance. See the section [Customizing component tags with TagFormatter](#customizing-component-tags-with-tagformatter).
2923
3055
 
@@ -2939,6 +3071,26 @@ COMPONENTS = {
2939
3071
  }
2940
3072
  ```
2941
3073
 
3074
+ ## Running with development server
3075
+
3076
+ ### Reload dev server on component file changes
3077
+
3078
+ This is relevant if you are using the project structure as shown in our examples, where
3079
+ HTML, JS, CSS and Python are separate and nested in a directory.
3080
+
3081
+ In this case you may notice that when you are running a development server,
3082
+ the server sometimes does not reload when you change comoponent files.
3083
+
3084
+ From relevant [StackOverflow thread](https://stackoverflow.com/a/76722393/9788634):
3085
+
3086
+ > TL;DR is that the server won't reload if it thinks the changed file is in a templates directory,
3087
+ > or in a nested sub directory of a templates directory. This is by design.
3088
+
3089
+ To make the dev server reload on all component files, set [`reload_on_template_change`](#reload_on_template_change---reload-dev-server-on-component-file-changes) to `True`.
3090
+ This configures Django to watch for component files too.
3091
+
3092
+ NOTE: This setting should be enabled only for the dev environment!
3093
+
2942
3094
  ## Logging and debugging
2943
3095
 
2944
3096
  Django components supports [logging with Django](https://docs.djangoproject.com/en/5.0/howto/logging/#logging-how-to). This can help with troubleshooting.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "django_components"
7
- version = "0.93"
7
+ version = "0.95"
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"]
@@ -22,6 +22,7 @@ from django_components.component_registry import (
22
22
  register as register,
23
23
  registry as registry,
24
24
  )
25
+ from django_components.components import DynamicComponent as DynamicComponent
25
26
  from django_components.library import TagProtectedError as TagProtectedError
26
27
  from django_components.slots import (
27
28
  SlotContent as SlotContent,
@@ -99,9 +99,21 @@ class AppSettings:
99
99
  return self.settings.get("autodiscover", True)
100
100
 
101
101
  @property
102
- def LIBRARIES(self) -> List:
102
+ def DYNAMIC_COMPONENT_NAME(self) -> str:
103
+ return self.settings.get("dynamic_component_name", "dynamic")
104
+
105
+ @property
106
+ def LIBRARIES(self) -> List[str]:
103
107
  return self.settings.get("libraries", [])
104
108
 
109
+ @property
110
+ def MULTILINE_TAGS(self) -> bool:
111
+ return self.settings.get("multiline_tags", True)
112
+
113
+ @property
114
+ def RELOAD_ON_TEMPLATE_CHANGE(self) -> bool:
115
+ return self.settings.get("reload_on_template_change", False)
116
+
105
117
  @property
106
118
  def TEMPLATE_CACHE_SIZE(self) -> int:
107
119
  return self.settings.get("template_cache_size", 128)
@@ -0,0 +1,50 @@
1
+ import re
2
+
3
+ from django.apps import AppConfig
4
+
5
+
6
+ class ComponentsConfig(AppConfig):
7
+ name = "django_components"
8
+
9
+ # This is the code that gets run when user adds django_components
10
+ # to Django's INSTALLED_APPS
11
+ def ready(self) -> None:
12
+ from django_components.app_settings import app_settings
13
+ from django_components.autodiscover import autodiscover, get_dirs, import_libraries, search_dirs
14
+ from django_components.component_registry import registry
15
+ from django_components.components.dynamic import DynamicComponent
16
+ from django_components.utils import watch_files_for_autoreload
17
+
18
+ # Import modules set in `COMPONENTS.libraries` setting
19
+ import_libraries()
20
+
21
+ if app_settings.AUTODISCOVER:
22
+ autodiscover()
23
+
24
+ # Watch template files for changes, so Django dev server auto-reloads
25
+ # See https://github.com/EmilStenstrom/django-components/discussions/567#discussioncomment-10273632
26
+ # And https://stackoverflow.com/questions/42907285/66673186#66673186
27
+ if app_settings.RELOAD_ON_TEMPLATE_CHANGE:
28
+ dirs = get_dirs()
29
+ component_filepaths = search_dirs(dirs, "**/*")
30
+ watch_files_for_autoreload(component_filepaths)
31
+
32
+ # Allow tags to span multiple lines. This makes it easier to work with
33
+ # components inside Django templates, allowing us syntax like:
34
+ # ```html
35
+ # {% component "icon"
36
+ # icon='outline_chevron_down'
37
+ # size=16
38
+ # color="text-gray-400"
39
+ # attrs:class="ml-2"
40
+ # %}{% endcomponent %}
41
+ # ```
42
+ #
43
+ # See https://stackoverflow.com/a/54206609/9788634
44
+ if app_settings.MULTILINE_TAGS:
45
+ from django.template import base
46
+
47
+ base.tag_re = re.compile(base.tag_re.pattern, re.DOTALL)
48
+
49
+ # Register the dynamic component under the name as given in settings
50
+ registry.register(app_settings.DYNAMIC_COMPONENT_NAME, DynamicComponent)
@@ -205,14 +205,17 @@ class Component(Generic[ArgsType, KwargsType, DataType, SlotsType], metaclass=Co
205
205
  return self.registered_name or self.__class__.__name__
206
206
 
207
207
  @property
208
- def input(self) -> Optional[RenderInput[ArgsType, KwargsType, SlotsType]]:
208
+ def input(self) -> RenderInput[ArgsType, KwargsType, SlotsType]:
209
209
  """
210
210
  Input holds the data (like arg, kwargs, slots) that were passsed to
211
211
  the current execution of the `render` method.
212
212
  """
213
+ if not len(self._render_stack):
214
+ raise RuntimeError(f"{self.name}: Tried to access Component input while outside of rendering execution")
215
+
213
216
  # NOTE: Input is managed as a stack, so if `render` is called within another `render`,
214
217
  # the propertes below will return only the inner-most state.
215
- return self._render_stack[-1] if len(self._render_stack) else None
218
+ return self._render_stack[-1]
216
219
 
217
220
  def get_context_data(self, *args: Any, **kwargs: Any) -> DataType:
218
221
  return cast(DataType, {})
@@ -526,6 +529,8 @@ class Component(Generic[ArgsType, KwargsType, DataType, SlotsType], metaclass=Co
526
529
  component_name=self.name,
527
530
  context_data=slot_context_data,
528
531
  fill_content=fill_content,
532
+ # Dynamic component has a special mark do it doesn't raise certain errors
533
+ is_dynamic_component=getattr(self, "_is_dynamic_component", False),
529
534
  )
530
535
 
531
536
  # Available slot fills - this is internal to us
@@ -1,4 +1,4 @@
1
- from typing import TYPE_CHECKING, Callable, Dict, NamedTuple, Optional, Set, Type, TypeVar, Union
1
+ from typing import TYPE_CHECKING, Callable, Dict, List, NamedTuple, Optional, Set, Type, TypeVar, Union
2
2
 
3
3
  from django.template import Library
4
4
 
@@ -44,6 +44,12 @@ class InternalRegistrySettings(NamedTuple):
44
44
  TAG_FORMATTER: Union["TagFormatterABC", str]
45
45
 
46
46
 
47
+ # We keep track of all registries that exist so that, when users want to
48
+ # dynamically resolve component name to component class, they would be able
49
+ # to search across all registries.
50
+ all_registries: List["ComponentRegistry"] = []
51
+
52
+
47
53
  class ComponentRegistry:
48
54
  """
49
55
  Manages which components can be used in the template tags.
@@ -88,6 +94,8 @@ class ComponentRegistry:
88
94
  self._settings_input = settings
89
95
  self._settings: Optional[Callable[[], InternalRegistrySettings]] = None
90
96
 
97
+ all_registries.append(self)
98
+
91
99
  @property
92
100
  def library(self) -> Library:
93
101
  """
@@ -0,0 +1,3 @@
1
+ # flake8: noqa F401
2
+
3
+ from django_components.components.dynamic import DynamicComponent as DynamicComponent