django-components 0.96__tar.gz → 0.100__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.96/src/django_components.egg-info → django_components-0.100}/PKG-INFO +251 -65
- {django_components-0.96 → django_components-0.100}/README.md +250 -64
- {django_components-0.96 → django_components-0.100}/pyproject.toml +1 -1
- {django_components-0.96 → django_components-0.100}/src/django_components/__init__.py +1 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/app_settings.py +55 -1
- {django_components-0.96 → django_components-0.100}/src/django_components/autodiscover.py +8 -16
- {django_components-0.96 → django_components-0.100}/src/django_components/component.py +86 -20
- {django_components-0.96 → django_components-0.100}/src/django_components/component_media.py +3 -3
- django_components-0.100/src/django_components/finders.py +154 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/slots.py +19 -13
- django_components-0.100/src/django_components/template.py +42 -0
- django_components-0.100/src/django_components/template_loader.py +111 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/templatetags/component_tags.py +1 -1
- {django_components-0.96 → django_components-0.100}/src/django_components/utils.py +55 -1
- {django_components-0.96 → django_components-0.100/src/django_components.egg-info}/PKG-INFO +251 -65
- {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/SOURCES.txt +4 -3
- {django_components-0.96 → django_components-0.100}/tests/test_component.py +32 -5
- {django_components-0.96 → django_components-0.100}/tests/test_component_as_view.py +22 -0
- {django_components-0.96 → django_components-0.100}/tests/test_component_media.py +4 -6
- django_components-0.100/tests/test_finders.py +210 -0
- {django_components-0.96 → django_components-0.100}/tests/test_registry.py +6 -2
- django_components-0.100/tests/test_template.py +67 -0
- django_components-0.100/tests/test_template_loader.py +181 -0
- {django_components-0.96 → django_components-0.100}/tests/test_templatetags_slot_fill.py +1 -1
- {django_components-0.96 → django_components-0.100}/tests/testutils.py +4 -0
- django_components-0.96/src/django_components/safer_staticfiles/apps.py +0 -22
- django_components-0.96/src/django_components/template_loader.py +0 -61
- django_components-0.96/src/django_components/templatetags/__init__.py +0 -0
- django_components-0.96/tests/test_safer_staticfiles.py +0 -103
- django_components-0.96/tests/test_template_loader.py +0 -76
- {django_components-0.96 → django_components-0.100}/LICENSE +0 -0
- {django_components-0.96 → django_components-0.100}/setup.cfg +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/apps.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/attributes.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/component_registry.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/components/__init__.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/components/dynamic.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/context.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/expression.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/library.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/logger.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/management/__init__.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/middleware.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/node.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/provide.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/py.typed +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/tag_formatter.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/template_parser.py +0 -0
- {django_components-0.96/src/django_components/safer_staticfiles → django_components-0.100/src/django_components/templatetags}/__init__.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components/types.py +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_attributes.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_autodiscover.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_command_startcomponent.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_context.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_expression.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_settings.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_tag_formatter.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_template_parser.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_templatetags.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_templatetags_component.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_templatetags_provide.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_templatetags_templating.py +0 -0
- {django_components-0.96 → django_components-0.100}/tests/test_utils.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: django_components
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.100
|
|
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
|
|
@@ -28,19 +28,24 @@ Requires-Dist: Django>=4.2
|
|
|
28
28
|
|
|
29
29
|
[**Docs (Work in progress)**](https://EmilStenstrom.github.io/django-components/latest/)
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
Django-components is a package that introduces component-based architecture to Django's server-side rendering. It aims to combine Django's templating system with the modularity seen in modern frontend frameworks.
|
|
32
32
|
|
|
33
33
|
## Features
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
1. 🧩 **Reusability:** Allows creation of self-contained, reusable UI elements.
|
|
36
|
+
2. 📦 **Encapsulation:** Each component can include its own HTML, CSS, and JavaScript.
|
|
37
|
+
3. 🚀 **Server-side rendering:** Components render on the server, improving initial load times and SEO.
|
|
38
|
+
4. 🐍 **Django integration:** Works within the Django ecosystem, using familiar concepts like template tags.
|
|
39
|
+
5. ⚡ **Asynchronous loading:** Components can render independently opening up for integration with JS frameworks like HTMX or AlpineJS.
|
|
36
40
|
|
|
37
|
-
|
|
38
|
-
- 📁 **Single file components**: Keep your Python, CSS, Javascript and HTML in one place (if you wish)
|
|
39
|
-
- 🎰 **Slots**: Define slots in your components to make them more flexible.
|
|
40
|
-
- 💻 **CLI**: A command line interface to help you create new components.
|
|
41
|
-
- 🚀 **Wide compatibility**: Works with [modern and LTS versions of Django](https://emilstenstrom.github.io/django-components/latest/user_guide/requirements_compatibility).
|
|
42
|
-
- **Load assets**: Automatically load the right CSS and Javascript files for your components, with [our middleware](https://emilstenstrom.github.io/django-components/latest/user_guide/creating_using_components/middleware).
|
|
41
|
+
Potential benefits:
|
|
43
42
|
|
|
43
|
+
- 🔄 Reduced code duplication
|
|
44
|
+
- 🛠️ Improved maintainability through modular design
|
|
45
|
+
- 🧠 Easier management of complex UIs
|
|
46
|
+
- 🤝 Potential for better collaboration between frontend and backend developers
|
|
47
|
+
|
|
48
|
+
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.
|
|
44
49
|
|
|
45
50
|
## Summary
|
|
46
51
|
|
|
@@ -56,7 +61,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
56
61
|
<div class="calendar-component">Today's date is <span>2015-06-19</span></div>
|
|
57
62
|
```
|
|
58
63
|
|
|
59
|
-
[See the example project](
|
|
64
|
+
[See the example project](https://github.com/EmilStenstrom/django-components/tree/master/sampleproject) or read on to learn about the details!
|
|
60
65
|
|
|
61
66
|
## Table of Contents
|
|
62
67
|
|
|
@@ -95,6 +100,24 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
95
100
|
|
|
96
101
|
## Release notes
|
|
97
102
|
|
|
103
|
+
🚨📢 **Version 0.100**
|
|
104
|
+
- BREAKING CHANGE:
|
|
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
|
+
|
|
98
121
|
**Version 0.96**
|
|
99
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))
|
|
100
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))
|
|
@@ -117,7 +140,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
117
140
|
🚨📢 **Version 0.92**
|
|
118
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))
|
|
119
142
|
|
|
120
|
-
- The inputs (args, kwargs, slots, context, ...) that you pass to `Component.render()` can be accessed from within `get_context_data`, `
|
|
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))
|
|
121
144
|
|
|
122
145
|
- Typing: `Component` class supports generics that specify types for `Component.render` (See [Adding type hints with Generics](#adding-type-hints-with-generics))
|
|
123
146
|
|
|
@@ -208,14 +231,25 @@ _You are advised to read this section before using django-components in producti
|
|
|
208
231
|
|
|
209
232
|
Components can be organized however you prefer.
|
|
210
233
|
That said, our prefered way is to keep the files of a component close together by bundling them in the same directory.
|
|
234
|
+
|
|
211
235
|
This means that files containing backend logic, such as Python modules and HTML templates, live in the same directory as static files, e.g. JS and CSS.
|
|
212
236
|
|
|
213
|
-
|
|
237
|
+
From v0.100 onwards, we keep component files (as defined by [`COMPONENTS.dirs`](#dirs) and [`COMPONENTS.app_dirs`](#app_dirs)) separate from the rest of the static
|
|
238
|
+
files (defined by `STATICFILES_DIRS`). That way, the Python and HTML files are NOT exposed by the server. Only the static JS, CSS, and [other common formats](#static_files_allowed).
|
|
239
|
+
|
|
240
|
+
> NOTE: If you need to expose different file formats, you can configure these with [`COMPONENTS.static_files_allowed`](#static_files_allowed)
|
|
241
|
+
and [`COMPONENTS.static_files_forbidden`](#static_files_forbidden).
|
|
242
|
+
|
|
243
|
+
<!-- # TODO_REMOVE_IN_V1 - Remove mentions of safer_staticfiles in V1 -->
|
|
244
|
+
#### Static files prior to v0.100
|
|
245
|
+
|
|
246
|
+
Prior to v0.100, if your were using _django.contrib.staticfiles_ to collect static files, no distinction was made between the different kinds of files.
|
|
247
|
+
|
|
214
248
|
As a result, your Python code and templates may inadvertently become available on your static file server.
|
|
215
249
|
You probably don't want this, as parts of your backend logic will be exposed, posing a **potential security vulnerability**.
|
|
216
250
|
|
|
217
|
-
|
|
218
|
-
It
|
|
251
|
+
From _v0.27_ until _v0.100_, django-components shipped with an additional installable app _django_components.**safer_staticfiles**_.
|
|
252
|
+
It was a drop-in replacement for _django.contrib.staticfiles_.
|
|
219
253
|
Its behavior is 100% identical except it ignores .py and .html files, meaning these will not end up on your static files server.
|
|
220
254
|
To use it, add it to INSTALLED_APPS and remove _django.contrib.staticfiles_.
|
|
221
255
|
|
|
@@ -243,15 +277,15 @@ python manage.py runserver
|
|
|
243
277
|
```
|
|
244
278
|
|
|
245
279
|
For a step-by-step guide on deploying production server with static files,
|
|
246
|
-
[see the demo project](
|
|
280
|
+
[see the demo project](https://github.com/EmilStenstrom/django-components/tree/master/sampleproject).
|
|
247
281
|
|
|
248
282
|
## Installation
|
|
249
283
|
|
|
250
|
-
1. Install
|
|
284
|
+
1. Install `django_components` into your environment:
|
|
251
285
|
|
|
252
286
|
> `pip install django_components`
|
|
253
287
|
|
|
254
|
-
2.
|
|
288
|
+
2. Load `django_components` into Django by adding it into `INSTALLED_APPS` in settings.py:
|
|
255
289
|
|
|
256
290
|
```python
|
|
257
291
|
INSTALLED_APPS = [
|
|
@@ -260,13 +294,33 @@ For a step-by-step guide on deploying production server with static files,
|
|
|
260
294
|
]
|
|
261
295
|
```
|
|
262
296
|
|
|
263
|
-
3.
|
|
297
|
+
3. `BASE_DIR` setting is required. Ensure that it is defined in settings.py:
|
|
264
298
|
|
|
265
299
|
```py
|
|
266
300
|
BASE_DIR = Path(__file__).resolve().parent.parent
|
|
267
301
|
```
|
|
268
302
|
|
|
269
|
-
4.
|
|
303
|
+
4. Add / modify [`COMPONENTS.dirs`](#dirs) and / or [`COMPONENTS.app_dirs`](#app_dirs) so django_components knows where to find component HTML, JS and CSS files:
|
|
304
|
+
|
|
305
|
+
```python
|
|
306
|
+
COMPONENTS = {
|
|
307
|
+
"dirs": [
|
|
308
|
+
...,
|
|
309
|
+
os.path.join(BASE_DIR, "components"),
|
|
310
|
+
],
|
|
311
|
+
}
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
If `COMPONENTS.dirs` is omitted, django-components will by default look for a top-level `/components` directory,
|
|
315
|
+
`{BASE_DIR}/components`.
|
|
316
|
+
|
|
317
|
+
Irrespective of `COMPONENTS.dirs`, django_components will also load components from app-level directories, e.g. `my-app/components/`.
|
|
318
|
+
The directories within apps are configured with [`COMPONENTS.app_dirs`](#app_dirs), and the default is `[app]/components`.
|
|
319
|
+
|
|
320
|
+
NOTE: The input to `COMPONENTS.dirs` is the same as for `STATICFILES_DIRS`, and the paths must be full paths. [See Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#staticfiles-dirs).
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
5. Next, to make Django load component HTML files as Django templates, modify `TEMPLATES` section of settings.py as follows:
|
|
270
324
|
|
|
271
325
|
- _Remove `'APP_DIRS': True,`_
|
|
272
326
|
- 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)
|
|
@@ -295,19 +349,18 @@ For a step-by-step guide on deploying production server with static files,
|
|
|
295
349
|
]
|
|
296
350
|
```
|
|
297
351
|
|
|
298
|
-
|
|
352
|
+
6. Lastly, be able to serve the component JS and CSS files as static files, modify `STATICFILES_FINDERS` section of settings.py as follows:
|
|
299
353
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
354
|
+
```py
|
|
355
|
+
STATICFILES_FINDERS = [
|
|
356
|
+
# Default finders
|
|
357
|
+
"django.contrib.staticfiles.finders.FileSystemFinder",
|
|
358
|
+
"django.contrib.staticfiles.finders.AppDirectoriesFinder",
|
|
359
|
+
# Django components
|
|
360
|
+
"django_components.finders.ComponentsFileSystemFinder",
|
|
361
|
+
]
|
|
362
|
+
```
|
|
309
363
|
|
|
310
|
-
NOTE: The paths in `STATICFILES_DIRS` must be full paths. [See Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#staticfiles-dirs).
|
|
311
364
|
|
|
312
365
|
### Optional
|
|
313
366
|
|
|
@@ -407,11 +460,13 @@ from django_components import Component, register
|
|
|
407
460
|
@register("calendar")
|
|
408
461
|
class Calendar(Component):
|
|
409
462
|
# Templates inside `[your apps]/components` dir and `[project root]/components` dir
|
|
410
|
-
# will be automatically found.
|
|
411
|
-
# you can override method `get_template_name` instead of specifying `template_name`.
|
|
463
|
+
# will be automatically found.
|
|
412
464
|
#
|
|
413
|
-
# `template_name` can be relative to dir where `calendar.py` is, or relative to
|
|
465
|
+
# `template_name` can be relative to dir where `calendar.py` is, or relative to COMPONENTS.dirs
|
|
414
466
|
template_name = "template.html"
|
|
467
|
+
# Or
|
|
468
|
+
def get_template_name(context):
|
|
469
|
+
return f"template-{context['name']}.html"
|
|
415
470
|
|
|
416
471
|
# This component takes one parameter, a date string to show in the template
|
|
417
472
|
def get_context_data(self, date):
|
|
@@ -419,7 +474,7 @@ class Calendar(Component):
|
|
|
419
474
|
"date": date,
|
|
420
475
|
}
|
|
421
476
|
|
|
422
|
-
# Both `css` and `js` can be relative to dir where `calendar.py` is, or relative to
|
|
477
|
+
# Both `css` and `js` can be relative to dir where `calendar.py` is, or relative to COMPONENTS.dirs
|
|
423
478
|
class Media:
|
|
424
479
|
css = "style.css"
|
|
425
480
|
js = "script.js"
|
|
@@ -1240,7 +1295,7 @@ class MyAppConfig(AppConfig):
|
|
|
1240
1295
|
|
|
1241
1296
|
However, there's a simpler way!
|
|
1242
1297
|
|
|
1243
|
-
By default, the Python files in the `
|
|
1298
|
+
By default, the Python files in the `COMPONENTS.dirs` directories (or app-level `[app]/components/`) are auto-imported in order to auto-register the components.
|
|
1244
1299
|
|
|
1245
1300
|
Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
|
|
1246
1301
|
|
|
@@ -1599,17 +1654,17 @@ Consider a component with slot(s). This component may do some processing on the
|
|
|
1599
1654
|
```py
|
|
1600
1655
|
@register("my_comp")
|
|
1601
1656
|
class MyComp(Component):
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
|
-
|
|
1605
|
-
|
|
1606
|
-
|
|
1607
|
-
|
|
1608
|
-
|
|
1657
|
+
template = """
|
|
1658
|
+
<div>
|
|
1659
|
+
{% slot "content" default %}
|
|
1660
|
+
input: {{ input }}
|
|
1661
|
+
{% endslot %}
|
|
1662
|
+
</div>
|
|
1663
|
+
"""
|
|
1609
1664
|
|
|
1610
|
-
|
|
1611
|
-
|
|
1612
|
-
|
|
1665
|
+
def get_context_data(self, input):
|
|
1666
|
+
processed_input = do_something(input)
|
|
1667
|
+
return {"input": processed_input}
|
|
1613
1668
|
```
|
|
1614
1669
|
|
|
1615
1670
|
You may want to design a component so that users of your component can still access the `input` variable, so they don't have to recompute it.
|
|
@@ -1628,17 +1683,17 @@ To pass the data to the `slot` tag, simply pass them as keyword attributes (`key
|
|
|
1628
1683
|
```py
|
|
1629
1684
|
@register("my_comp")
|
|
1630
1685
|
class MyComp(Component):
|
|
1631
|
-
|
|
1632
|
-
|
|
1633
|
-
|
|
1634
|
-
|
|
1635
|
-
|
|
1636
|
-
|
|
1637
|
-
|
|
1638
|
-
|
|
1639
|
-
|
|
1640
|
-
|
|
1641
|
-
|
|
1686
|
+
template = """
|
|
1687
|
+
<div>
|
|
1688
|
+
{% slot "content" default input=input %}
|
|
1689
|
+
input: {{ input }}
|
|
1690
|
+
{% endslot %}
|
|
1691
|
+
</div>
|
|
1692
|
+
"""
|
|
1693
|
+
|
|
1694
|
+
def get_context_data(self, input):
|
|
1695
|
+
processed_input = do_something(input)
|
|
1696
|
+
return {
|
|
1642
1697
|
"input": processed_input,
|
|
1643
1698
|
}
|
|
1644
1699
|
```
|
|
@@ -1766,7 +1821,7 @@ When you call `Component.render` or `Component.render_to_response`, the inputs t
|
|
|
1766
1821
|
This means that you can use `self.input` inside:
|
|
1767
1822
|
- `get_context_data`
|
|
1768
1823
|
- `get_template_name`
|
|
1769
|
-
- `
|
|
1824
|
+
- `get_template`
|
|
1770
1825
|
|
|
1771
1826
|
`self.input` is defined only for the duration of `Component.render`, and raises `RuntimeError` when called outside of this.
|
|
1772
1827
|
|
|
@@ -1972,13 +2027,13 @@ Assuming that:
|
|
|
1972
2027
|
class_from_var = "from-var"
|
|
1973
2028
|
|
|
1974
2029
|
attrs = {
|
|
1975
|
-
|
|
1976
|
-
|
|
2030
|
+
"class": "from-attrs",
|
|
2031
|
+
"type": "submit",
|
|
1977
2032
|
}
|
|
1978
2033
|
|
|
1979
2034
|
defaults = {
|
|
1980
|
-
|
|
1981
|
-
|
|
2035
|
+
"class": "from-defaults",
|
|
2036
|
+
"role": "button",
|
|
1982
2037
|
}
|
|
1983
2038
|
```
|
|
1984
2039
|
|
|
@@ -2883,9 +2938,9 @@ class Calendar(Component):
|
|
|
2883
2938
|
|
|
2884
2939
|
In the example above, the files are defined relative to the directory where `component.py` is.
|
|
2885
2940
|
|
|
2886
|
-
Alternatively, you can specify the file paths relative to the directories set in `
|
|
2941
|
+
Alternatively, you can specify the file paths relative to the directories set in `COMPONENTS.dirs` or `COMPONENTS.app_dirs`.
|
|
2887
2942
|
|
|
2888
|
-
Assuming that `
|
|
2943
|
+
Assuming that `COMPONENTS.dirs` contains path `[project root]/components`, we can rewrite the example as:
|
|
2889
2944
|
|
|
2890
2945
|
```py
|
|
2891
2946
|
# In a file [project root]/components/calendar/calendar.py
|
|
@@ -2981,7 +3036,7 @@ In the example [above](#supported-types-for-file-paths), you could see that when
|
|
|
2981
3036
|
|
|
2982
3037
|
This is an extension of Django's [Paths as objects](https://docs.djangoproject.com/en/5.0/topics/forms/media/#paths-as-objects) feature, where "safe" strings are taken as is, and accessed only at render time.
|
|
2983
3038
|
|
|
2984
|
-
Because of that, the paths defined as "safe" strings are NEVER resolved, neither relative to component's directory, nor relative to `
|
|
3039
|
+
Because of that, the paths defined as "safe" strings are NEVER resolved, neither relative to component's directory, nor relative to `COMPONENTS.dirs`.
|
|
2985
3040
|
|
|
2986
3041
|
"Safe" strings can be used to lazily resolve a path, or to customize the `<script>` or `<link>` tag for individual paths:
|
|
2987
3042
|
|
|
@@ -3101,10 +3156,27 @@ Here's overview of all available settings and their defaults:
|
|
|
3101
3156
|
COMPONENTS = {
|
|
3102
3157
|
"autodiscover": True,
|
|
3103
3158
|
"context_behavior": "django", # "django" | "isolated"
|
|
3159
|
+
"dirs": [BASE_DIR / "components"], # Root-level "components" dirs, e.g. `/path/to/proj/components/`
|
|
3160
|
+
"app_dirs": ["components"], # App-level "components" dirs, e.g. `[app]/components/`
|
|
3104
3161
|
"dynamic_component_name": "dynamic",
|
|
3105
3162
|
"libraries": [], # ["mysite.components.forms", ...]
|
|
3106
3163
|
"multiline_tags": True,
|
|
3107
3164
|
"reload_on_template_change": False,
|
|
3165
|
+
"static_files_allowed": [
|
|
3166
|
+
".css",
|
|
3167
|
+
".js",
|
|
3168
|
+
# Images
|
|
3169
|
+
".apng", ".png", ".avif", ".gif", ".jpg",
|
|
3170
|
+
".jpeg", ".jfif", ".pjpeg", ".pjp", ".svg",
|
|
3171
|
+
".webp", ".bmp", ".ico", ".cur", ".tif", ".tiff",
|
|
3172
|
+
# Fonts
|
|
3173
|
+
".eot", ".ttf", ".woff", ".otf", ".svg",
|
|
3174
|
+
],
|
|
3175
|
+
"static_files_forbidden": [
|
|
3176
|
+
".html", ".django", ".dj", ".tpl",
|
|
3177
|
+
# Python files
|
|
3178
|
+
".py", ".pyc",
|
|
3179
|
+
],
|
|
3108
3180
|
"tag_formatter": "django_components.component_formatter",
|
|
3109
3181
|
"template_cache_size": 128,
|
|
3110
3182
|
}
|
|
@@ -3162,6 +3234,46 @@ COMPONENTS = {
|
|
|
3162
3234
|
}
|
|
3163
3235
|
```
|
|
3164
3236
|
|
|
3237
|
+
### `dirs`
|
|
3238
|
+
|
|
3239
|
+
Specify the directories that contain your components.
|
|
3240
|
+
|
|
3241
|
+
Directories must be full paths, same as with STATICFILES_DIRS.
|
|
3242
|
+
|
|
3243
|
+
These locations are searched during autodiscovery, or when you define HTML, JS, or CSS as
|
|
3244
|
+
a separate file.
|
|
3245
|
+
|
|
3246
|
+
```py
|
|
3247
|
+
COMPONENTS = {
|
|
3248
|
+
"dirs": [BASE_DIR / "components"],
|
|
3249
|
+
}
|
|
3250
|
+
```
|
|
3251
|
+
|
|
3252
|
+
### `app_dirs`
|
|
3253
|
+
|
|
3254
|
+
Specify the app-level directories that contain your components.
|
|
3255
|
+
|
|
3256
|
+
Directories must be relative to app, e.g.:
|
|
3257
|
+
|
|
3258
|
+
```py
|
|
3259
|
+
COMPONENTS = {
|
|
3260
|
+
"app_dirs": ["my_comps"], # To search for [app]/my_comps
|
|
3261
|
+
}
|
|
3262
|
+
```
|
|
3263
|
+
|
|
3264
|
+
These locations are searched during autodiscovery, or when you define HTML, JS, or CSS as
|
|
3265
|
+
a separate file.
|
|
3266
|
+
|
|
3267
|
+
Each app will be searched for these directories.
|
|
3268
|
+
|
|
3269
|
+
Set to empty list to disable app-level components:
|
|
3270
|
+
|
|
3271
|
+
```py
|
|
3272
|
+
COMPONENTS = {
|
|
3273
|
+
"app_dirs": [],
|
|
3274
|
+
}
|
|
3275
|
+
```
|
|
3276
|
+
|
|
3165
3277
|
### `dynamic_component_name`
|
|
3166
3278
|
|
|
3167
3279
|
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.
|
|
@@ -3182,6 +3294,60 @@ COMPONENTS = {
|
|
|
3182
3294
|
}
|
|
3183
3295
|
```
|
|
3184
3296
|
|
|
3297
|
+
### `static_files_allowed`
|
|
3298
|
+
|
|
3299
|
+
A list of regex patterns (as strings) that define which files within `COMPONENTS.dirs` and `COMPONENTS.app_dirs`
|
|
3300
|
+
are treated as static files.
|
|
3301
|
+
|
|
3302
|
+
If a file is matched against any of the patterns, it's considered a static file. Such files are collected
|
|
3303
|
+
when running `collectstatic`, and can be accessed under the static file endpoint.
|
|
3304
|
+
|
|
3305
|
+
You can also pass in compiled regexes (`re.Pattern`) for more advanced patterns.
|
|
3306
|
+
|
|
3307
|
+
By default, JS, CSS, and common image and font file formats are considered static files:
|
|
3308
|
+
|
|
3309
|
+
```python
|
|
3310
|
+
COMPONENTS = {
|
|
3311
|
+
"static_files_allowed": [
|
|
3312
|
+
"css",
|
|
3313
|
+
"js",
|
|
3314
|
+
# Images
|
|
3315
|
+
".apng", ".png",
|
|
3316
|
+
".avif",
|
|
3317
|
+
".gif",
|
|
3318
|
+
".jpg", ".jpeg", ".jfif", ".pjpeg", ".pjp", # JPEG
|
|
3319
|
+
".svg",
|
|
3320
|
+
".webp", ".bmp",
|
|
3321
|
+
".ico", ".cur", # ICO
|
|
3322
|
+
".tif", ".tiff",
|
|
3323
|
+
# Fonts
|
|
3324
|
+
".eot", ".ttf", ".woff", ".otf", ".svg",
|
|
3325
|
+
],
|
|
3326
|
+
}
|
|
3327
|
+
```
|
|
3328
|
+
|
|
3329
|
+
### `static_files_forbidden`
|
|
3330
|
+
|
|
3331
|
+
A list of suffixes that define which files within `COMPONENTS.dirs` and `COMPONENTS.app_dirs`
|
|
3332
|
+
will NEVER be treated as static files.
|
|
3333
|
+
|
|
3334
|
+
If a file is matched against any of the patterns, it will never be considered a static file, even if the file matches
|
|
3335
|
+
a pattern in [`COMPONENTS.static_files_allowed`](#static_files_allowed).
|
|
3336
|
+
|
|
3337
|
+
Use this setting together with `COMPONENTS.static_files_allowed` for a fine control over what files will be exposed.
|
|
3338
|
+
|
|
3339
|
+
You can also pass in compiled regexes (`re.Pattern`) for more advanced patterns.
|
|
3340
|
+
|
|
3341
|
+
By default, any HTML and Python are considered NOT static files:
|
|
3342
|
+
|
|
3343
|
+
```python
|
|
3344
|
+
COMPONENTS = {
|
|
3345
|
+
"static_files_forbidden": [
|
|
3346
|
+
".html", ".django", ".dj", ".tpl", ".py", ".pyc",
|
|
3347
|
+
],
|
|
3348
|
+
}
|
|
3349
|
+
```
|
|
3350
|
+
|
|
3185
3351
|
### `template_cache_size` - Tune the template cache
|
|
3186
3352
|
|
|
3187
3353
|
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.
|
|
@@ -3194,6 +3360,26 @@ COMPONENTS = {
|
|
|
3194
3360
|
}
|
|
3195
3361
|
```
|
|
3196
3362
|
|
|
3363
|
+
If you want add templates to the cache yourself, you can use `cached_template()`:
|
|
3364
|
+
|
|
3365
|
+
```py
|
|
3366
|
+
from django_components import cached_template
|
|
3367
|
+
|
|
3368
|
+
cached_template("Variable: {{ variable }}")
|
|
3369
|
+
|
|
3370
|
+
# You can optionally specify Template class, and other Template inputs:
|
|
3371
|
+
class MyTemplate(Template):
|
|
3372
|
+
pass
|
|
3373
|
+
|
|
3374
|
+
cached_template(
|
|
3375
|
+
"Variable: {{ variable }}",
|
|
3376
|
+
template_cls=MyTemplate,
|
|
3377
|
+
name=...
|
|
3378
|
+
origin=...
|
|
3379
|
+
engine=...
|
|
3380
|
+
)
|
|
3381
|
+
```
|
|
3382
|
+
|
|
3197
3383
|
### `context_behavior` - Make components isolated (or not)
|
|
3198
3384
|
|
|
3199
3385
|
> NOTE: `context_behavior` and `slot_context_behavior` options were merged in v0.70.
|
|
@@ -3590,7 +3776,7 @@ You can publish and share your components for others to use. Here are the steps
|
|
|
3590
3776
|
|
|
3591
3777
|
4. Import the components in `apps.py`
|
|
3592
3778
|
|
|
3593
|
-
Normally, users rely on [autodiscovery](#autodiscovery) and `
|
|
3779
|
+
Normally, users rely on [autodiscovery](#autodiscovery) and `COMPONENTS.dirs` to load the component files.
|
|
3594
3780
|
|
|
3595
3781
|
Since you, as the library author, are not in control of the file system, it is recommended to load the components manually.
|
|
3596
3782
|
|