django-components 0.102__tar.gz → 0.111__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.102/src/django_components.egg-info → django_components-0.111}/PKG-INFO +433 -186
- {django_components-0.102 → django_components-0.111}/README.md +431 -185
- {django_components-0.102 → django_components-0.111}/pyproject.toml +6 -1
- django_components-0.111/src/django_components/__init__.py +73 -0
- django_components-0.111/src/django_components/app_settings.py +702 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/apps.py +23 -8
- django_components-0.111/src/django_components/autodiscovery.py +95 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/component.py +216 -156
- {django_components-0.102 → django_components-0.111}/src/django_components/component_media.py +3 -3
- django_components-0.111/src/django_components/component_registry.py +557 -0
- django_components-0.111/src/django_components/components/__init__.py +4 -0
- django_components-0.111/src/django_components/components/dynamic.py +170 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/context.py +2 -25
- django_components-0.111/src/django_components/dependencies.py +793 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/finders.py +4 -4
- {django_components-0.102 → django_components-0.111}/src/django_components/library.py +26 -1
- {django_components-0.102 → django_components-0.111}/src/django_components/management/commands/startcomponent.py +78 -10
- django_components-0.111/src/django_components/middleware.py +4 -0
- django_components-0.111/src/django_components/node.py +22 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/provide.py +2 -2
- django_components-0.111/src/django_components/slots.py +778 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/tag_formatter.py +132 -27
- {django_components-0.102 → django_components-0.111}/src/django_components/template.py +34 -2
- django_components-0.111/src/django_components/template_loader.py +28 -0
- django_components-0.111/src/django_components/templatetags/component_tags.py +1167 -0
- django_components-0.111/src/django_components/types.py +7 -0
- django_components-0.111/src/django_components/urls.py +7 -0
- django_components-0.111/src/django_components/util/__init__.py +0 -0
- django_components-0.111/src/django_components/util/cache.py +45 -0
- django_components-0.111/src/django_components/util/html.py +100 -0
- django_components-0.111/src/django_components/util/loader.py +240 -0
- {django_components-0.102/src/django_components → django_components-0.111/src/django_components/util}/logger.py +2 -6
- django_components-0.111/src/django_components/util/misc.py +79 -0
- django_components-0.111/src/django_components/util/nanoid.py +29 -0
- django_components-0.111/src/django_components/util/tag_parser.py +198 -0
- django_components-0.111/src/django_components/util/types.py +143 -0
- django_components-0.102/src/django_components/utils.py → django_components-0.111/src/django_components/util/validation.py +1 -93
- {django_components-0.102 → django_components-0.111/src/django_components.egg-info}/PKG-INFO +433 -186
- {django_components-0.102 → django_components-0.111}/src/django_components.egg-info/SOURCES.txt +14 -4
- django_components-0.111/src/django_components.egg-info/requires.txt +2 -0
- django_components-0.102/src/django_components/__init__.py +0 -49
- django_components-0.102/src/django_components/app_settings.py +0 -194
- django_components-0.102/src/django_components/autodiscover.py +0 -149
- django_components-0.102/src/django_components/component_registry.py +0 -364
- django_components-0.102/src/django_components/components/__init__.py +0 -3
- django_components-0.102/src/django_components/components/dynamic.py +0 -89
- django_components-0.102/src/django_components/middleware.py +0 -109
- django_components-0.102/src/django_components/node.py +0 -121
- django_components-0.102/src/django_components/slots.py +0 -727
- django_components-0.102/src/django_components/template_loader.py +0 -103
- django_components-0.102/src/django_components/templatetags/component_tags.py +0 -685
- django_components-0.102/src/django_components/types.py +0 -43
- django_components-0.102/src/django_components.egg-info/requires.txt +0 -1
- {django_components-0.102 → django_components-0.111}/LICENSE +0 -0
- {django_components-0.102 → django_components-0.111}/MANIFEST.in +0 -0
- {django_components-0.102 → django_components-0.111}/setup.cfg +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/attributes.py +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/expression.py +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/management/__init__.py +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/py.typed +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/static/django_components/django_components.min.js +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/template_parser.py +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.102 → django_components-0.111}/src/django_components.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: django_components
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.111
|
|
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
|
|
@@ -21,6 +21,7 @@ Requires-Python: <4.0,>=3.8
|
|
|
21
21
|
Description-Content-Type: text/markdown
|
|
22
22
|
License-File: LICENSE
|
|
23
23
|
Requires-Dist: Django>=4.2
|
|
24
|
+
Requires-Dist: selectolax>=0.3.24
|
|
24
25
|
|
|
25
26
|
# <img src="https://raw.githubusercontent.com/EmilStenstrom/django-components/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
|
|
26
27
|
|
|
@@ -47,21 +48,41 @@ Potential benefits:
|
|
|
47
48
|
|
|
48
49
|
Django-components can be particularly useful for larger Django projects that require a more structured approach to UI development, without necessitating a shift to a separate frontend framework.
|
|
49
50
|
|
|
50
|
-
##
|
|
51
|
+
## Quickstart
|
|
51
52
|
|
|
52
|
-
|
|
53
|
+
django-components lets you create reusable blocks of code needed to generate the front end code you need for a modern app.
|
|
54
|
+
|
|
55
|
+
Define a component in `components/calendar/calendar.py` like this:
|
|
56
|
+
```python
|
|
57
|
+
@register("calendar")
|
|
58
|
+
class Calendar(Component):
|
|
59
|
+
template_name = "template.html"
|
|
60
|
+
|
|
61
|
+
def get_context_data(self, date):
|
|
62
|
+
return {"date": date}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
With this `template.html` file:
|
|
53
66
|
|
|
54
67
|
```htmldjango
|
|
55
|
-
|
|
68
|
+
<div class="calendar-component">Today's date is <span>{{ date }}</span></div>
|
|
56
69
|
```
|
|
57
70
|
|
|
58
|
-
|
|
71
|
+
Use the component like this:
|
|
72
|
+
|
|
73
|
+
```htmldjango
|
|
74
|
+
{% component "calendar" date="2024-11-06" %}{% endcomponent %}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
And this is what gets rendered:
|
|
59
78
|
|
|
60
79
|
```html
|
|
61
|
-
<div class="calendar-component">Today's date is <span>
|
|
80
|
+
<div class="calendar-component">Today's date is <span>2024-11-06</span></div>
|
|
62
81
|
```
|
|
63
82
|
|
|
64
|
-
|
|
83
|
+
Read on to learn about all the exciting details and configuration possibilities!
|
|
84
|
+
|
|
85
|
+
(If you instead prefer to jump right into the code, [check out the example project](https://github.com/EmilStenstrom/django-components/tree/master/sampleproject))
|
|
65
86
|
|
|
66
87
|
## Table of Contents
|
|
67
88
|
|
|
@@ -100,128 +121,8 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
100
121
|
|
|
101
122
|
## Release notes
|
|
102
123
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
- `django_components.safer_staticfiles` app was removed. It is no longer needed.
|
|
106
|
-
- Installation changes:
|
|
107
|
-
- Instead of defining component directories in `STATICFILES_DIRS`, set them to [`COMPONENTS.dirs`](#dirs).
|
|
108
|
-
- You now must define `STATICFILES_FINDERS`
|
|
109
|
-
- [See here how to migrate your settings.py](https://github.com/EmilStenstrom/django-components/blob/master/docs/migrating_from_safer_staticfiles.md)
|
|
110
|
-
- Beside the top-level `/components` directory, you can now define also app-level components dirs, e.g. `[app]/components`
|
|
111
|
-
(See [`COMPONENTS.app_dirs`](#app_dirs)).
|
|
112
|
-
- When you call `as_view()` on a component instance, that instance will be passed to `View.as_view()`
|
|
113
|
-
|
|
114
|
-
**Version 0.97**
|
|
115
|
-
- Fixed template caching. You can now also manually create cached templates with [`cached_template()`](#template_cache_size---tune-the-template-cache)
|
|
116
|
-
- The previously undocumented `get_template` was made private.
|
|
117
|
-
- In it's place, there's a new `get_template`, which supersedes `get_template_string` (will be removed in v1). The new `get_template` is the same as `get_template_string`, except
|
|
118
|
-
it allows to return either a string or a Template instance.
|
|
119
|
-
- You now must use only one of `template`, `get_template`, `template_name`, or `get_template_name`.
|
|
120
|
-
|
|
121
|
-
**Version 0.96**
|
|
122
|
-
- Run-time type validation for Python 3.11+ - If the `Component` class is typed, e.g. `Component[Args, Kwargs, ...]`, the args, kwargs, slots, and data are validated against the given types. (See [Runtime input validation with types](#runtime-input-validation-with-types))
|
|
123
|
-
- Render hooks - Set `on_render_before` and `on_render_after` methods on `Component` to intercept or modify the template or context before rendering, or the rendered result afterwards. (See [Component hooks](#component-hooks))
|
|
124
|
-
- `component_vars.is_filled` context variable can be accessed from within `on_render_before` and `on_render_after` hooks as `self.is_filled.my_slot`
|
|
125
|
-
|
|
126
|
-
**Version 0.95**
|
|
127
|
-
- Added support for dynamic components, where the component name is passed as a variable. (See [Dynamic components](#dynamic-components))
|
|
128
|
-
- Changed `Component.input` to raise `RuntimeError` if accessed outside of render context. Previously it returned `None` if unset.
|
|
129
|
-
|
|
130
|
-
**Version 0.94**
|
|
131
|
-
- django_components now automatically configures Django to support multi-line tags. (See [Multi-line tags](#multi-line-tags))
|
|
132
|
-
- 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))
|
|
133
|
-
|
|
134
|
-
**Version 0.93**
|
|
135
|
-
- Spread operator `...dict` inside template tags. (See [Spread operator](#spread-operator))
|
|
136
|
-
- Use template tags inside string literals in component inputs. (See [Use template tags inside component inputs](#use-template-tags-inside-component-inputs))
|
|
137
|
-
- Dynamic slots, fills and provides - The `name` argument for these can now be a variable, a template expression, or via spread operator
|
|
138
|
-
- Component library authors can now configure `CONTEXT_BEHAVIOR` and `TAG_FORMATTER` settings independently from user settings.
|
|
139
|
-
|
|
140
|
-
🚨📢 **Version 0.92**
|
|
141
|
-
- BREAKING CHANGE: `Component` class is no longer a subclass of `View`. To configure the `View` class, set the `Component.View` nested class. HTTP methods like `get` or `post` can still be defined directly on `Component` class, and `Component.as_view()` internally calls `Component.View.as_view()`. (See [Modifying the View class](#modifying-the-view-class))
|
|
142
|
-
|
|
143
|
-
- The inputs (args, kwargs, slots, context, ...) that you pass to `Component.render()` can be accessed from within `get_context_data`, `get_template` and `get_template_name` via `self.input`. (See [Accessing data passed to the component](#accessing-data-passed-to-the-component))
|
|
144
|
-
|
|
145
|
-
- Typing: `Component` class supports generics that specify types for `Component.render` (See [Adding type hints with Generics](#adding-type-hints-with-generics))
|
|
146
|
-
|
|
147
|
-
**Version 0.90**
|
|
148
|
-
- All tags (`component`, `slot`, `fill`, ...) now support "self-closing" or "inline" form, where you can omit the closing tag:
|
|
149
|
-
```django
|
|
150
|
-
{# Before #}
|
|
151
|
-
{% component "button" %}{% endcomponent %}
|
|
152
|
-
{# After #}
|
|
153
|
-
{% component "button" / %}
|
|
154
|
-
```
|
|
155
|
-
- All tags now support the "dictionary key" or "aggregate" syntax (`kwarg:key=val`):
|
|
156
|
-
```django
|
|
157
|
-
{% component "button" attrs:class="hidden" %}
|
|
158
|
-
```
|
|
159
|
-
- You can change how the components are written in the template with [TagFormatter](#customizing-component-tags-with-tagformatter).
|
|
160
|
-
|
|
161
|
-
The default is `django_components.component_formatter`:
|
|
162
|
-
```django
|
|
163
|
-
{% component "button" href="..." disabled %}
|
|
164
|
-
Click me!
|
|
165
|
-
{% endcomponent %}
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
While `django_components.shorthand_component_formatter` allows you to write components like so:
|
|
169
|
-
|
|
170
|
-
```django
|
|
171
|
-
{% button href="..." disabled %}
|
|
172
|
-
Click me!
|
|
173
|
-
{% endbutton %}
|
|
174
|
-
|
|
175
|
-
🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
|
|
176
|
-
|
|
177
|
-
- Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
|
|
178
|
-
- To migrate from:
|
|
179
|
-
- `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
|
|
180
|
-
or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
|
|
181
|
-
- `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
|
|
182
|
-
- Previously, autodiscovery handled relative files in `STATICFILES_DIRS`. To align with Django, `STATICFILES_DIRS` now must be full paths ([Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#std-setting-STATICFILES_DIRS)).
|
|
183
|
-
|
|
184
|
-
🚨📢 **Version 0.81** Aligned the `render_to_response` method with the (now public) `render` method of `Component` class. Moreover, slots passed to these can now be rendered also as functions.
|
|
185
|
-
|
|
186
|
-
- BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
|
|
187
|
-
|
|
188
|
-
**Version 0.80** introduces dependency injection with the `{% provide %}` tag and `inject()` method.
|
|
189
|
-
|
|
190
|
-
🚨📢 **Version 0.79**
|
|
191
|
-
|
|
192
|
-
- BREAKING CHANGE: Default value for the `COMPONENTS.context_behavior` setting was changes from `"isolated"` to `"django"`. If you did not set this value explicitly before, this may be a breaking change. See the rationale for change [here](https://github.com/EmilStenstrom/django-components/issues/498).
|
|
193
|
-
|
|
194
|
-
🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
|
|
195
|
-
|
|
196
|
-
- Previously, the syntax was
|
|
197
|
-
`{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
|
|
198
|
-
- Now, the syntax is
|
|
199
|
-
`{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
|
|
200
|
-
|
|
201
|
-
**Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
|
|
202
|
-
|
|
203
|
-
🚨📢 **Version 0.70**
|
|
204
|
-
|
|
205
|
-
- `{% if_filled "my_slot" %}` tags were replaced with `{{ component_vars.is_filled.my_slot }}` variables.
|
|
206
|
-
- Simplified settings - `slot_context_behavior` and `context_behavior` were merged. See the [documentation](#context-behavior) for more details.
|
|
207
|
-
|
|
208
|
-
**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.
|
|
209
|
-
|
|
210
|
-
🚨📢 **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 templates that use components to the new syntax automatically.
|
|
211
|
-
|
|
212
|
-
This change is done to simplify the API in anticipation of a 1.0 release of django_components. After 1.0 we intend to be stricter with big changes like this in point releases.
|
|
213
|
-
|
|
214
|
-
**Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](#use-components-as-views) for more details.
|
|
215
|
-
|
|
216
|
-
**Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags.
|
|
217
|
-
|
|
218
|
-
**Version 0.27** adds a second installable app: _django_components.safer_staticfiles_. It provides the same behavior as _django.contrib.staticfiles_ but with extra security guarantees (more info below in Security Notes).
|
|
219
|
-
|
|
220
|
-
**Version 0.26** changes the syntax for `{% slot %}` tags. From now on, we separate defining a slot (`{% slot %}`) from filling a slot with content (`{% fill %}`). This means you will likely need to change a lot of slot tags to fill. We understand this is annoying, but it's the only way we can get support for nested slots that fill in other slots, which is a very nice featuPpre to have access to. Hoping that this will feel worth it!
|
|
221
|
-
|
|
222
|
-
**Version 0.22** starts autoimporting all files inside components subdirectores, to simplify setup. An existing project might start to get AlreadyRegistered-errors because of this. To solve this, either remove your custom loading of components, or set "autodiscover": False in settings.COMPONENTS.
|
|
223
|
-
|
|
224
|
-
**Version 0.17** renames `Component.context` and `Component.template` to `get_context_data` and `get_template_name`. The old methods still work, but emit a deprecation warning. This change was done to sync naming with Django's class based views, and make using django-components more familiar to Django users. `Component.context` and `Component.template` will be removed when version 1.0 is released.
|
|
124
|
+
Read the [Release Notes](https://github.com/EmilStenstrom/django-components/tree/master/CHANGELOG.md)
|
|
125
|
+
to see the latest features and fixes.
|
|
225
126
|
|
|
226
127
|
## Security notes 🚨
|
|
227
128
|
|
|
@@ -361,6 +262,34 @@ STATICFILES_FINDERS = [
|
|
|
361
262
|
]
|
|
362
263
|
```
|
|
363
264
|
|
|
265
|
+
### Adding support for JS and CSS
|
|
266
|
+
|
|
267
|
+
If you want to use JS or CSS with components, you will need to:
|
|
268
|
+
|
|
269
|
+
1. Add [`ComponentDependencyMiddleware`](#setting-up-componentdependencymiddleware) to `MIDDLEWARE` setting.
|
|
270
|
+
|
|
271
|
+
The middleware searches the outgoing HTML for all components that were rendered
|
|
272
|
+
to generate the HTML, and adds the JS and CSS associated with those components.
|
|
273
|
+
|
|
274
|
+
```py
|
|
275
|
+
MIDDLEWARE = [
|
|
276
|
+
...
|
|
277
|
+
"django_components.middleware.ComponentDependencyMiddleware",
|
|
278
|
+
]
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Read more in [Rendering JS/CSS dependencies](#rendering-jscss-dependencies).
|
|
282
|
+
|
|
283
|
+
2. Add django-component's URL paths to your `urlpatterns`:
|
|
284
|
+
|
|
285
|
+
```py
|
|
286
|
+
from django.urls import include, path
|
|
287
|
+
|
|
288
|
+
urlpatterns = [
|
|
289
|
+
...
|
|
290
|
+
path("", include("django_components.urls")),
|
|
291
|
+
]
|
|
292
|
+
```
|
|
364
293
|
|
|
365
294
|
### Optional
|
|
366
295
|
|
|
@@ -901,7 +830,7 @@ that allow you to specify the types of args, kwargs, slots, and
|
|
|
901
830
|
data:
|
|
902
831
|
|
|
903
832
|
```py
|
|
904
|
-
class Button(Component[Args, Kwargs, Data,
|
|
833
|
+
class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
|
|
905
834
|
...
|
|
906
835
|
```
|
|
907
836
|
|
|
@@ -940,7 +869,7 @@ class Slots(TypedDict):
|
|
|
940
869
|
# SlotContent == Union[str, SafeString]
|
|
941
870
|
another_slot: SlotContent
|
|
942
871
|
|
|
943
|
-
class Button(Component[Args, Kwargs, Data,
|
|
872
|
+
class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
|
|
944
873
|
def get_context_data(self, variable, another):
|
|
945
874
|
return {
|
|
946
875
|
"variable": variable,
|
|
@@ -1018,7 +947,7 @@ from django_components import Component, EmptyDict, EmptyTuple
|
|
|
1018
947
|
Args = EmptyTuple
|
|
1019
948
|
Kwargs = Data = Slots = EmptyDict
|
|
1020
949
|
|
|
1021
|
-
class Button(Component[Args, Kwargs, Data,
|
|
950
|
+
class Button(Component[Args, Kwargs, Slots, Data, JsData, CssData]):
|
|
1022
951
|
...
|
|
1023
952
|
```
|
|
1024
953
|
|
|
@@ -1060,7 +989,7 @@ Or you can replace `Args` with `Any` altogether, to skip the validation of args:
|
|
|
1060
989
|
|
|
1061
990
|
```py
|
|
1062
991
|
# Replaced `Args` with `Any`
|
|
1063
|
-
class Button(Component[Any, Kwargs, Data,
|
|
992
|
+
class Button(Component[Any, Kwargs, Slots, Data, JsData, CssData]):
|
|
1064
993
|
...
|
|
1065
994
|
```
|
|
1066
995
|
|
|
@@ -1089,6 +1018,20 @@ Instead, you can use **dynamic components**. Dynamic components are used in plac
|
|
|
1089
1018
|
{% endcomponent %}
|
|
1090
1019
|
```
|
|
1091
1020
|
|
|
1021
|
+
or in case you use the `django_components.component_shorthand_formatter` tag formatter:
|
|
1022
|
+
|
|
1023
|
+
```django
|
|
1024
|
+
{% dynamic is=component_name title="Cat Museu" %}
|
|
1025
|
+
{% fill "content" %}
|
|
1026
|
+
HELLO_FROM_SLOT_1
|
|
1027
|
+
{% endfill %}
|
|
1028
|
+
{% fill "sidebar" %}
|
|
1029
|
+
HELLO_FROM_SLOT_2
|
|
1030
|
+
{% endfill %}
|
|
1031
|
+
{% enddynamic %}
|
|
1032
|
+
```
|
|
1033
|
+
|
|
1034
|
+
|
|
1092
1035
|
These behave same way as regular components. You pass it the same args, kwargs, and slots as you would
|
|
1093
1036
|
to the component that you want to render.
|
|
1094
1037
|
|
|
@@ -1240,8 +1183,8 @@ NOTE: The Library instance can be accessed under `library` attribute of `Compone
|
|
|
1240
1183
|
When you are creating an instance of `ComponentRegistry`, you can define the components' behavior within the template.
|
|
1241
1184
|
|
|
1242
1185
|
The registry accepts these settings:
|
|
1243
|
-
- `
|
|
1244
|
-
- `
|
|
1186
|
+
- `context_behavior`
|
|
1187
|
+
- `tag_formatter`
|
|
1245
1188
|
|
|
1246
1189
|
```py
|
|
1247
1190
|
from django.template import Library
|
|
@@ -1251,8 +1194,8 @@ register = library = django.template.Library()
|
|
|
1251
1194
|
comp_registry = ComponentRegistry(
|
|
1252
1195
|
library=library,
|
|
1253
1196
|
settings=RegistrySettings(
|
|
1254
|
-
|
|
1255
|
-
|
|
1197
|
+
context_behavior="isolated",
|
|
1198
|
+
tag_formatter="django_components.component_formatter",
|
|
1256
1199
|
),
|
|
1257
1200
|
)
|
|
1258
1201
|
```
|
|
@@ -1336,7 +1279,7 @@ This behavior is similar to [slots in Vue](https://vuejs.org/guide/components/sl
|
|
|
1336
1279
|
In the example below we introduce two block tags that work hand in hand to make this work. These are...
|
|
1337
1280
|
|
|
1338
1281
|
- `{% slot <name> %}`/`{% endslot %}`: Declares a new slot in the component template.
|
|
1339
|
-
- `{% fill <name> %}`/`{% endfill %}`: (Used inside a `component` tag pair.) Fills a declared slot with the specified content.
|
|
1282
|
+
- `{% fill <name> %}`/`{% endfill %}`: (Used inside a `{% component %}` tag pair.) Fills a declared slot with the specified content.
|
|
1340
1283
|
|
|
1341
1284
|
Let's update our calendar component to support more customization. We'll add `slot` tag pairs to its template, _template.html_.
|
|
1342
1285
|
|
|
@@ -1355,7 +1298,9 @@ When using the component, you specify which slots you want to fill and where you
|
|
|
1355
1298
|
|
|
1356
1299
|
```htmldjango
|
|
1357
1300
|
{% component "calendar" date="2020-06-06" %}
|
|
1358
|
-
{% fill "body" %}
|
|
1301
|
+
{% fill "body" %}
|
|
1302
|
+
Can you believe it's already <span>{{ date }}</span>??
|
|
1303
|
+
{% endfill %}
|
|
1359
1304
|
{% endcomponent %}
|
|
1360
1305
|
```
|
|
1361
1306
|
|
|
@@ -1372,13 +1317,53 @@ Since the 'header' fill is unspecified, it's taken from the base template. If yo
|
|
|
1372
1317
|
</div>
|
|
1373
1318
|
```
|
|
1374
1319
|
|
|
1320
|
+
### Named slots
|
|
1321
|
+
|
|
1322
|
+
As seen in the previouse section, you can use `{% fill slot_name %}` to insert content into a specific
|
|
1323
|
+
slot.
|
|
1324
|
+
|
|
1325
|
+
You can define fills for multiple slot simply by defining them all within the `{% component %} {% endcomponent %}`
|
|
1326
|
+
tags:
|
|
1327
|
+
|
|
1328
|
+
```htmldjango
|
|
1329
|
+
{% component "calendar" date="2020-06-06" %}
|
|
1330
|
+
{% fill "header" %}
|
|
1331
|
+
Hi this is header!
|
|
1332
|
+
{% endfill %}
|
|
1333
|
+
{% fill "body" %}
|
|
1334
|
+
Can you believe it's already <span>{{ date }}</span>??
|
|
1335
|
+
{% endfill %}
|
|
1336
|
+
{% endcomponent %}
|
|
1337
|
+
```
|
|
1338
|
+
|
|
1339
|
+
You can also use `{% for %}`, `{% with %}`, or other non-component tags (even `{% include %}`)
|
|
1340
|
+
to construct the `{% fill %}` tags, **as long as these other tags do not leave any text behind!**
|
|
1341
|
+
|
|
1342
|
+
```django
|
|
1343
|
+
{% component "table" %}
|
|
1344
|
+
{% for slot_name in slots %}
|
|
1345
|
+
{% fill name=slot_name %}
|
|
1346
|
+
{{ slot_name }}
|
|
1347
|
+
{% endfill %}
|
|
1348
|
+
{% endfor %}
|
|
1349
|
+
|
|
1350
|
+
{% with slot_name="abc" %}
|
|
1351
|
+
{% fill name=slot_name %}
|
|
1352
|
+
{{ slot_name }}
|
|
1353
|
+
{% endfill %}
|
|
1354
|
+
{% endwith %}
|
|
1355
|
+
{% endcomponent %}
|
|
1356
|
+
```
|
|
1357
|
+
|
|
1375
1358
|
### Default slot
|
|
1376
1359
|
|
|
1377
1360
|
_Added in version 0.28_
|
|
1378
1361
|
|
|
1379
1362
|
As you can see, component slots lets you write reusable containers that you fill in when you use a component. This makes for highly reusable components that can be used in different circumstances.
|
|
1380
1363
|
|
|
1381
|
-
It can become tedious to use `fill` tags everywhere, especially when you're using a component that declares only one slot. To make things easier, `slot` tags can be marked with an optional keyword: `default`.
|
|
1364
|
+
It can become tedious to use `fill` tags everywhere, especially when you're using a component that declares only one slot. To make things easier, `slot` tags can be marked with an optional keyword: `default`.
|
|
1365
|
+
|
|
1366
|
+
When added to the tag (as shown below), this option lets you pass filling content directly in the body of a `component` tag pair – without using a `fill` tag. Choose carefully, though: a component template may contain at most one slot that is marked as `default`. The `default` option can be combined with other slot options, e.g. `required`.
|
|
1382
1367
|
|
|
1383
1368
|
Here's the same example as before, except with default slots and implicit filling.
|
|
1384
1369
|
|
|
@@ -1412,7 +1397,7 @@ The rendered result (exactly the same as before):
|
|
|
1412
1397
|
</div>
|
|
1413
1398
|
```
|
|
1414
1399
|
|
|
1415
|
-
You may be tempted to combine implicit fills with explicit `fill` tags. This will not work. The following component template will raise an error when
|
|
1400
|
+
You may be tempted to combine implicit fills with explicit `fill` tags. This will not work. The following component template will raise an error when rendered.
|
|
1416
1401
|
|
|
1417
1402
|
```htmldjango
|
|
1418
1403
|
{# DON'T DO THIS #}
|
|
@@ -1422,26 +1407,33 @@ You may be tempted to combine implicit fills with explicit `fill` tags. This wil
|
|
|
1422
1407
|
{% endcomponent %}
|
|
1423
1408
|
```
|
|
1424
1409
|
|
|
1425
|
-
|
|
1410
|
+
Instead, you can use a named fill with name `default` to target the default fill:
|
|
1426
1411
|
|
|
1427
1412
|
```htmldjango
|
|
1413
|
+
{# THIS WORKS #}
|
|
1428
1414
|
{% component "calendar" date="2020-06-06" %}
|
|
1429
|
-
{%
|
|
1430
|
-
|
|
1431
|
-
|
|
1415
|
+
{% fill "header" %}Totally new header!{% endfill %}
|
|
1416
|
+
{% fill "default" %}
|
|
1417
|
+
Can you believe it's already <span>{{ date }}</span>??
|
|
1418
|
+
{% endfill %}
|
|
1432
1419
|
{% endcomponent %}
|
|
1433
1420
|
```
|
|
1434
1421
|
|
|
1435
|
-
|
|
1422
|
+
NOTE: If you doubly-fill a slot, that is, that both `{% fill "default" %}` and `{% fill "header" %}`
|
|
1423
|
+
would point to the same slot, this will raise an error when rendered.
|
|
1436
1424
|
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
|
|
1440
|
-
|
|
1441
|
-
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1425
|
+
#### Accessing default slot in Python
|
|
1426
|
+
|
|
1427
|
+
Since the default slot is stored under the slot name `default`, you can access the default slot
|
|
1428
|
+
like so:
|
|
1429
|
+
|
|
1430
|
+
```py
|
|
1431
|
+
class MyTable(Component):
|
|
1432
|
+
def get_context_data(self, *args, **kwargs):
|
|
1433
|
+
default_slot = self.input.slots["default"]
|
|
1434
|
+
return {
|
|
1435
|
+
"default_slot": default_slot,
|
|
1436
|
+
}
|
|
1445
1437
|
```
|
|
1446
1438
|
|
|
1447
1439
|
### Render fill in multiple places
|
|
@@ -1488,9 +1480,7 @@ This renders:
|
|
|
1488
1480
|
#### Default and required slots
|
|
1489
1481
|
|
|
1490
1482
|
If you use a slot multiple times, you can still mark the slot as `default` or `required`.
|
|
1491
|
-
For that, you must mark
|
|
1492
|
-
|
|
1493
|
-
We recommend to mark the first occurence for consistency, e.g.:
|
|
1483
|
+
For that, you must mark each slot individually, e.g.:
|
|
1494
1484
|
|
|
1495
1485
|
```htmldjango
|
|
1496
1486
|
<div class="calendar-component">
|
|
@@ -1498,12 +1488,12 @@ We recommend to mark the first occurence for consistency, e.g.:
|
|
|
1498
1488
|
{% slot "image" default required %}Image here{% endslot %}
|
|
1499
1489
|
</div>
|
|
1500
1490
|
<div class="body">
|
|
1501
|
-
{% slot "image" %}Image here{% endslot %}
|
|
1491
|
+
{% slot "image" default required %}Image here{% endslot %}
|
|
1502
1492
|
</div>
|
|
1503
1493
|
</div>
|
|
1504
1494
|
```
|
|
1505
1495
|
|
|
1506
|
-
Which you can then use
|
|
1496
|
+
Which you can then use as regular default slot:
|
|
1507
1497
|
|
|
1508
1498
|
```htmldjango
|
|
1509
1499
|
{% component "calendar" date="2020-06-06" %}
|
|
@@ -1511,6 +1501,39 @@ Which you can then use are regular default slot:
|
|
|
1511
1501
|
{% endcomponent %}
|
|
1512
1502
|
```
|
|
1513
1503
|
|
|
1504
|
+
Since each slot is tagged individually, you can have multiple slots
|
|
1505
|
+
with the same name but different conditions.
|
|
1506
|
+
|
|
1507
|
+
E.g. in this example, we have a component that renders a user avatar
|
|
1508
|
+
- a small circular image with a profile picture of name initials.
|
|
1509
|
+
|
|
1510
|
+
If the component is given `image_src` or `name_initials` variables,
|
|
1511
|
+
the `image` slot is optional. But if neither of those are provided,
|
|
1512
|
+
you MUST fill the `image` slot.
|
|
1513
|
+
|
|
1514
|
+
```htmldjango
|
|
1515
|
+
<div class="avatar">
|
|
1516
|
+
{% if image_src %}
|
|
1517
|
+
{% slot "image" default %}
|
|
1518
|
+
<img src="{{ image_src }}" />
|
|
1519
|
+
{% endslot %}
|
|
1520
|
+
{% elif name_initials %}
|
|
1521
|
+
{% slot "image" default %}
|
|
1522
|
+
<div style="
|
|
1523
|
+
border-radius: 25px;
|
|
1524
|
+
width: 50px;
|
|
1525
|
+
height: 50px;
|
|
1526
|
+
background: blue;
|
|
1527
|
+
">
|
|
1528
|
+
{{ name_initials }}
|
|
1529
|
+
</div>
|
|
1530
|
+
{% endslot %}
|
|
1531
|
+
{% else %}
|
|
1532
|
+
{% slot "image" default required / %}
|
|
1533
|
+
{% endif %}
|
|
1534
|
+
</div>
|
|
1535
|
+
```
|
|
1536
|
+
|
|
1514
1537
|
### Accessing original content of slots
|
|
1515
1538
|
|
|
1516
1539
|
_Added in version 0.26_
|
|
@@ -1554,6 +1577,16 @@ This produces:
|
|
|
1554
1577
|
</div>
|
|
1555
1578
|
```
|
|
1556
1579
|
|
|
1580
|
+
To access the original content of a default slot, set the name to `default`:
|
|
1581
|
+
|
|
1582
|
+
```htmldjango
|
|
1583
|
+
{% component "calendar" date="2020-06-06" %}
|
|
1584
|
+
{% fill "default" default="slot_default" %}
|
|
1585
|
+
{{ slot_default }}. Have a great day!
|
|
1586
|
+
{% endfill %}
|
|
1587
|
+
{% endcomponent %}
|
|
1588
|
+
```
|
|
1589
|
+
|
|
1557
1590
|
### Conditional slots
|
|
1558
1591
|
|
|
1559
1592
|
_Added in version 0.26._
|
|
@@ -1605,6 +1638,7 @@ This is what our example looks like with `component_vars.is_filled`.
|
|
|
1605
1638
|
</div>
|
|
1606
1639
|
{% endif %}
|
|
1607
1640
|
</div>
|
|
1641
|
+
```
|
|
1608
1642
|
|
|
1609
1643
|
Here's our example with more complex branching.
|
|
1610
1644
|
|
|
@@ -1644,6 +1678,20 @@ However, you can still define slots with other special characters. In such case,
|
|
|
1644
1678
|
|
|
1645
1679
|
So a slot named `"my super-slot :)"` will be available as `component_vars.is_filled.my_super_slot___`.
|
|
1646
1680
|
|
|
1681
|
+
Same applies when you are accessing `is_filled` from within the Python, e.g.:
|
|
1682
|
+
|
|
1683
|
+
```py
|
|
1684
|
+
class MyTable(Component):
|
|
1685
|
+
def on_render_before(self, context, template) -> None:
|
|
1686
|
+
# ✅ Works
|
|
1687
|
+
if self.is_filled["my_super_slot___"]:
|
|
1688
|
+
# Do something
|
|
1689
|
+
|
|
1690
|
+
# ❌ Does not work
|
|
1691
|
+
if self.is_filled["my super-slot :)"]:
|
|
1692
|
+
# Do something
|
|
1693
|
+
```
|
|
1694
|
+
|
|
1647
1695
|
### Scoped slots
|
|
1648
1696
|
|
|
1649
1697
|
_Added in version 0.76_:
|
|
@@ -1705,8 +1753,8 @@ the slot data. In the example below, we set it to `data`:
|
|
|
1705
1753
|
|
|
1706
1754
|
```django
|
|
1707
1755
|
{% component "my_comp" %}
|
|
1708
|
-
{% fill "content" data="
|
|
1709
|
-
{{
|
|
1756
|
+
{% fill "content" data="slot_data" %}
|
|
1757
|
+
{{ slot_data.input }}
|
|
1710
1758
|
{% endfill %}
|
|
1711
1759
|
{% endcomponent %}
|
|
1712
1760
|
```
|
|
@@ -1717,8 +1765,8 @@ So this works:
|
|
|
1717
1765
|
|
|
1718
1766
|
```django
|
|
1719
1767
|
{% component "my_comp" %}
|
|
1720
|
-
{% fill "
|
|
1721
|
-
{{
|
|
1768
|
+
{% fill "default" data="slot_data" %}
|
|
1769
|
+
{{ slot_data.input }}
|
|
1722
1770
|
{% endfill %}
|
|
1723
1771
|
{% endcomponent %}
|
|
1724
1772
|
```
|
|
@@ -1813,6 +1861,31 @@ So it's possible to define a `name` key on a dictionary, and then spread that on
|
|
|
1813
1861
|
{% slot ...slot_props / %}
|
|
1814
1862
|
```
|
|
1815
1863
|
|
|
1864
|
+
### Pass through all the slots
|
|
1865
|
+
|
|
1866
|
+
You can dynamically pass all slots to a child component. This is similar to
|
|
1867
|
+
[passing all slots in Vue](https://vue-land.github.io/faq/forwarding-slots#passing-all-slots):
|
|
1868
|
+
|
|
1869
|
+
```py
|
|
1870
|
+
class MyTable(Component):
|
|
1871
|
+
def get_context_data(self, *args, **kwargs):
|
|
1872
|
+
return {
|
|
1873
|
+
"slots": self.input.slots,
|
|
1874
|
+
}
|
|
1875
|
+
|
|
1876
|
+
template: """
|
|
1877
|
+
<div>
|
|
1878
|
+
{% component "child" %}
|
|
1879
|
+
{% for slot_name in slots %}
|
|
1880
|
+
{% fill name=slot_name data="data" %}
|
|
1881
|
+
{% slot name=slot_name ...data / %}
|
|
1882
|
+
{% endfill %}
|
|
1883
|
+
{% endfor %}
|
|
1884
|
+
{% endcomponent %}
|
|
1885
|
+
</div>
|
|
1886
|
+
"""
|
|
1887
|
+
```
|
|
1888
|
+
|
|
1816
1889
|
## Accessing data passed to the component
|
|
1817
1890
|
|
|
1818
1891
|
When you call `Component.render` or `Component.render_to_response`, the inputs to these methods can be accessed from within the instance under `self.input`.
|
|
@@ -1821,6 +1894,8 @@ This means that you can use `self.input` inside:
|
|
|
1821
1894
|
- `get_context_data`
|
|
1822
1895
|
- `get_template_name`
|
|
1823
1896
|
- `get_template`
|
|
1897
|
+
- `on_render_before`
|
|
1898
|
+
- `on_render_after`
|
|
1824
1899
|
|
|
1825
1900
|
`self.input` is only defined during the execution of `Component.render`, and raises a `RuntimeError` when called outside of this context.
|
|
1826
1901
|
|
|
@@ -1831,7 +1906,7 @@ class TestComponent(Component):
|
|
|
1831
1906
|
def get_context_data(self, var1, var2, variable, another, **attrs):
|
|
1832
1907
|
assert self.input.args == (123, "str")
|
|
1833
1908
|
assert self.input.kwargs == {"variable": "test", "another": 1}
|
|
1834
|
-
assert self.input.slots == {"my_slot":
|
|
1909
|
+
assert self.input.slots == {"my_slot": ...}
|
|
1835
1910
|
assert isinstance(self.input.context, Context)
|
|
1836
1911
|
|
|
1837
1912
|
return {
|
|
@@ -1845,6 +1920,8 @@ rendered = TestComponent.render(
|
|
|
1845
1920
|
)
|
|
1846
1921
|
```
|
|
1847
1922
|
|
|
1923
|
+
NOTE: The slots in `self.input.slots` are normalized to slot functions.
|
|
1924
|
+
|
|
1848
1925
|
## Rendering HTML attributes
|
|
1849
1926
|
|
|
1850
1927
|
_New in version 0.74_:
|
|
@@ -2784,6 +2861,16 @@ Here is a list of all variables that are automatically available from within the
|
|
|
2784
2861
|
{% endif %}
|
|
2785
2862
|
```
|
|
2786
2863
|
|
|
2864
|
+
This is equivalent to checking if a given key is among the slot fills:
|
|
2865
|
+
|
|
2866
|
+
```py
|
|
2867
|
+
class MyTable(Component):
|
|
2868
|
+
def get_context_data(self, *args, **kwargs):
|
|
2869
|
+
return {
|
|
2870
|
+
"my_slot_filled": "my_slot" in self.input.slots
|
|
2871
|
+
}
|
|
2872
|
+
```
|
|
2873
|
+
|
|
2787
2874
|
## Customizing component tags with TagFormatter
|
|
2788
2875
|
|
|
2789
2876
|
_New in version 0.89_
|
|
@@ -2802,7 +2889,7 @@ Click me!
|
|
|
2802
2889
|
|
|
2803
2890
|
You can change this behaviour in the settings under the [`COMPONENTS.tag_formatter`](#tag-formatter-setting).
|
|
2804
2891
|
|
|
2805
|
-
For example, if you set the tag formatter to `django_components.
|
|
2892
|
+
For example, if you set the tag formatter to `django_components.component_shorthand_formatter`, the components will use their name as the template tags:
|
|
2806
2893
|
|
|
2807
2894
|
```django
|
|
2808
2895
|
{% button href="..." disabled %}
|
|
@@ -2838,7 +2925,7 @@ django_components provides following predefined TagFormatters:
|
|
|
2838
2925
|
{% component "button" href="..." / %}
|
|
2839
2926
|
```
|
|
2840
2927
|
|
|
2841
|
-
- **`ShorthandComponentFormatter` (`django_components.
|
|
2928
|
+
- **`ShorthandComponentFormatter` (`django_components.component_shorthand_formatter`)**
|
|
2842
2929
|
|
|
2843
2930
|
Uses the component name as start tag, and `end<component_name>`
|
|
2844
2931
|
as an end tag.
|
|
@@ -3136,15 +3223,72 @@ NOTE: The instance of the `Media` class (or it's subclass) is available under `C
|
|
|
3136
3223
|
|
|
3137
3224
|
## Rendering JS/CSS dependencies
|
|
3138
3225
|
|
|
3139
|
-
|
|
3140
|
-
|
|
3226
|
+
If:
|
|
3227
|
+
1. Your components use JS and CSS, whether inlined via `Component.js/css` or via `Component.Media.js/css`,
|
|
3228
|
+
2. And you use the `ComponentDependencyMiddleware` middleware
|
|
3229
|
+
|
|
3230
|
+
Then, by default, the components' JS and CSS will be automatically inserted into the HTML:
|
|
3231
|
+
- CSS styles will be inserted at the end of the `<head>`
|
|
3232
|
+
- JS scripts will be inserted at the end of the `<body>`
|
|
3141
3233
|
|
|
3142
|
-
|
|
3143
|
-
- `component_js_dependencies` - Renders only JS
|
|
3144
|
-
- `component_css_dependencies` - Reneders only CSS
|
|
3234
|
+
If you want to place the dependencies elsewhere, you can override that with following Django template tags:
|
|
3145
3235
|
|
|
3146
|
-
|
|
3147
|
-
|
|
3236
|
+
- `{% component_js_dependencies %}` - Renders only JS
|
|
3237
|
+
- `{% component_css_dependencies %}` - Renders only CSS
|
|
3238
|
+
|
|
3239
|
+
So if you have a component with JS and CSS:
|
|
3240
|
+
|
|
3241
|
+
```py
|
|
3242
|
+
from django_components import Component, types
|
|
3243
|
+
|
|
3244
|
+
class MyButton(Component):
|
|
3245
|
+
template: types.django_html = """
|
|
3246
|
+
<button class="my-button">
|
|
3247
|
+
Click me!
|
|
3248
|
+
</button>
|
|
3249
|
+
"""
|
|
3250
|
+
js: types.js = """
|
|
3251
|
+
for (const btnEl of document.querySelectorAll(".my-button")) {
|
|
3252
|
+
btnEl.addEventListener("click", () => {
|
|
3253
|
+
console.log("BUTTON CLICKED!");
|
|
3254
|
+
});
|
|
3255
|
+
}
|
|
3256
|
+
"""
|
|
3257
|
+
css: types.css """
|
|
3258
|
+
.my-button {
|
|
3259
|
+
background: green;
|
|
3260
|
+
}
|
|
3261
|
+
"""
|
|
3262
|
+
|
|
3263
|
+
class Media:
|
|
3264
|
+
js = ["/extra/script.js"]
|
|
3265
|
+
css = ["/extra/style.css"]
|
|
3266
|
+
```
|
|
3267
|
+
|
|
3268
|
+
Then the inlined JS and the scripts in `Media.js` will be rendered at the default place,
|
|
3269
|
+
or in `{% component_js_dependencies %}`.
|
|
3270
|
+
|
|
3271
|
+
And the inlined CSS and the styles in `Media.css` will be rendered at the default place,
|
|
3272
|
+
or in `{% component_css_dependencies %}`.
|
|
3273
|
+
|
|
3274
|
+
And if you don't specify `{% component_dependencies %}` tags, it is the equivalent of:
|
|
3275
|
+
|
|
3276
|
+
```django
|
|
3277
|
+
<!doctype html>
|
|
3278
|
+
<html>
|
|
3279
|
+
<head>
|
|
3280
|
+
<title>MyPage</title>
|
|
3281
|
+
...
|
|
3282
|
+
{% component_css_dependencies %}
|
|
3283
|
+
</head>
|
|
3284
|
+
<body>
|
|
3285
|
+
<main>
|
|
3286
|
+
...
|
|
3287
|
+
</main>
|
|
3288
|
+
{% component_js_dependencies %}
|
|
3289
|
+
</body>
|
|
3290
|
+
</html>
|
|
3291
|
+
```
|
|
3148
3292
|
|
|
3149
3293
|
### Setting Up `ComponentDependencyMiddleware`
|
|
3150
3294
|
|
|
@@ -3160,15 +3304,115 @@ MIDDLEWARE = [
|
|
|
3160
3304
|
]
|
|
3161
3305
|
```
|
|
3162
3306
|
|
|
3163
|
-
|
|
3307
|
+
### `render_dependencies` and deep-dive into rendering JS / CSS without the middleware
|
|
3164
3308
|
|
|
3165
|
-
|
|
3166
|
-
|
|
3167
|
-
|
|
3168
|
-
|
|
3169
|
-
|
|
3309
|
+
For most scenarios, using the `ComponentDependencyMiddleware` middleware will be just fine.
|
|
3310
|
+
|
|
3311
|
+
However, this section is for you if you want to:
|
|
3312
|
+
- Render HTML that will NOT be sent as a server response
|
|
3313
|
+
- Insert pre-rendered HTML into another component
|
|
3314
|
+
- Render HTML fragments (partials)
|
|
3315
|
+
|
|
3316
|
+
Every time there is an HTML string that has parts which were rendered using components,
|
|
3317
|
+
and any of those components has JS / CSS, then this HTML string MUST be processed with `render_dependencies`.
|
|
3318
|
+
|
|
3319
|
+
It is actually `render_dependencies` that finds all used components in the HTML string,
|
|
3320
|
+
and inserts the component's JS and CSS into `{% component_dependencies %}` tags, or at the default locations.
|
|
3321
|
+
|
|
3322
|
+
#### Render JS / CSS without the middleware
|
|
3323
|
+
|
|
3324
|
+
The `ComponentDependencyMiddleware` middleware just calls `render_dependencies`, passing in the HTML
|
|
3325
|
+
content. So if you rendered a template that contained `{% components %}` tags, instead of the middleware,
|
|
3326
|
+
you MUST pass the result through `render_dependencies`:
|
|
3327
|
+
|
|
3328
|
+
```py
|
|
3329
|
+
from django.template.base import Template
|
|
3330
|
+
from django.template.context import Context
|
|
3331
|
+
from django_component import render_dependencies
|
|
3332
|
+
|
|
3333
|
+
template = Template("""
|
|
3334
|
+
{% load component_tags %}
|
|
3335
|
+
<!doctype html>
|
|
3336
|
+
<html>
|
|
3337
|
+
<head>
|
|
3338
|
+
<title>MyPage</title>
|
|
3339
|
+
</head>
|
|
3340
|
+
<body>
|
|
3341
|
+
<main>
|
|
3342
|
+
{% component "my_button" %}
|
|
3343
|
+
Click me!
|
|
3344
|
+
{% endcomponent %}
|
|
3345
|
+
</main>
|
|
3346
|
+
</body>
|
|
3347
|
+
</html>
|
|
3348
|
+
""")
|
|
3349
|
+
|
|
3350
|
+
rendered = template.render(Context({}))
|
|
3351
|
+
rendered = render_dependencies(rendered)
|
|
3170
3352
|
```
|
|
3171
3353
|
|
|
3354
|
+
Same applies if you render a template using Django's [`django.shortcuts.render`](https://docs.djangoproject.com/en/5.1/topics/http/shortcuts/#render):
|
|
3355
|
+
|
|
3356
|
+
```py
|
|
3357
|
+
from django.shortcuts import render
|
|
3358
|
+
|
|
3359
|
+
def my_view(request):
|
|
3360
|
+
rendered = render(request, "pages/home.html")
|
|
3361
|
+
rendered = render_dependencies(rendered)
|
|
3362
|
+
return rendered
|
|
3363
|
+
```
|
|
3364
|
+
|
|
3365
|
+
Alternatively, when you render HTML with `Component.render()` or `Component.render_to_response()`,
|
|
3366
|
+
these automatically call `render_dependencies()` for you, so you don't have to:
|
|
3367
|
+
|
|
3368
|
+
```py
|
|
3369
|
+
from django_components import Component
|
|
3370
|
+
|
|
3371
|
+
class MyButton(Component):
|
|
3372
|
+
...
|
|
3373
|
+
|
|
3374
|
+
# No need to call `render_dependencies()`
|
|
3375
|
+
rendered = MyButton.render()
|
|
3376
|
+
```
|
|
3377
|
+
|
|
3378
|
+
#### Inserting pre-rendered HTML into another component
|
|
3379
|
+
|
|
3380
|
+
In previous section we've shown that `render_dependencies()` does NOT need to be called
|
|
3381
|
+
when you render a component via `Component.render()`.
|
|
3382
|
+
|
|
3383
|
+
API of django-components makes it possible to compose components in a "React-like" way,
|
|
3384
|
+
where we pre-render a piece of HTML and then insert it into a larger structure.
|
|
3385
|
+
|
|
3386
|
+
To do this, you must add `render_dependencies=False` to the nested components:
|
|
3387
|
+
|
|
3388
|
+
```py
|
|
3389
|
+
card_actions = CardActions.render(
|
|
3390
|
+
kwargs={"editable": editable},
|
|
3391
|
+
render_dependencies=False,
|
|
3392
|
+
)
|
|
3393
|
+
|
|
3394
|
+
card = Card.render(
|
|
3395
|
+
slots={"actions": card_actions},
|
|
3396
|
+
render_dependencies=False,
|
|
3397
|
+
)
|
|
3398
|
+
|
|
3399
|
+
page = MyPage.render(
|
|
3400
|
+
slots={"card": card},
|
|
3401
|
+
)
|
|
3402
|
+
```
|
|
3403
|
+
|
|
3404
|
+
Why is `render_dependencies=False` required?
|
|
3405
|
+
|
|
3406
|
+
As mentioned earlier, each time we call `Component.render()`, we also call `render_dependencies()`.
|
|
3407
|
+
|
|
3408
|
+
However, there is a problem here - When we call `render_dependencies()` inside `CardActions.render()`,
|
|
3409
|
+
we extract the info on components' JS and CSS from the HTML. But the template of `CardActions`
|
|
3410
|
+
contains no `{% component_depedencies %}` tags, and nor `<head>` nor `<body>` HTML tags.
|
|
3411
|
+
So the component's JS and CSS will NOT be inserted, and will be lost.
|
|
3412
|
+
|
|
3413
|
+
To work around this, you must set `render_dependencies=False` when rendering pieces of HTML with `Component.render()`
|
|
3414
|
+
and inserting them into larger structures.
|
|
3415
|
+
|
|
3172
3416
|
## Available settings
|
|
3173
3417
|
|
|
3174
3418
|
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.
|
|
@@ -3699,17 +3943,17 @@ You can publish and share your components for others to use. Here are the steps
|
|
|
3699
3943
|
comp_registry = ComponentRegistry(
|
|
3700
3944
|
library=library,
|
|
3701
3945
|
settings=RegistrySettings(
|
|
3702
|
-
|
|
3703
|
-
|
|
3946
|
+
context_behavior="isolated",
|
|
3947
|
+
tag_formatter="django_components.component_formatter",
|
|
3704
3948
|
),
|
|
3705
3949
|
)
|
|
3706
3950
|
```
|
|
3707
3951
|
|
|
3708
3952
|
As you can see above, this is also the place where we configure how our components should behave, using the `settings` argument. If omitted, default settings are used.
|
|
3709
3953
|
|
|
3710
|
-
For library authors, we recommend setting `
|
|
3954
|
+
For library authors, we recommend setting `context_behavior` to `"isolated"`, so that the state cannot leak into the components, and so the components' behavior is configured solely through the inputs. This means that the components will be more predictable and easier to debug.
|
|
3711
3955
|
|
|
3712
|
-
Next, you can decide how will others use your components by settingt the `
|
|
3956
|
+
Next, you can decide how will others use your components by settingt the `tag_formatter` options.
|
|
3713
3957
|
|
|
3714
3958
|
If omitted or set to `"django_components.component_formatter"`,
|
|
3715
3959
|
your components will be used like this:
|
|
@@ -3775,7 +4019,7 @@ You can publish and share your components for others to use. Here are the steps
|
|
|
3775
4019
|
# Define the component
|
|
3776
4020
|
# NOTE: Don't forget to set the `registry`!
|
|
3777
4021
|
@register("my_menu", registry=comp_registry)
|
|
3778
|
-
class MyMenu(Component[MyMenuArgs, MyMenuProps, MyMenuSlots, Any]):
|
|
4022
|
+
class MyMenu(Component[MyMenuArgs, MyMenuProps, MyMenuSlots, Any, Any, Any]):
|
|
3779
4023
|
def get_context_data(
|
|
3780
4024
|
self,
|
|
3781
4025
|
*args,
|
|
@@ -4033,5 +4277,8 @@ twine upload --repository pypi dist/* -u __token__ -p <PyPI_TOKEN>
|
|
|
4033
4277
|
|
|
4034
4278
|
### Development guides
|
|
4035
4279
|
|
|
4036
|
-
|
|
4037
|
-
|
|
4280
|
+
Deep dive into how django_components' features are implemented.
|
|
4281
|
+
|
|
4282
|
+
- [Slot rendering](https://github.com/EmilStenstrom/django-components/blob/master/docs/devguides/slot_rendering.md)
|
|
4283
|
+
- [Slots and blocks](https://github.com/EmilStenstrom/django-components/blob/master/docs/devguides/slots_and_blocks.md)
|
|
4284
|
+
- [JS and CSS dependency management](https://github.com/EmilStenstrom/django-components/blob/master/docs/devguides/dependency_mgmt.md)
|