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.
Files changed (70) hide show
  1. {django_components-0.96/src/django_components.egg-info → django_components-0.100}/PKG-INFO +251 -65
  2. {django_components-0.96 → django_components-0.100}/README.md +250 -64
  3. {django_components-0.96 → django_components-0.100}/pyproject.toml +1 -1
  4. {django_components-0.96 → django_components-0.100}/src/django_components/__init__.py +1 -0
  5. {django_components-0.96 → django_components-0.100}/src/django_components/app_settings.py +55 -1
  6. {django_components-0.96 → django_components-0.100}/src/django_components/autodiscover.py +8 -16
  7. {django_components-0.96 → django_components-0.100}/src/django_components/component.py +86 -20
  8. {django_components-0.96 → django_components-0.100}/src/django_components/component_media.py +3 -3
  9. django_components-0.100/src/django_components/finders.py +154 -0
  10. {django_components-0.96 → django_components-0.100}/src/django_components/slots.py +19 -13
  11. django_components-0.100/src/django_components/template.py +42 -0
  12. django_components-0.100/src/django_components/template_loader.py +111 -0
  13. {django_components-0.96 → django_components-0.100}/src/django_components/templatetags/component_tags.py +1 -1
  14. {django_components-0.96 → django_components-0.100}/src/django_components/utils.py +55 -1
  15. {django_components-0.96 → django_components-0.100/src/django_components.egg-info}/PKG-INFO +251 -65
  16. {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/SOURCES.txt +4 -3
  17. {django_components-0.96 → django_components-0.100}/tests/test_component.py +32 -5
  18. {django_components-0.96 → django_components-0.100}/tests/test_component_as_view.py +22 -0
  19. {django_components-0.96 → django_components-0.100}/tests/test_component_media.py +4 -6
  20. django_components-0.100/tests/test_finders.py +210 -0
  21. {django_components-0.96 → django_components-0.100}/tests/test_registry.py +6 -2
  22. django_components-0.100/tests/test_template.py +67 -0
  23. django_components-0.100/tests/test_template_loader.py +181 -0
  24. {django_components-0.96 → django_components-0.100}/tests/test_templatetags_slot_fill.py +1 -1
  25. {django_components-0.96 → django_components-0.100}/tests/testutils.py +4 -0
  26. django_components-0.96/src/django_components/safer_staticfiles/apps.py +0 -22
  27. django_components-0.96/src/django_components/template_loader.py +0 -61
  28. django_components-0.96/src/django_components/templatetags/__init__.py +0 -0
  29. django_components-0.96/tests/test_safer_staticfiles.py +0 -103
  30. django_components-0.96/tests/test_template_loader.py +0 -76
  31. {django_components-0.96 → django_components-0.100}/LICENSE +0 -0
  32. {django_components-0.96 → django_components-0.100}/setup.cfg +0 -0
  33. {django_components-0.96 → django_components-0.100}/src/django_components/apps.py +0 -0
  34. {django_components-0.96 → django_components-0.100}/src/django_components/attributes.py +0 -0
  35. {django_components-0.96 → django_components-0.100}/src/django_components/component_registry.py +0 -0
  36. {django_components-0.96 → django_components-0.100}/src/django_components/components/__init__.py +0 -0
  37. {django_components-0.96 → django_components-0.100}/src/django_components/components/dynamic.py +0 -0
  38. {django_components-0.96 → django_components-0.100}/src/django_components/context.py +0 -0
  39. {django_components-0.96 → django_components-0.100}/src/django_components/expression.py +0 -0
  40. {django_components-0.96 → django_components-0.100}/src/django_components/library.py +0 -0
  41. {django_components-0.96 → django_components-0.100}/src/django_components/logger.py +0 -0
  42. {django_components-0.96 → django_components-0.100}/src/django_components/management/__init__.py +0 -0
  43. {django_components-0.96 → django_components-0.100}/src/django_components/management/commands/__init__.py +0 -0
  44. {django_components-0.96 → django_components-0.100}/src/django_components/management/commands/startcomponent.py +0 -0
  45. {django_components-0.96 → django_components-0.100}/src/django_components/management/commands/upgradecomponent.py +0 -0
  46. {django_components-0.96 → django_components-0.100}/src/django_components/middleware.py +0 -0
  47. {django_components-0.96 → django_components-0.100}/src/django_components/node.py +0 -0
  48. {django_components-0.96 → django_components-0.100}/src/django_components/provide.py +0 -0
  49. {django_components-0.96 → django_components-0.100}/src/django_components/py.typed +0 -0
  50. {django_components-0.96 → django_components-0.100}/src/django_components/tag_formatter.py +0 -0
  51. {django_components-0.96 → django_components-0.100}/src/django_components/template_parser.py +0 -0
  52. {django_components-0.96/src/django_components/safer_staticfiles → django_components-0.100/src/django_components/templatetags}/__init__.py +0 -0
  53. {django_components-0.96 → django_components-0.100}/src/django_components/types.py +0 -0
  54. {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/dependency_links.txt +0 -0
  55. {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/requires.txt +0 -0
  56. {django_components-0.96 → django_components-0.100}/src/django_components.egg-info/top_level.txt +0 -0
  57. {django_components-0.96 → django_components-0.100}/tests/test_attributes.py +0 -0
  58. {django_components-0.96 → django_components-0.100}/tests/test_autodiscover.py +0 -0
  59. {django_components-0.96 → django_components-0.100}/tests/test_command_startcomponent.py +0 -0
  60. {django_components-0.96 → django_components-0.100}/tests/test_context.py +0 -0
  61. {django_components-0.96 → django_components-0.100}/tests/test_dependency_rendering.py +0 -0
  62. {django_components-0.96 → django_components-0.100}/tests/test_expression.py +0 -0
  63. {django_components-0.96 → django_components-0.100}/tests/test_settings.py +0 -0
  64. {django_components-0.96 → django_components-0.100}/tests/test_tag_formatter.py +0 -0
  65. {django_components-0.96 → django_components-0.100}/tests/test_template_parser.py +0 -0
  66. {django_components-0.96 → django_components-0.100}/tests/test_templatetags.py +0 -0
  67. {django_components-0.96 → django_components-0.100}/tests/test_templatetags_component.py +0 -0
  68. {django_components-0.96 → django_components-0.100}/tests/test_templatetags_provide.py +0 -0
  69. {django_components-0.96 → django_components-0.100}/tests/test_templatetags_templating.py +0 -0
  70. {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.96
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
- Create simple reusable template components in Django
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
- <!-- FIXME Links -->
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
- - ✨ **Reusable components**: Create components that can be reused in different parts of your project, or even in different projects.
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](./sampleproject) or read on to learn about the details!
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`, `get_template_string` and `get_template_name` via `self.input`. (See [Accessing data passed to the component](#accessing-data-passed-to-the-component))
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
- If your are using _django.contrib.staticfiles_ to collect static files, no distinction is made between the different kinds of files.
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
- As of _v0.27_, django-components ships with an additional installable app _django_components.**safer_staticfiles**_.
218
- It is a drop-in replacement for _django.contrib.staticfiles_.
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](./sampleproject/README.md).
280
+ [see the demo project](https://github.com/EmilStenstrom/django-components/tree/master/sampleproject).
247
281
 
248
282
  ## Installation
249
283
 
250
- 1. Install the app into your environment:
284
+ 1. Install `django_components` into your environment:
251
285
 
252
286
  > `pip install django_components`
253
287
 
254
- 2. Then add the app into `INSTALLED_APPS` in settings.py
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. Ensure that `BASE_DIR` setting is defined in settings.py:
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. Modify `TEMPLATES` section of settings.py as follows:
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
- 5. Modify `STATICFILES_DIRS` (or add it if you don't have it) so django can find your static JS and CSS files:
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
- ```python
301
- STATICFILES_DIRS = [
302
- ...,
303
- os.path.join(BASE_DIR, "components"),
304
- ]
305
- ```
306
-
307
- If `STATICFILES_DIRS` is omitted or empty, django-components will by default look for
308
- `{BASE_DIR}/components`
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. To customize which template to use based on context
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 STATICFILES_DIRS
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 STATICFILES_DIRS
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 `STATICFILES_DIRS` directories are auto-imported in order to auto-register the components.
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
- template = """
1603
- <div>
1604
- {% slot "content" default %}
1605
- input: {{ input }}
1606
- {% endslot %}
1607
- </div>
1608
- """
1657
+ template = """
1658
+ <div>
1659
+ {% slot "content" default %}
1660
+ input: {{ input }}
1661
+ {% endslot %}
1662
+ </div>
1663
+ """
1609
1664
 
1610
- def get_context_data(self, input):
1611
- processed_input = do_something(input)
1612
- return {"input": processed_input}
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
- template = """
1632
- <div>
1633
- {% slot "content" default input=input %}
1634
- input: {{ input }}
1635
- {% endslot %}
1636
- </div>
1637
- """
1638
-
1639
- def get_context_data(self, input):
1640
- processed_input = do_something(input)
1641
- return {
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
- - `get_template_string`
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
- "class": "from-attrs",
1976
- "type": "submit",
2030
+ "class": "from-attrs",
2031
+ "type": "submit",
1977
2032
  }
1978
2033
 
1979
2034
  defaults = {
1980
- "class": "from-defaults",
1981
- "role": "button",
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 `STATICFILES_DIRS`.
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 `STATICFILES_DIRS` contains path `[project root]/components`, we can rewrite the example as:
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 `STATICFILES_DIRS`.
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 `STATICFILES_DIRS` to load the component files.
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