django-components 0.84__tar.gz → 0.86__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. {django_components-0.84/src/django_components.egg-info → django_components-0.86}/PKG-INFO +172 -43
  2. {django_components-0.84 → django_components-0.86}/README.md +171 -42
  3. {django_components-0.84 → django_components-0.86}/pyproject.toml +1 -1
  4. django_components-0.86/src/django_components/__init__.py +7 -0
  5. django_components-0.86/src/django_components/apps.py +17 -0
  6. django_components-0.86/src/django_components/autodiscover.py +115 -0
  7. {django_components-0.84 → django_components-0.86}/src/django_components/component_media.py +2 -2
  8. django_components-0.86/src/django_components/management/commands/upgradecomponent.py +69 -0
  9. django_components-0.86/src/django_components/template_loader.py +61 -0
  10. {django_components-0.84 → django_components-0.86}/src/django_components/template_parser.py +3 -1
  11. django_components-0.86/src/django_components/utils.py +21 -0
  12. {django_components-0.84 → django_components-0.86/src/django_components.egg-info}/PKG-INFO +172 -43
  13. {django_components-0.84 → django_components-0.86}/src/django_components.egg-info/SOURCES.txt +2 -0
  14. {django_components-0.84 → django_components-0.86}/tests/test_attributes.py +2 -3
  15. django_components-0.86/tests/test_autodiscover.py +164 -0
  16. {django_components-0.84 → django_components-0.86}/tests/test_command_startcomponent.py +10 -10
  17. {django_components-0.84 → django_components-0.86}/tests/test_component.py +9 -11
  18. {django_components-0.84 → django_components-0.86}/tests/test_component_as_view.py +4 -5
  19. {django_components-0.84 → django_components-0.86}/tests/test_component_media.py +11 -13
  20. {django_components-0.84 → django_components-0.86}/tests/test_context.py +29 -35
  21. {django_components-0.84 → django_components-0.86}/tests/test_dependency_rendering.py +3 -1
  22. {django_components-0.84 → django_components-0.86}/tests/test_registry.py +3 -1
  23. django_components-0.86/tests/test_settings.py +19 -0
  24. django_components-0.86/tests/test_template_loader.py +76 -0
  25. {django_components-0.84 → django_components-0.86}/tests/test_template_parser.py +34 -6
  26. {django_components-0.84 → django_components-0.86}/tests/test_templatetags.py +11 -16
  27. {django_components-0.84 → django_components-0.86}/tests/test_templatetags_component.py +10 -15
  28. {django_components-0.84 → django_components-0.86}/tests/test_templatetags_provide.py +4 -5
  29. {django_components-0.84 → django_components-0.86}/tests/test_templatetags_slot_fill.py +17 -23
  30. {django_components-0.84 → django_components-0.86}/tests/test_templatetags_templating.py +20 -27
  31. {django_components-0.84 → django_components-0.86}/tests/testutils.py +16 -12
  32. django_components-0.84/src/django_components/__init__.py +0 -76
  33. django_components-0.84/src/django_components/apps.py +0 -8
  34. django_components-0.84/src/django_components/management/commands/upgradecomponent.py +0 -66
  35. django_components-0.84/src/django_components/template_loader.py +0 -95
  36. django_components-0.84/src/django_components/utils.py +0 -58
  37. django_components-0.84/tests/test_autodiscover.py +0 -186
  38. django_components-0.84/tests/test_settings.py +0 -35
  39. {django_components-0.84 → django_components-0.86}/LICENSE +0 -0
  40. {django_components-0.84 → django_components-0.86}/setup.cfg +0 -0
  41. {django_components-0.84 → django_components-0.86}/src/django_components/app_settings.py +0 -0
  42. {django_components-0.84 → django_components-0.86}/src/django_components/attributes.py +0 -0
  43. {django_components-0.84 → django_components-0.86}/src/django_components/component.py +0 -0
  44. {django_components-0.84 → django_components-0.86}/src/django_components/component_registry.py +0 -0
  45. {django_components-0.84 → django_components-0.86}/src/django_components/context.py +0 -0
  46. {django_components-0.84 → django_components-0.86}/src/django_components/expression.py +0 -0
  47. {django_components-0.84 → django_components-0.86}/src/django_components/logger.py +0 -0
  48. {django_components-0.84 → django_components-0.86}/src/django_components/management/__init__.py +0 -0
  49. {django_components-0.84 → django_components-0.86}/src/django_components/management/commands/__init__.py +0 -0
  50. {django_components-0.84 → django_components-0.86}/src/django_components/management/commands/startcomponent.py +0 -0
  51. {django_components-0.84 → django_components-0.86}/src/django_components/middleware.py +0 -0
  52. {django_components-0.84 → django_components-0.86}/src/django_components/node.py +0 -0
  53. {django_components-0.84 → django_components-0.86}/src/django_components/provide.py +0 -0
  54. {django_components-0.84 → django_components-0.86}/src/django_components/py.typed +0 -0
  55. {django_components-0.84 → django_components-0.86}/src/django_components/safer_staticfiles/__init__.py +0 -0
  56. {django_components-0.84 → django_components-0.86}/src/django_components/safer_staticfiles/apps.py +0 -0
  57. {django_components-0.84 → django_components-0.86}/src/django_components/slots.py +0 -0
  58. {django_components-0.84 → django_components-0.86}/src/django_components/templatetags/__init__.py +0 -0
  59. {django_components-0.84 → django_components-0.86}/src/django_components/templatetags/component_tags.py +0 -0
  60. {django_components-0.84 → django_components-0.86}/src/django_components/types.py +0 -0
  61. {django_components-0.84 → django_components-0.86}/src/django_components.egg-info/dependency_links.txt +0 -0
  62. {django_components-0.84 → django_components-0.86}/src/django_components.egg-info/requires.txt +0 -0
  63. {django_components-0.84 → django_components-0.86}/src/django_components.egg-info/top_level.txt +0 -0
  64. {django_components-0.84 → django_components-0.86}/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.84
