django-components 0.83__tar.gz → 0.85__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.83/src/django_components.egg-info → django_components-0.85}/PKG-INFO +171 -42
- {django_components-0.83 → django_components-0.85}/README.md +170 -41
- {django_components-0.83 → django_components-0.85}/pyproject.toml +1 -1
- django_components-0.85/src/django_components/__init__.py +7 -0
- django_components-0.85/src/django_components/apps.py +17 -0
- django_components-0.85/src/django_components/autodiscover.py +115 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/component.py +10 -6
- {django_components-0.83 → django_components-0.85}/src/django_components/component_media.py +2 -2
- django_components-0.85/src/django_components/template_loader.py +61 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/template_parser.py +3 -1
- django_components-0.85/src/django_components/utils.py +21 -0
- {django_components-0.83 → django_components-0.85/src/django_components.egg-info}/PKG-INFO +171 -42
- {django_components-0.83 → django_components-0.85}/src/django_components.egg-info/SOURCES.txt +2 -0
- {django_components-0.83 → django_components-0.85}/tests/test_attributes.py +2 -3
- django_components-0.85/tests/test_autodiscover.py +164 -0
- {django_components-0.83 → django_components-0.85}/tests/test_command_startcomponent.py +10 -10
- {django_components-0.83 → django_components-0.85}/tests/test_component.py +9 -11
- {django_components-0.83 → django_components-0.85}/tests/test_component_as_view.py +4 -5
- {django_components-0.83 → django_components-0.85}/tests/test_component_media.py +11 -13
- {django_components-0.83 → django_components-0.85}/tests/test_context.py +29 -35
- {django_components-0.83 → django_components-0.85}/tests/test_dependency_rendering.py +3 -1
- {django_components-0.83 → django_components-0.85}/tests/test_registry.py +3 -1
- django_components-0.85/tests/test_settings.py +19 -0
- django_components-0.85/tests/test_template_loader.py +76 -0
- {django_components-0.83 → django_components-0.85}/tests/test_template_parser.py +34 -6
- {django_components-0.83 → django_components-0.85}/tests/test_templatetags.py +11 -16
- {django_components-0.83 → django_components-0.85}/tests/test_templatetags_component.py +10 -15
- {django_components-0.83 → django_components-0.85}/tests/test_templatetags_provide.py +4 -5
- {django_components-0.83 → django_components-0.85}/tests/test_templatetags_slot_fill.py +17 -23
- {django_components-0.83 → django_components-0.85}/tests/test_templatetags_templating.py +20 -27
- {django_components-0.83 → django_components-0.85}/tests/testutils.py +16 -12
- django_components-0.83/src/django_components/__init__.py +0 -76
- django_components-0.83/src/django_components/apps.py +0 -8
- django_components-0.83/src/django_components/template_loader.py +0 -95
- django_components-0.83/src/django_components/utils.py +0 -58
- django_components-0.83/tests/test_autodiscover.py +0 -186
- django_components-0.83/tests/test_settings.py +0 -35
- {django_components-0.83 → django_components-0.85}/LICENSE +0 -0
- {django_components-0.83 → django_components-0.85}/setup.cfg +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/app_settings.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/attributes.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/component_registry.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/context.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/expression.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/logger.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/management/__init__.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/middleware.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/node.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/provide.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/py.typed +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/slots.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/templatetags/component_tags.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components/types.py +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.83 → django_components-0.85}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.83 → django_components-0.85}/tests/test_safer_staticfiles.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: django_components
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.85
|
|
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
|
|
@@ -70,6 +70,14 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
70
70
|
|
|
71
71
|
## Release notes
|
|
72
72
|
|
|
73
|
+
🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
|
|
74
|
+
- Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
|
|
75
|
+
- To migrate from:
|
|
76
|
+
- `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
|
|
77
|
+
or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
|
|
78
|
+
- `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
|
|
79
|
+
- 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)).
|
|
80
|
+
|
|
73
81
|
🚨📢 **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.
|
|
74
82
|
|
|
75
83
|
- BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
|
|
@@ -159,51 +167,62 @@ For a step-by-step guide on deploying production server with static files,
|
|
|
159
167
|
|
|
160
168
|
## Installation
|
|
161
169
|
|
|
162
|
-
Install the app into your environment:
|
|
170
|
+
1. Install the app into your environment:
|
|
163
171
|
|
|
164
|
-
> `pip install django_components`
|
|
172
|
+
> `pip install django_components`
|
|
165
173
|
|
|
166
|
-
Then add the app into INSTALLED_APPS in settings.py
|
|
174
|
+
2. Then add the app into `INSTALLED_APPS` in settings.py
|
|
167
175
|
|
|
168
|
-
```python
|
|
169
|
-
INSTALLED_APPS = [
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
]
|
|
173
|
-
```
|
|
176
|
+
```python
|
|
177
|
+
INSTALLED_APPS = [
|
|
178
|
+
...,
|
|
179
|
+
'django_components',
|
|
180
|
+
]
|
|
181
|
+
```
|
|
174
182
|
|
|
175
|
-
|
|
176
|
-
- *Remove `'APP_DIRS': True,`*
|
|
177
|
-
- add `loaders` to `OPTIONS` list and set it to following value:
|
|
183
|
+
3. Ensure that `BASE_DIR` setting is defined in settings.py:
|
|
178
184
|
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
...,
|
|
183
|
-
'OPTIONS': {
|
|
184
|
-
'context_processors': [
|
|
185
|
-
...
|
|
186
|
-
],
|
|
187
|
-
'loaders':[(
|
|
188
|
-
'django.template.loaders.cached.Loader', [
|
|
189
|
-
'django.template.loaders.filesystem.Loader',
|
|
190
|
-
'django.template.loaders.app_directories.Loader',
|
|
191
|
-
'django_components.template_loader.Loader',
|
|
192
|
-
]
|
|
193
|
-
)],
|
|
194
|
-
},
|
|
195
|
-
},
|
|
196
|
-
]
|
|
197
|
-
```
|
|
185
|
+
```py
|
|
186
|
+
BASE_DIR = Path(__file__).resolve().parent.parent
|
|
187
|
+
```
|
|
198
188
|
|
|
199
|
-
Modify
|
|
189
|
+
4. Modify `TEMPLATES` section of settings.py as follows:
|
|
190
|
+
- *Remove `'APP_DIRS': True,`*
|
|
191
|
+
- Add `loaders` to `OPTIONS` list and set it to following value:
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
TEMPLATES = [
|
|
195
|
+
{
|
|
196
|
+
...,
|
|
197
|
+
'OPTIONS': {
|
|
198
|
+
'context_processors': [
|
|
199
|
+
...
|
|
200
|
+
],
|
|
201
|
+
'loaders':[(
|
|
202
|
+
'django.template.loaders.cached.Loader', [
|
|
203
|
+
'django.template.loaders.filesystem.Loader',
|
|
204
|
+
'django.template.loaders.app_directories.Loader',
|
|
205
|
+
'django_components.template_loader.Loader',
|
|
206
|
+
]
|
|
207
|
+
)],
|
|
208
|
+
},
|
|
209
|
+
},
|
|
210
|
+
]
|
|
211
|
+
```
|
|
200
212
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
213
|
+
5. Modify `STATICFILES_DIRS` (or add it if you don't have it) so django can find your static JS and CSS files:
|
|
214
|
+
|
|
215
|
+
```python
|
|
216
|
+
STATICFILES_DIRS = [
|
|
217
|
+
...,
|
|
218
|
+
os.path.join(BASE_DIR, "components"),
|
|
219
|
+
]
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
If `STATICFILES_DIRS` is omitted or empty, django-components will by default look for
|
|
223
|
+
`{BASE_DIR}/components`
|
|
224
|
+
|
|
225
|
+
NOTE: The paths in `STATICFILES_DIRS` must be full paths. [See Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#staticfiles-dirs).
|
|
207
226
|
|
|
208
227
|
### Optional
|
|
209
228
|
|
|
@@ -359,7 +378,49 @@ class Calendar(component.Component):
|
|
|
359
378
|
|
|
360
379
|
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
|
|
361
380
|
|
|
362
|
-
|
|
381
|
+
### Syntax highlight and code assistance
|
|
382
|
+
|
|
383
|
+
#### VSCode
|
|
384
|
+
|
|
385
|
+
Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
|
|
386
|
+
|
|
387
|
+
#### Pycharm (or other Jetbrains IDEs)
|
|
388
|
+
|
|
389
|
+
If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
|
|
390
|
+
|
|
391
|
+
```python
|
|
392
|
+
from django_components import component
|
|
393
|
+
|
|
394
|
+
@component.register("calendar")
|
|
395
|
+
class Calendar(component.Component):
|
|
396
|
+
def get_context_data(self, date):
|
|
397
|
+
return {
|
|
398
|
+
"date": date,
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
# language=HTML
|
|
402
|
+
template= """
|
|
403
|
+
<div class="calendar-component">Today's date is <span>{{ date }}</span></div>
|
|
404
|
+
"""
|
|
405
|
+
|
|
406
|
+
# language=CSS
|
|
407
|
+
css = """
|
|
408
|
+
.calendar-component { width: 200px; background: pink; }
|
|
409
|
+
.calendar-component span { font-weight: bold; }
|
|
410
|
+
"""
|
|
411
|
+
|
|
412
|
+
# language=JS
|
|
413
|
+
js = """
|
|
414
|
+
(function(){
|
|
415
|
+
if (document.querySelector(".calendar-component")) {
|
|
416
|
+
document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
|
|
417
|
+
}
|
|
418
|
+
})()
|
|
419
|
+
"""
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
You don't need to use `t.django_html`, `t.css`, `t.js` and `from django_components import types as t` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
|
|
423
|
+
You only need to write the comments `# language=<lang>` above the variables.
|
|
363
424
|
|
|
364
425
|
## Use components in templates
|
|
365
426
|
|
|
@@ -605,7 +666,37 @@ If you're planning on passing an HTML string, check Django's use of [`format_htm
|
|
|
605
666
|
|
|
606
667
|
## Autodiscovery
|
|
607
668
|
|
|
608
|
-
|
|
669
|
+
Every component that you want to use in the template with the `{% component %}` tag needs to be registered with the ComponentRegistry. Normally, we use the `@component.register` decorator for that:
|
|
670
|
+
|
|
671
|
+
```py
|
|
672
|
+
from django_components import component
|
|
673
|
+
|
|
674
|
+
@component.register("calendar")
|
|
675
|
+
class Calendar(component.Component):
|
|
676
|
+
...
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
But for the component to be registered, the code needs to be executed - the file needs to be imported as a module.
|
|
680
|
+
|
|
681
|
+
One way to do that is by importing all your components in `apps.py`:
|
|
682
|
+
|
|
683
|
+
```py
|
|
684
|
+
from django.apps import AppConfig
|
|
685
|
+
|
|
686
|
+
class MyAppConfig(AppConfig):
|
|
687
|
+
name = "my_app"
|
|
688
|
+
|
|
689
|
+
def ready(self) -> None:
|
|
690
|
+
from components.card.card import Card
|
|
691
|
+
from components.list.list import List
|
|
692
|
+
from components.menu.menu import Menu
|
|
693
|
+
from components.button.button import Button
|
|
694
|
+
...
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
However, there's a simpler way!
|
|
698
|
+
|
|
699
|
+
By default, the Python files in the `STATICFILES_DIRS` directories are auto-imported in order to auto-register the components.
|
|
609
700
|
|
|
610
701
|
Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
|
|
611
702
|
|
|
@@ -615,7 +706,17 @@ If you are using autodiscovery, keep a few points in mind:
|
|
|
615
706
|
- Components inside the auto-imported files still need to be registered with `@component.register()`
|
|
616
707
|
- Auto-imported component files must be valid Python modules, they must use suffix `.py`, and module name should follow [PEP-8](https://peps.python.org/pep-0008/#package-and-module-names).
|
|
617
708
|
|
|
618
|
-
Autodiscovery can be disabled
|
|
709
|
+
Autodiscovery can be disabled in the [settings](#disable-autodiscovery).
|
|
710
|
+
|
|
711
|
+
### Manually trigger autodiscovery
|
|
712
|
+
|
|
713
|
+
Autodiscovery can be also triggered manually as a function call. This is useful if you want to run autodiscovery at a custom point of the lifecycle:
|
|
714
|
+
|
|
715
|
+
```py
|
|
716
|
+
from django_components import autodiscover
|
|
717
|
+
|
|
718
|
+
autodiscover()
|
|
719
|
+
```
|
|
619
720
|
|
|
620
721
|
## Using slots in templates
|
|
621
722
|
|
|
@@ -1941,6 +2042,34 @@ COMPONENTS = {
|
|
|
1941
2042
|
}
|
|
1942
2043
|
```
|
|
1943
2044
|
|
|
2045
|
+
Where `mysite/components/forms.py` may look like this:
|
|
2046
|
+
|
|
2047
|
+
```py
|
|
2048
|
+
@component.register("form_simple")
|
|
2049
|
+
class FormSimple(component.Component):
|
|
2050
|
+
template = """
|
|
2051
|
+
<form>
|
|
2052
|
+
...
|
|
2053
|
+
</form>
|
|
2054
|
+
"""
|
|
2055
|
+
|
|
2056
|
+
@component.register("form_other")
|
|
2057
|
+
class FormOther(component.Component):
|
|
2058
|
+
template = """
|
|
2059
|
+
<form>
|
|
2060
|
+
...
|
|
2061
|
+
</form>
|
|
2062
|
+
"""
|
|
2063
|
+
```
|
|
2064
|
+
|
|
2065
|
+
In the rare cases when you need to manually trigger the import of libraries, you can use the `import_libraries` function:
|
|
2066
|
+
|
|
2067
|
+
```py
|
|
2068
|
+
from django_components import import_libraries
|
|
2069
|
+
|
|
2070
|
+
import_libraries()
|
|
2071
|
+
```
|
|
2072
|
+
|
|
1944
2073
|
### Disable autodiscovery
|
|
1945
2074
|
|
|
1946
2075
|
If you specify all the component locations with the setting above and have a lot of apps, you can (very) slightly speed things up by disabling autodiscovery.
|
|
@@ -46,6 +46,14 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
46
46
|
|
|
47
47
|
## Release notes
|
|
48
48
|
|
|
49
|
+
🚨📢 **Version 0.85** Autodiscovery module resolution changed. Following undocumented behavior was removed:
|
|
50
|
+
- Previously, autodiscovery also imported any `[app]/components.py` files, and used `SETTINGS_MODULE` to search for component dirs.
|
|
51
|
+
- To migrate from:
|
|
52
|
+
- `[app]/components.py` - Define each module in `COMPONENTS.libraries` setting,
|
|
53
|
+
or import each module inside the `AppConfig.ready()` hook in respective `apps.py` files.
|
|
54
|
+
- `SETTINGS_MODULE` - Define component dirs using `STATICFILES_DIRS`
|
|
55
|
+
- 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)).
|
|
56
|
+
|
|
49
57
|
🚨📢 **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.
|
|
50
58
|
|
|
51
59
|
- BREAKING CHANGE: The order of arguments to `render_to_response` has changed.
|
|
@@ -135,51 +143,62 @@ For a step-by-step guide on deploying production server with static files,
|
|
|
135
143
|
|
|
136
144
|
## Installation
|
|
137
145
|
|
|
138
|
-
Install the app into your environment:
|
|
146
|
+
1. Install the app into your environment:
|
|
139
147
|
|
|
140
|
-
> `pip install django_components`
|
|
148
|
+
> `pip install django_components`
|
|
141
149
|
|
|
142
|
-
Then add the app into INSTALLED_APPS in settings.py
|
|
150
|
+
2. Then add the app into `INSTALLED_APPS` in settings.py
|
|
143
151
|
|
|
144
|
-
```python
|
|
145
|
-
INSTALLED_APPS = [
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
]
|
|
149
|
-
```
|
|
152
|
+
```python
|
|
153
|
+
INSTALLED_APPS = [
|
|
154
|
+
...,
|
|
155
|
+
'django_components',
|
|
156
|
+
]
|
|
157
|
+
```
|
|
150
158
|
|
|
151
|
-
|
|
152
|
-
- *Remove `'APP_DIRS': True,`*
|
|
153
|
-
- add `loaders` to `OPTIONS` list and set it to following value:
|
|
159
|
+
3. Ensure that `BASE_DIR` setting is defined in settings.py:
|
|
154
160
|
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
...,
|
|
159
|
-
'OPTIONS': {
|
|
160
|
-
'context_processors': [
|
|
161
|
-
...
|
|
162
|
-
],
|
|
163
|
-
'loaders':[(
|
|
164
|
-
'django.template.loaders.cached.Loader', [
|
|
165
|
-
'django.template.loaders.filesystem.Loader',
|
|
166
|
-
'django.template.loaders.app_directories.Loader',
|
|
167
|
-
'django_components.template_loader.Loader',
|
|
168
|
-
]
|
|
169
|
-
)],
|
|
170
|
-
},
|
|
171
|
-
},
|
|
172
|
-
]
|
|
173
|
-
```
|
|
161
|
+
```py
|
|
162
|
+
BASE_DIR = Path(__file__).resolve().parent.parent
|
|
163
|
+
```
|
|
174
164
|
|
|
175
|
-
Modify
|
|
165
|
+
4. Modify `TEMPLATES` section of settings.py as follows:
|
|
166
|
+
- *Remove `'APP_DIRS': True,`*
|
|
167
|
+
- Add `loaders` to `OPTIONS` list and set it to following value:
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
TEMPLATES = [
|
|
171
|
+
{
|
|
172
|
+
...,
|
|
173
|
+
'OPTIONS': {
|
|
174
|
+
'context_processors': [
|
|
175
|
+
...
|
|
176
|
+
],
|
|
177
|
+
'loaders':[(
|
|
178
|
+
'django.template.loaders.cached.Loader', [
|
|
179
|
+
'django.template.loaders.filesystem.Loader',
|
|
180
|
+
'django.template.loaders.app_directories.Loader',
|
|
181
|
+
'django_components.template_loader.Loader',
|
|
182
|
+
]
|
|
183
|
+
)],
|
|
184
|
+
},
|
|
185
|
+
},
|
|
186
|
+
]
|
|
187
|
+
```
|
|
176
188
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
189
|
+
5. Modify `STATICFILES_DIRS` (or add it if you don't have it) so django can find your static JS and CSS files:
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
STATICFILES_DIRS = [
|
|
193
|
+
...,
|
|
194
|
+
os.path.join(BASE_DIR, "components"),
|
|
195
|
+
]
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
If `STATICFILES_DIRS` is omitted or empty, django-components will by default look for
|
|
199
|
+
`{BASE_DIR}/components`
|
|
200
|
+
|
|
201
|
+
NOTE: The paths in `STATICFILES_DIRS` must be full paths. [See Django docs](https://docs.djangoproject.com/en/5.0/ref/settings/#staticfiles-dirs).
|
|
183
202
|
|
|
184
203
|
### Optional
|
|
185
204
|
|
|
@@ -335,7 +354,49 @@ class Calendar(component.Component):
|
|
|
335
354
|
|
|
336
355
|
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
|
|
337
356
|
|
|
338
|
-
|
|
357
|
+
### Syntax highlight and code assistance
|
|
358
|
+
|
|
359
|
+
#### VSCode
|
|
360
|
+
|
|
361
|
+
Note, in the above example, that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
|
|
362
|
+
|
|
363
|
+
#### Pycharm (or other Jetbrains IDEs)
|
|
364
|
+
|
|
365
|
+
If you're a Pycharm user (or any other editor from Jetbrains), you can have coding assistance as well:
|
|
366
|
+
|
|
367
|
+
```python
|
|
368
|
+
from django_components import component
|
|
369
|
+
|
|
370
|
+
@component.register("calendar")
|
|
371
|
+
class Calendar(component.Component):
|
|
372
|
+
def get_context_data(self, date):
|
|
373
|
+
return {
|
|
374
|
+
"date": date,
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
# language=HTML
|
|
378
|
+
template= """
|
|
379
|
+
<div class="calendar-component">Today's date is <span>{{ date }}</span></div>
|
|
380
|
+
"""
|
|
381
|
+
|
|
382
|
+
# language=CSS
|
|
383
|
+
css = """
|
|
384
|
+
.calendar-component { width: 200px; background: pink; }
|
|
385
|
+
.calendar-component span { font-weight: bold; }
|
|
386
|
+
"""
|
|
387
|
+
|
|
388
|
+
# language=JS
|
|
389
|
+
js = """
|
|
390
|
+
(function(){
|
|
391
|
+
if (document.querySelector(".calendar-component")) {
|
|
392
|
+
document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
|
|
393
|
+
}
|
|
394
|
+
})()
|
|
395
|
+
"""
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
You don't need to use `t.django_html`, `t.css`, `t.js` and `from django_components import types as t` since Pycharm uses [language injections](https://www.jetbrains.com/help/pycharm/using-language-injections.html).
|
|
399
|
+
You only need to write the comments `# language=<lang>` above the variables.
|
|
339
400
|
|
|
340
401
|
## Use components in templates
|
|
341
402
|
|
|
@@ -581,7 +642,37 @@ If you're planning on passing an HTML string, check Django's use of [`format_htm
|
|
|
581
642
|
|
|
582
643
|
## Autodiscovery
|
|
583
644
|
|
|
584
|
-
|
|
645
|
+
Every component that you want to use in the template with the `{% component %}` tag needs to be registered with the ComponentRegistry. Normally, we use the `@component.register` decorator for that:
|
|
646
|
+
|
|
647
|
+
```py
|
|
648
|
+
from django_components import component
|
|
649
|
+
|
|
650
|
+
@component.register("calendar")
|
|
651
|
+
class Calendar(component.Component):
|
|
652
|
+
...
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
But for the component to be registered, the code needs to be executed - the file needs to be imported as a module.
|
|
656
|
+
|
|
657
|
+
One way to do that is by importing all your components in `apps.py`:
|
|
658
|
+
|
|
659
|
+
```py
|
|
660
|
+
from django.apps import AppConfig
|
|
661
|
+
|
|
662
|
+
class MyAppConfig(AppConfig):
|
|
663
|
+
name = "my_app"
|
|
664
|
+
|
|
665
|
+
def ready(self) -> None:
|
|
666
|
+
from components.card.card import Card
|
|
667
|
+
from components.list.list import List
|
|
668
|
+
from components.menu.menu import Menu
|
|
669
|
+
from components.button.button import Button
|
|
670
|
+
...
|
|
671
|
+
```
|
|
672
|
+
|
|
673
|
+
However, there's a simpler way!
|
|
674
|
+
|
|
675
|
+
By default, the Python files in the `STATICFILES_DIRS` directories are auto-imported in order to auto-register the components.
|
|
585
676
|
|
|
586
677
|
Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
|
|
587
678
|
|
|
@@ -591,7 +682,17 @@ If you are using autodiscovery, keep a few points in mind:
|
|
|
591
682
|
- Components inside the auto-imported files still need to be registered with `@component.register()`
|
|
592
683
|
- Auto-imported component files must be valid Python modules, they must use suffix `.py`, and module name should follow [PEP-8](https://peps.python.org/pep-0008/#package-and-module-names).
|
|
593
684
|
|
|
594
|
-
Autodiscovery can be disabled
|
|
685
|
+
Autodiscovery can be disabled in the [settings](#disable-autodiscovery).
|
|
686
|
+
|
|
687
|
+
### Manually trigger autodiscovery
|
|
688
|
+
|
|
689
|
+
Autodiscovery can be also triggered manually as a function call. This is useful if you want to run autodiscovery at a custom point of the lifecycle:
|
|
690
|
+
|
|
691
|
+
```py
|
|
692
|
+
from django_components import autodiscover
|
|
693
|
+
|
|
694
|
+
autodiscover()
|
|
695
|
+
```
|
|
595
696
|
|
|
596
697
|
## Using slots in templates
|
|
597
698
|
|
|
@@ -1917,6 +2018,34 @@ COMPONENTS = {
|
|
|
1917
2018
|
}
|
|
1918
2019
|
```
|
|
1919
2020
|
|
|
2021
|
+
Where `mysite/components/forms.py` may look like this:
|
|
2022
|
+
|
|
2023
|
+
```py
|
|
2024
|
+
@component.register("form_simple")
|
|
2025
|
+
class FormSimple(component.Component):
|
|
2026
|
+
template = """
|
|
2027
|
+
<form>
|
|
2028
|
+
...
|
|
2029
|
+
</form>
|
|
2030
|
+
"""
|
|
2031
|
+
|
|
2032
|
+
@component.register("form_other")
|
|
2033
|
+
class FormOther(component.Component):
|
|
2034
|
+
template = """
|
|
2035
|
+
<form>
|
|
2036
|
+
...
|
|
2037
|
+
</form>
|
|
2038
|
+
"""
|
|
2039
|
+
```
|
|
2040
|
+
|
|
2041
|
+
In the rare cases when you need to manually trigger the import of libraries, you can use the `import_libraries` function:
|
|
2042
|
+
|
|
2043
|
+
```py
|
|
2044
|
+
from django_components import import_libraries
|
|
2045
|
+
|
|
2046
|
+
import_libraries()
|
|
2047
|
+
```
|
|
2048
|
+
|
|
1920
2049
|
### Disable autodiscovery
|
|
1921
2050
|
|
|
1922
2051
|
If you specify all the component locations with the setting above and have a lot of apps, you can (very) slightly speed things up by disabling autodiscovery.
|
|
@@ -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.85"
|
|
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"]
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import django
|
|
2
|
+
|
|
3
|
+
from django_components.autodiscover import autodiscover as autodiscover # NOQA
|
|
4
|
+
from django_components.autodiscover import import_libraries as import_libraries # NOQA
|
|
5
|
+
|
|
6
|
+
if django.VERSION < (3, 2):
|
|
7
|
+
default_app_config = "django_components.apps.ComponentsConfig"
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
from django.apps import AppConfig
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class ComponentsConfig(AppConfig):
|
|
5
|
+
name = "django_components"
|
|
6
|
+
|
|
7
|
+
# This is the code that gets run when user adds django_components
|
|
8
|
+
# to Django's INSTALLED_APPS
|
|
9
|
+
def ready(self) -> None:
|
|
10
|
+
from django_components.app_settings import app_settings
|
|
11
|
+
from django_components.autodiscover import autodiscover, import_libraries
|
|
12
|
+
|
|
13
|
+
# Import modules set in `COMPONENTS.libraries` setting
|
|
14
|
+
import_libraries()
|
|
15
|
+
|
|
16
|
+
if app_settings.AUTODISCOVER:
|
|
17
|
+
autodiscover()
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
import glob
|
|
2
|
+
import importlib
|
|
3
|
+
import os
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Callable, List, Optional, Union
|
|
6
|
+
|
|
7
|
+
from django.conf import settings
|
|
8
|
+
from django.template.engine import Engine
|
|
9
|
+
|
|
10
|
+
from django_components.logger import logger
|
|
11
|
+
from django_components.template_loader import Loader
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def autodiscover(
|
|
15
|
+
map_module: Optional[Callable[[str], str]] = None,
|
|
16
|
+
) -> List[str]:
|
|
17
|
+
"""
|
|
18
|
+
Search for component files and import them. Returns a list of module
|
|
19
|
+
paths of imported files.
|
|
20
|
+
|
|
21
|
+
Autodiscover searches in the locations as defined by `Loader.get_dirs`.
|
|
22
|
+
|
|
23
|
+
You can map the module paths with `map_module` function. This serves
|
|
24
|
+
as an escape hatch for when you need to use this function in tests.
|
|
25
|
+
"""
|
|
26
|
+
dirs = get_dirs()
|
|
27
|
+
component_filepaths = search_dirs(dirs, "**/*.py")
|
|
28
|
+
logger.debug(f"Autodiscover found {len(component_filepaths)} files in component directories.")
|
|
29
|
+
|
|
30
|
+
modules = [_filepath_to_python_module(filepath) for filepath in component_filepaths]
|
|
31
|
+
return _import_modules(modules, map_module)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def import_libraries(
|
|
35
|
+
map_module: Optional[Callable[[str], str]] = None,
|
|
36
|
+
) -> List[str]:
|
|
37
|
+
"""
|
|
38
|
+
Import modules set in `COMPONENTS.libraries` setting.
|
|
39
|
+
|
|
40
|
+
You can map the module paths with `map_module` function. This serves
|
|
41
|
+
as an escape hatch for when you need to use this function in tests.
|
|
42
|
+
"""
|
|
43
|
+
from django_components.app_settings import app_settings
|
|
44
|
+
|
|
45
|
+
return _import_modules(app_settings.LIBRARIES, map_module)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _import_modules(
|
|
49
|
+
modules: List[str],
|
|
50
|
+
map_module: Optional[Callable[[str], str]] = None,
|
|
51
|
+
) -> List[str]:
|
|
52
|
+
imported_modules: List[str] = []
|
|
53
|
+
for module_name in modules:
|
|
54
|
+
if map_module:
|
|
55
|
+
module_name = map_module(module_name)
|
|
56
|
+
|
|
57
|
+
# This imports the file and runs it's code. So if the file defines any
|
|
58
|
+
# django components, they will be registered.
|
|
59
|
+
logger.debug(f'Importing module "{module_name}"')
|
|
60
|
+
importlib.import_module(module_name)
|
|
61
|
+
imported_modules.append(module_name)
|
|
62
|
+
return imported_modules
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _filepath_to_python_module(file_path: Union[Path, str]) -> str:
|
|
66
|
+
"""
|
|
67
|
+
Derive python import path from the filesystem path.
|
|
68
|
+
|
|
69
|
+
Example:
|
|
70
|
+
- If project root is `/path/to/project`
|
|
71
|
+
- And file_path is `/path/to/project/app/components/mycomp.py`
|
|
72
|
+
- Then the path relative to project root is `app/components/mycomp.py`
|
|
73
|
+
- Which we then turn into python import path `app.components.mycomp`
|
|
74
|
+
"""
|
|
75
|
+
if hasattr(settings, "BASE_DIR") and settings.BASE_DIR:
|
|
76
|
+
project_root = str(settings.BASE_DIR)
|
|
77
|
+
else:
|
|
78
|
+
# Fallback for getting the root dir, see https://stackoverflow.com/a/16413955/9788634
|
|
79
|
+
project_root = os.path.abspath(os.path.dirname(__name__))
|
|
80
|
+
|
|
81
|
+
rel_path = os.path.relpath(file_path, start=project_root)
|
|
82
|
+
rel_path_without_suffix = str(Path(rel_path).with_suffix(""))
|
|
83
|
+
|
|
84
|
+
# NOTE: `Path` normalizes paths to use `/` as separator, while `os.path`
|
|
85
|
+
# uses `os.path.sep`.
|
|
86
|
+
sep = os.path.sep if os.path.sep in rel_path_without_suffix else "/"
|
|
87
|
+
module_name = rel_path_without_suffix.replace(sep, ".")
|
|
88
|
+
|
|
89
|
+
return module_name
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def get_dirs(engine: Optional[Engine] = None) -> List[Path]:
|
|
93
|
+
"""
|
|
94
|
+
Helper for using django_component's FilesystemLoader class to obtain a list
|
|
95
|
+
of directories where component python files may be defined.
|
|
96
|
+
"""
|
|
97
|
+
current_engine = engine
|
|
98
|
+
if current_engine is None:
|
|
99
|
+
current_engine = Engine.get_default()
|
|
100
|
+
|
|
101
|
+
loader = Loader(current_engine)
|
|
102
|
+
return loader.get_dirs()
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def search_dirs(dirs: List[Path], search_glob: str) -> List[Path]:
|
|
106
|
+
"""
|
|
107
|
+
Search the directories for the given glob pattern. Glob search results are returned
|
|
108
|
+
as a flattened list.
|
|
109
|
+
"""
|
|
110
|
+
matched_files: List[Path] = []
|
|
111
|
+
for directory in dirs:
|
|
112
|
+
for path in glob.iglob(str(Path(directory) / search_glob), recursive=True):
|
|
113
|
+
matched_files.append(Path(path))
|
|
114
|
+
|
|
115
|
+
return matched_files
|