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.
- {django_components-0.93/src/django_components.egg-info → django_components-0.95}/PKG-INFO +157 -5
- {django_components-0.93 → django_components-0.95}/README.md +156 -4
- {django_components-0.93 → django_components-0.95}/pyproject.toml +1 -1
- {django_components-0.93 → django_components-0.95}/src/django_components/__init__.py +1 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/app_settings.py +13 -1
- django_components-0.95/src/django_components/apps.py +50 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/component.py +7 -2
- {django_components-0.93 → django_components-0.95}/src/django_components/component_registry.py +9 -1
- django_components-0.95/src/django_components/components/__init__.py +3 -0
- django_components-0.95/src/django_components/components/dynamic.py +89 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/slots.py +8 -2
- {django_components-0.93 → django_components-0.95}/src/django_components/templatetags/component_tags.py +29 -31
- {django_components-0.93 → django_components-0.95}/src/django_components/utils.py +14 -1
- {django_components-0.93 → django_components-0.95/src/django_components.egg-info}/PKG-INFO +157 -5
- {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/SOURCES.txt +2 -0
- {django_components-0.93 → django_components-0.95}/tests/test_templatetags.py +32 -1
- {django_components-0.93 → django_components-0.95}/tests/test_templatetags_component.py +298 -14
- django_components-0.93/src/django_components/apps.py +0 -17
- {django_components-0.93 → django_components-0.95}/LICENSE +0 -0
- {django_components-0.93 → django_components-0.95}/setup.cfg +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/attributes.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/autodiscover.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/component_media.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/context.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/expression.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/library.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/logger.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/management/__init__.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/middleware.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/node.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/provide.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/py.typed +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/tag_formatter.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/template_loader.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/template_parser.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components/types.py +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.93 → django_components-0.95}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_attributes.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_autodiscover.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_command_startcomponent.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_component.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_component_as_view.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_component_media.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_context.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_expression.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_registry.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_safer_staticfiles.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_settings.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_tag_formatter.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_template_loader.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_template_parser.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_templatetags_provide.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_templatetags_slot_fill.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_templatetags_templating.py +0 -0
- {django_components-0.93 → django_components-0.95}/tests/test_utils.py +0 -0
- {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.
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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) ->
|
|
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]
|
|
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
|
{django_components-0.93 → django_components-0.95}/src/django_components/component_registry.py
RENAMED
|
@@ -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
|
"""
|