3
+ Version: 0.86
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.
@@ -96,7 +104,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
96
104
 
97
105
  **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.
98
106
 
99
- 🚨📢 **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 components to the new syntax automatically.
107
+ 🚨📢 **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.
100
108
 
101
109
  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.
102
110
 
@@ -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
- 'django_components',
172
- ]
173
- ```
176
+ ```python
177
+ INSTALLED_APPS = [
178
+ ...,
179
+ 'django_components',
180
+ ]
181
+ ```
174
182
 
175
- Modify `TEMPLATES` section of settings.py as follows:
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
- ```python
180
- TEMPLATES = [
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 STATICFILES_DIRS (or add it if you don't have it) so django can find your static JS and CSS files:
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
- ```python
202
- STATICFILES_DIRS = [
203
- ...,
204
- os.path.join(BASE_DIR, "components"),
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
- Note 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.
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
- By default, the Python files in the `components` app are auto-imported in order to auto-register the components (e.g. `components/button/button.py`).
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 via in the [settings](#disable-autodiscovery).
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.
@@ -72,7 +80,7 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
72
80
 
73
81
  **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.
74
82
 
75
- 🚨📢 **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 components to the new syntax automatically.
83
+ 🚨📢 **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.
76
84
 
77
85
  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.
78
86
 
@@ -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
- 'django_components',
148
- ]
149
- ```
152
+ ```python
153
+ INSTALLED_APPS = [
154
+ ...,
155
+ 'django_components',
156
+ ]
157
+ ```
150
158
 
151
- Modify `TEMPLATES` section of settings.py as follows:
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
- ```python
156
- TEMPLATES = [
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 STATICFILES_DIRS (or add it if you don't have it) so django can find your static JS and CSS files:
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
- ```python
178
- STATICFILES_DIRS = [
179
- ...,
180
- os.path.join(BASE_DIR, "components"),
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
- Note 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.
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
- By default, the Python files in the `components` app are auto-imported in order to auto-register the components (e.g. `components/button/button.py`).
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 via in the [settings](#disable-autodiscovery).
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.84"
7
+ version = "0.86"
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()