django-components 0.128__tar.gz → 0.130__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 (65) hide show
  1. django_components-0.130/PKG-INFO +363 -0
  2. django_components-0.130/README.md +332 -0
  3. {django_components-0.128 → django_components-0.130}/pyproject.toml +1 -1
  4. {django_components-0.128 → django_components-0.130}/src/django_components/component.py +122 -7
  5. {django_components-0.128 → django_components-0.130}/src/django_components/component_media.py +13 -8
  6. {django_components-0.128 → django_components-0.130}/src/django_components/slots.py +39 -4
  7. {django_components-0.128 → django_components-0.130}/src/django_components/util/cache.py +4 -0
  8. {django_components-0.128 → django_components-0.130}/src/django_components/util/context.py +44 -2
  9. django_components-0.130/src/django_components.egg-info/PKG-INFO +363 -0
  10. django_components-0.128/PKG-INFO +0 -189
  11. django_components-0.128/README.md +0 -158
  12. django_components-0.128/src/django_components.egg-info/PKG-INFO +0 -189
  13. {django_components-0.128 → django_components-0.130}/LICENSE +0 -0
  14. {django_components-0.128 → django_components-0.130}/MANIFEST.in +0 -0
  15. {django_components-0.128 → django_components-0.130}/setup.cfg +0 -0
  16. {django_components-0.128 → django_components-0.130}/src/django_components/__init__.py +0 -0
  17. {django_components-0.128 → django_components-0.130}/src/django_components/app_settings.py +0 -0
  18. {django_components-0.128 → django_components-0.130}/src/django_components/apps.py +0 -0
  19. {django_components-0.128 → django_components-0.130}/src/django_components/attributes.py +0 -0
  20. {django_components-0.128 → django_components-0.130}/src/django_components/autodiscovery.py +0 -0
  21. {django_components-0.128 → django_components-0.130}/src/django_components/cache.py +0 -0
  22. {django_components-0.128 → django_components-0.130}/src/django_components/component_registry.py +0 -0
  23. {django_components-0.128 → django_components-0.130}/src/django_components/components/__init__.py +0 -0
  24. {django_components-0.128 → django_components-0.130}/src/django_components/components/dynamic.py +0 -0
  25. {django_components-0.128 → django_components-0.130}/src/django_components/context.py +0 -0
  26. {django_components-0.128 → django_components-0.130}/src/django_components/dependencies.py +0 -0
  27. {django_components-0.128 → django_components-0.130}/src/django_components/expression.py +0 -0
  28. {django_components-0.128 → django_components-0.130}/src/django_components/finders.py +0 -0
  29. {django_components-0.128 → django_components-0.130}/src/django_components/library.py +0 -0
  30. {django_components-0.128 → django_components-0.130}/src/django_components/management/__init__.py +0 -0
  31. {django_components-0.128 → django_components-0.130}/src/django_components/management/commands/__init__.py +0 -0
  32. {django_components-0.128 → django_components-0.130}/src/django_components/management/commands/startcomponent.py +0 -0
  33. {django_components-0.128 → django_components-0.130}/src/django_components/management/commands/upgradecomponent.py +0 -0
  34. {django_components-0.128 → django_components-0.130}/src/django_components/middleware.py +0 -0
  35. {django_components-0.128 → django_components-0.130}/src/django_components/node.py +0 -0
  36. {django_components-0.128 → django_components-0.130}/src/django_components/perfutil/__init__.py +0 -0
  37. {django_components-0.128 → django_components-0.130}/src/django_components/perfutil/component.py +0 -0
  38. {django_components-0.128 → django_components-0.130}/src/django_components/perfutil/provide.py +0 -0
  39. {django_components-0.128 → django_components-0.130}/src/django_components/provide.py +0 -0
  40. {django_components-0.128 → django_components-0.130}/src/django_components/py.typed +0 -0
  41. {django_components-0.128 → django_components-0.130}/src/django_components/static/django_components/django_components.min.js +0 -0
  42. {django_components-0.128 → django_components-0.130}/src/django_components/tag_formatter.py +0 -0
  43. {django_components-0.128 → django_components-0.130}/src/django_components/template.py +0 -0
  44. {django_components-0.128 → django_components-0.130}/src/django_components/template_loader.py +0 -0
  45. {django_components-0.128 → django_components-0.130}/src/django_components/templatetags/__init__.py +0 -0
  46. {django_components-0.128 → django_components-0.130}/src/django_components/templatetags/component_tags.py +0 -0
  47. {django_components-0.128 → django_components-0.130}/src/django_components/types.py +0 -0
  48. {django_components-0.128 → django_components-0.130}/src/django_components/urls.py +0 -0
  49. {django_components-0.128 → django_components-0.130}/src/django_components/util/__init__.py +0 -0
  50. {django_components-0.128 → django_components-0.130}/src/django_components/util/component_highlight.py +0 -0
  51. {django_components-0.128 → django_components-0.130}/src/django_components/util/django_monkeypatch.py +0 -0
  52. {django_components-0.128 → django_components-0.130}/src/django_components/util/exception.py +0 -0
  53. {django_components-0.128 → django_components-0.130}/src/django_components/util/loader.py +0 -0
  54. {django_components-0.128 → django_components-0.130}/src/django_components/util/logger.py +0 -0
  55. {django_components-0.128 → django_components-0.130}/src/django_components/util/misc.py +0 -0
  56. {django_components-0.128 → django_components-0.130}/src/django_components/util/nanoid.py +0 -0
  57. {django_components-0.128 → django_components-0.130}/src/django_components/util/tag_parser.py +0 -0
  58. {django_components-0.128 → django_components-0.130}/src/django_components/util/template_parser.py +0 -0
  59. {django_components-0.128 → django_components-0.130}/src/django_components/util/template_tag.py +0 -0
  60. {django_components-0.128 → django_components-0.130}/src/django_components/util/types.py +0 -0
  61. {django_components-0.128 → django_components-0.130}/src/django_components/util/validation.py +0 -0
  62. {django_components-0.128 → django_components-0.130}/src/django_components.egg-info/SOURCES.txt +0 -0
  63. {django_components-0.128 → django_components-0.130}/src/django_components.egg-info/dependency_links.txt +0 -0
  64. {django_components-0.128 → django_components-0.130}/src/django_components.egg-info/requires.txt +0 -0
  65. {django_components-0.128 → django_components-0.130}/src/django_components.egg-info/top_level.txt +0 -0
@@ -0,0 +1,363 @@
1
+ Metadata-Version: 2.2
2
+ Name: django_components
3
+ Version: 0.130
4
+ Summary: A way to create simple reusable template components in Django.
5
+ Author-email: Emil Stenström <emil@emilstenstrom.se>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/django-components/django-components/
8
+ Project-URL: Documentation, https://django-components.github.io/django-components/
9
+ Project-URL: Changelog, https://django-components.github.io/django-components/latest/release_notes/
10
+ Project-URL: Issues, https://github.com/django-components/django-components/issues
11
+ Project-URL: Donate, https://github.com/sponsors/EmilStenstrom
12
+ Keywords: django,components,css,js,html
13
+ Classifier: Framework :: Django
14
+ Classifier: Framework :: Django :: 4.2
15
+ Classifier: Framework :: Django :: 5.0
16
+ Classifier: Framework :: Django :: 5.1
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.8
21
+ Classifier: Programming Language :: Python :: 3.9
22
+ Classifier: Programming Language :: Python :: 3.10
23
+ Classifier: Programming Language :: Python :: 3.11
24
+ Classifier: Programming Language :: Python :: 3.12
25
+ Classifier: Programming Language :: Python :: 3.13
26
+ Requires-Python: <4.0,>=3.8
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ Requires-Dist: Django>=4.2
30
+ Requires-Dist: djc-core-html-parser>=1.0
31
+
32
+ # <img src="https://raw.githubusercontent.com/django-components/django-components/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
33
+
34
+ [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://github.com/django-components/django-components/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/django-components/tests.yml)](https://github.com/django-components/django-components/actions/workflows/tests.yml)
35
+
36
+ ### <table><td>[Read the full documentation](https://django-components.github.io/django-components/latest/)</td></table>
37
+
38
+ <!-- TODO - Remove this banner after a month(?), so March 2025 -->
39
+ > ⚠️ Attention ⚠️ - We migrated from `EmilStenstrom/django-components` to `django-components/django-components`.
40
+ >
41
+ > **Repo name and documentation URL changed. Package name remains the same.**
42
+ >
43
+ > Report any broken links links in [#922](https://github.com/django-components/django-components/issues/922).
44
+
45
+ `django-components` combines Django's templating system with the modularity seen
46
+ in modern frontend frameworks like Vue or React.
47
+
48
+ With `django-components` you can support Django projects small and large without leaving the Django ecosystem.
49
+
50
+ ## Quickstart
51
+
52
+ A component in django-components can be as simple as a Django template and Python code to declare the component:
53
+
54
+ ```django
55
+ {# components/calendar/calendar.html #}
56
+ <div class="calendar">
57
+ Today's date is <span>{{ date }}</span>
58
+ </div>
59
+ ```
60
+
61
+ ```py
62
+ # components/calendar/calendar.html
63
+ from django_components import Component
64
+
65
+ class Calendar(Component):
66
+ template_file = "calendar.html"
67
+ ```
68
+
69
+ Or a combination of Django template, Python, CSS, and Javascript:
70
+
71
+ ```django
72
+ {# components/calendar/calendar.html #}
73
+ <div class="calendar">
74
+ Today's date is <span>{{ date }}</span>
75
+ </div>
76
+ ```
77
+
78
+ ```css
79
+ /* components/calendar/calendar.css */
80
+ .calendar {
81
+ width: 200px;
82
+ background: pink;
83
+ }
84
+ ```
85
+
86
+ ```js
87
+ /* components/calendar/calendar.js */
88
+ document.querySelector(".calendar").onclick = () => {
89
+ alert("Clicked calendar!");
90
+ };
91
+ ```
92
+
93
+ ```py
94
+ # components/calendar/calendar.py
95
+ from django_components import Component
96
+
97
+ class Calendar(Component):
98
+ template_file = "calendar.html"
99
+ js_file = "calendar.js"
100
+ css_file = "calendar.css"
101
+
102
+ def get_context_data(self, date):
103
+ return {"date": date}
104
+ ```
105
+
106
+ Use the component like this:
107
+
108
+ ```django
109
+ {% component "calendar" date="2024-11-06" %}{% endcomponent %}
110
+ ```
111
+
112
+ And this is what gets rendered:
113
+
114
+ ```html
115
+ <div class="calendar-component">
116
+ Today's date is <span>2024-11-06</span>
117
+ </div>
118
+ ```
119
+
120
+ ## Features
121
+
122
+ ### Modern and modular UI
123
+
124
+ - Create self-contained, reusable UI elements.
125
+ - Each component can include its own HTML, CSS, and JS, or additional third-party JS and CSS.
126
+ - HTML, CSS, and JS can be defined on the component class, or loaded from files.
127
+
128
+ ```python
129
+ from django_components import Component
130
+
131
+ @register("calendar")
132
+ class Calendar(Component):
133
+ template = """
134
+ <div class="calendar">
135
+ Today's date is
136
+ <span>{{ date }}</span>
137
+ </div>
138
+ """
139
+
140
+ css = """
141
+ .calendar {
142
+ width: 200px;
143
+ background: pink;
144
+ }
145
+ """
146
+
147
+ js = """
148
+ document.querySelector(".calendar")
149
+ .addEventListener("click", () => {
150
+ alert("Clicked calendar!");
151
+ });
152
+ """
153
+
154
+ # Additional JS and CSS
155
+ class Media:
156
+ js = ["https://cdn.jsdelivr.net/npm/htmx.org@2.1.1/dist/htmx.min.js"]
157
+ css = ["bootstrap/dist/css/bootstrap.min.css"]
158
+
159
+ # Variables available in the template
160
+ def get_context_data(self, date):
161
+ return {
162
+ "date": date
163
+ }
164
+ ```
165
+
166
+ ### Composition with slots
167
+
168
+ - Render components inside templates with `{% component %}` tag.
169
+ - Compose them with `{% slot %}` and `{% fill %}` tags.
170
+ - Vue-like slot system, including scoped slots.
171
+
172
+ ```django
173
+ {% component "Layout"
174
+ bookmarks=bookmarks
175
+ breadcrumbs=breadcrumbs
176
+ %}
177
+ {% fill "header" %}
178
+ <div class="flex justify-between gap-x-12">
179
+ <div class="prose">
180
+ <h3>{{ project.name }}</h3>
181
+ </div>
182
+ <div class="font-semibold text-gray-500">
183
+ {{ project.start_date }} - {{ project.end_date }}
184
+ </div>
185
+ </div>
186
+ {% endfill %}
187
+
188
+ {# Access data passed to `{% slot %}` with `data` #}
189
+ {% fill "tabs" data="tabs_data" %}
190
+ {% component "TabItem" header="Project Info" %}
191
+ {% component "ProjectInfo"
192
+ project=project
193
+ project_tags=project_tags
194
+ attrs:class="py-5"
195
+ attrs:width=tabs_data.width
196
+ / %}
197
+ {% endcomponent %}
198
+ {% endfill %}
199
+ {% endcomponent %}
200
+ ```
201
+
202
+ ### Extended template tags
203
+
204
+ `django-components` extends Django's template tags syntax with:
205
+
206
+ - Literal lists and dictionaries in template tags
207
+ - Self-closing tags `{% mytag / %}`
208
+ - Multi-line template tags
209
+ - Spread operator `...` to dynamically pass args or kwargs into the template tag
210
+ - Nested template tags like `"{{ first_name }} {{ last_name }}"`
211
+ - Flat definition of dictionary keys `attr:key=val`
212
+
213
+ ```django
214
+ {% component "table"
215
+ ...default_attrs
216
+ title="Friend list for {{ user.name }}"
217
+ headers=["Name", "Age", "Email"]
218
+ data=[
219
+ {
220
+ "name": "John"|upper,
221
+ "age": 30|add:1,
222
+ "email": "john@example.com",
223
+ "hobbies": ["reading"],
224
+ },
225
+ {
226
+ "name": "Jane"|upper,
227
+ "age": 25|add:1,
228
+ "email": "jane@example.com",
229
+ "hobbies": ["reading", "coding"],
230
+ },
231
+ ],
232
+ attrs:class="py-4 ma-2 border-2 border-gray-300 rounded-md"
233
+ / %}
234
+ ```
235
+
236
+ ### HTML fragment support
237
+
238
+ `django-components` makes intergration with HTMX, AlpineJS or jQuery easy by allowing components to be rendered as HTML fragments:
239
+
240
+ - Components's JS and CSS is loaded automatically when the fragment is inserted into the DOM.
241
+
242
+ - Expose components as views with `get`, `post`, `put`, `patch`, `delete` methods
243
+
244
+ ```py
245
+ # components/calendar/calendar.py
246
+ @register("calendar")
247
+ class Calendar(Component):
248
+ template_file = "calendar.html"
249
+
250
+ def get(self, request, *args, **kwargs):
251
+ page = request.GET.get("page", 1)
252
+ return self.render_to_response(
253
+ kwargs={
254
+ "page": page,
255
+ }
256
+ )
257
+
258
+ def get_context_data(self, page):
259
+ return {
260
+ "page": page,
261
+ }
262
+
263
+ # urls.py
264
+ path("calendar/", Calendar.as_view()),
265
+ ```
266
+
267
+ ### Type hints
268
+
269
+ Opt-in to type hints by defining types for component's args, kwargs, slots, and more:
270
+
271
+ ```py
272
+ from typing import NotRequired, Tuple, TypedDict, SlotContent, SlotFunc
273
+
274
+ ButtonArgs = Tuple[int, str]
275
+
276
+ class ButtonKwargs(TypedDict):
277
+ variable: str
278
+ another: int
279
+ maybe_var: NotRequired[int] # May be omitted
280
+
281
+ class ButtonData(TypedDict):
282
+ variable: str
283
+
284
+ class ButtonSlots(TypedDict):
285
+ my_slot: NotRequired[SlotFunc]
286
+ another_slot: SlotContent
287
+
288
+ ButtonType = Component[ButtonArgs, ButtonKwargs, ButtonSlots, ButtonData, JsData, CssData]
289
+
290
+ class Button(ButtonType):
291
+ def get_context_data(self, *args, **kwargs):
292
+ self.input.args[0] # int
293
+ self.input.kwargs["variable"] # str
294
+ self.input.slots["my_slot"] # SlotFunc[MySlotData]
295
+
296
+ return {} # Error: Key "variable" is missing
297
+ ```
298
+
299
+ When you then call `Button.render()` or `Button.render_to_response()`, you will get type hints:
300
+
301
+ ```py
302
+ Button.render(
303
+ # Error: First arg must be `int`, got `float`
304
+ args=(1.25, "abc"),
305
+ # Error: Key "another" is missing
306
+ kwargs={
307
+ "variable": "text",
308
+ },
309
+ )
310
+ ```
311
+
312
+ ### Debugging features
313
+
314
+ - **Visual component inspection**: Highlight components and slots directly in your browser.
315
+ - **Detailed tracing logs to supply AI-agents with context**: The logs include component and slot names and IDs, and their position in the tree.
316
+
317
+ <div style="text-align: center;">
318
+ <img src="https://github.com/django-components/django-components/blob/master/docs/images/debug-highlight-slots.png?raw=true" alt="Component debugging visualization showing slot highlighting" width="500" style="margin: auto;">
319
+ </div>
320
+
321
+ ### Sharing components
322
+
323
+ - Install and use third-party components from PyPI
324
+ - Or publish your own "component registry"
325
+ - Highly customizable - Choose how the components are called in the template, and more:
326
+
327
+ ```django
328
+ {% component "calendar" date="2024-11-06" %}
329
+ {% endcomponent %}
330
+
331
+ {% calendar date="2024-11-06" %}
332
+ {% endcalendar %}
333
+ ```
334
+
335
+ ### Other features
336
+
337
+ - Vue-like provide / inject system
338
+ - Format HTML attributes with `{% html_attrs %}`
339
+
340
+ ## Documentation
341
+
342
+ [Read the full documentation here](https://django-components.github.io/django-components/latest/).
343
+
344
+ ... or jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject).
345
+
346
+ ## Release notes
347
+
348
+ Read the [Release Notes](https://github.com/django-components/django-components/tree/master/CHANGELOG.md)
349
+ to see the latest features and fixes.
350
+
351
+ ## Community examples
352
+
353
+ One of our goals with `django-components` is to make it easy to share components between projects. If you have a set of components that you think would be useful to others, please open a pull request to add them to the list below.
354
+
355
+ - [django-htmx-components](https://github.com/iwanalabs/django-htmx-components): A set of components for use with [htmx](https://htmx.org/). Try out the [live demo](https://dhc.iwanalabs.com/).
356
+
357
+ - [djc-heroicons](https://pypi.org/project/djc-heroicons/): A component that renders icons from [Heroicons.com](https://heroicons.com/).
358
+
359
+ ## Contributing and development
360
+
361
+ Get involved or sponsor this project - [See here](https://django-components.github.io/django-components/dev/overview/contributing/)
362
+
363
+ Running django-components locally for development - [See here](https://django-components.github.io/django-components/dev/overview/development/)
@@ -0,0 +1,332 @@
1
+ # <img src="https://raw.githubusercontent.com/django-components/django-components/master/logo/logo-black-on-white.svg" alt="django-components" style="max-width: 100%; background: white; color: black;">
2
+
3
+ [![PyPI - Version](https://img.shields.io/pypi/v/django-components)](https://pypi.org/project/django-components/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-components)](https://pypi.org/project/django-components/) [![PyPI - License](https://img.shields.io/pypi/l/django-components)](https://github.com/django-components/django-components/blob/master/LICENSE/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/django-components)](https://pypistats.org/packages/django-components) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/django-components/django-components/tests.yml)](https://github.com/django-components/django-components/actions/workflows/tests.yml)
4
+
5
+ ### <table><td>[Read the full documentation](https://django-components.github.io/django-components/latest/)</td></table>
6
+
7
+ <!-- TODO - Remove this banner after a month(?), so March 2025 -->
8
+ > ⚠️ Attention ⚠️ - We migrated from `EmilStenstrom/django-components` to `django-components/django-components`.
9
+ >
10
+ > **Repo name and documentation URL changed. Package name remains the same.**
11
+ >
12
+ > Report any broken links links in [#922](https://github.com/django-components/django-components/issues/922).
13
+
14
+ `django-components` combines Django's templating system with the modularity seen
15
+ in modern frontend frameworks like Vue or React.
16
+
17
+ With `django-components` you can support Django projects small and large without leaving the Django ecosystem.
18
+
19
+ ## Quickstart
20
+
21
+ A component in django-components can be as simple as a Django template and Python code to declare the component:
22
+
23
+ ```django
24
+ {# components/calendar/calendar.html #}
25
+ <div class="calendar">
26
+ Today's date is <span>{{ date }}</span>
27
+ </div>
28
+ ```
29
+
30
+ ```py
31
+ # components/calendar/calendar.html
32
+ from django_components import Component
33
+
34
+ class Calendar(Component):
35
+ template_file = "calendar.html"
36
+ ```
37
+
38
+ Or a combination of Django template, Python, CSS, and Javascript:
39
+
40
+ ```django
41
+ {# components/calendar/calendar.html #}
42
+ <div class="calendar">
43
+ Today's date is <span>{{ date }}</span>
44
+ </div>
45
+ ```
46
+
47
+ ```css
48
+ /* components/calendar/calendar.css */
49
+ .calendar {
50
+ width: 200px;
51
+ background: pink;
52
+ }
53
+ ```
54
+
55
+ ```js
56
+ /* components/calendar/calendar.js */
57
+ document.querySelector(".calendar").onclick = () => {
58
+ alert("Clicked calendar!");
59
+ };
60
+ ```
61
+
62
+ ```py
63
+ # components/calendar/calendar.py
64
+ from django_components import Component
65
+
66
+ class Calendar(Component):
67
+ template_file = "calendar.html"
68
+ js_file = "calendar.js"
69
+ css_file = "calendar.css"
70
+
71
+ def get_context_data(self, date):
72
+ return {"date": date}
73
+ ```
74
+
75
+ Use the component like this:
76
+
77
+ ```django
78
+ {% component "calendar" date="2024-11-06" %}{% endcomponent %}
79
+ ```
80
+
81
+ And this is what gets rendered:
82
+
83
+ ```html
84
+ <div class="calendar-component">
85
+ Today's date is <span>2024-11-06</span>
86
+ </div>
87
+ ```
88
+
89
+ ## Features
90
+
91
+ ### Modern and modular UI
92
+
93
+ - Create self-contained, reusable UI elements.
94
+ - Each component can include its own HTML, CSS, and JS, or additional third-party JS and CSS.
95
+ - HTML, CSS, and JS can be defined on the component class, or loaded from files.
96
+
97
+ ```python
98
+ from django_components import Component
99
+
100
+ @register("calendar")
101
+ class Calendar(Component):
102
+ template = """
103
+ <div class="calendar">
104
+ Today's date is
105
+ <span>{{ date }}</span>
106
+ </div>
107
+ """
108
+
109
+ css = """
110
+ .calendar {
111
+ width: 200px;
112
+ background: pink;
113
+ }
114
+ """
115
+
116
+ js = """
117
+ document.querySelector(".calendar")
118
+ .addEventListener("click", () => {
119
+ alert("Clicked calendar!");
120
+ });
121
+ """
122
+
123
+ # Additional JS and CSS
124
+ class Media:
125
+ js = ["https://cdn.jsdelivr.net/npm/htmx.org@2.1.1/dist/htmx.min.js"]
126
+ css = ["bootstrap/dist/css/bootstrap.min.css"]
127
+
128
+ # Variables available in the template
129
+ def get_context_data(self, date):
130
+ return {
131
+ "date": date
132
+ }
133
+ ```
134
+
135
+ ### Composition with slots
136
+
137
+ - Render components inside templates with `{% component %}` tag.
138
+ - Compose them with `{% slot %}` and `{% fill %}` tags.
139
+ - Vue-like slot system, including scoped slots.
140
+
141
+ ```django
142
+ {% component "Layout"
143
+ bookmarks=bookmarks
144
+ breadcrumbs=breadcrumbs
145
+ %}
146
+ {% fill "header" %}
147
+ <div class="flex justify-between gap-x-12">
148
+ <div class="prose">
149
+ <h3>{{ project.name }}</h3>
150
+ </div>
151
+ <div class="font-semibold text-gray-500">
152
+ {{ project.start_date }} - {{ project.end_date }}
153
+ </div>
154
+ </div>
155
+ {% endfill %}
156
+
157
+ {# Access data passed to `{% slot %}` with `data` #}
158
+ {% fill "tabs" data="tabs_data" %}
159
+ {% component "TabItem" header="Project Info" %}
160
+ {% component "ProjectInfo"
161
+ project=project
162
+ project_tags=project_tags
163
+ attrs:class="py-5"
164
+ attrs:width=tabs_data.width
165
+ / %}
166
+ {% endcomponent %}
167
+ {% endfill %}
168
+ {% endcomponent %}
169
+ ```
170
+
171
+ ### Extended template tags
172
+
173
+ `django-components` extends Django's template tags syntax with:
174
+
175
+ - Literal lists and dictionaries in template tags
176
+ - Self-closing tags `{% mytag / %}`
177
+ - Multi-line template tags
178
+ - Spread operator `...` to dynamically pass args or kwargs into the template tag
179
+ - Nested template tags like `"{{ first_name }} {{ last_name }}"`
180
+ - Flat definition of dictionary keys `attr:key=val`
181
+
182
+ ```django
183
+ {% component "table"
184
+ ...default_attrs
185
+ title="Friend list for {{ user.name }}"
186
+ headers=["Name", "Age", "Email"]
187
+ data=[
188
+ {
189
+ "name": "John"|upper,
190
+ "age": 30|add:1,
191
+ "email": "john@example.com",
192
+ "hobbies": ["reading"],
193
+ },
194
+ {
195
+ "name": "Jane"|upper,
196
+ "age": 25|add:1,
197
+ "email": "jane@example.com",
198
+ "hobbies": ["reading", "coding"],
199
+ },
200
+ ],
201
+ attrs:class="py-4 ma-2 border-2 border-gray-300 rounded-md"
202
+ / %}
203
+ ```
204
+
205
+ ### HTML fragment support
206
+
207
+ `django-components` makes intergration with HTMX, AlpineJS or jQuery easy by allowing components to be rendered as HTML fragments:
208
+
209
+ - Components's JS and CSS is loaded automatically when the fragment is inserted into the DOM.
210
+
211
+ - Expose components as views with `get`, `post`, `put`, `patch`, `delete` methods
212
+
213
+ ```py
214
+ # components/calendar/calendar.py
215
+ @register("calendar")
216
+ class Calendar(Component):
217
+ template_file = "calendar.html"
218
+
219
+ def get(self, request, *args, **kwargs):
220
+ page = request.GET.get("page", 1)
221
+ return self.render_to_response(
222
+ kwargs={
223
+ "page": page,
224
+ }
225
+ )
226
+
227
+ def get_context_data(self, page):
228
+ return {
229
+ "page": page,
230
+ }
231
+
232
+ # urls.py
233
+ path("calendar/", Calendar.as_view()),
234
+ ```
235
+
236
+ ### Type hints
237
+
238
+ Opt-in to type hints by defining types for component's args, kwargs, slots, and more:
239
+
240
+ ```py
241
+ from typing import NotRequired, Tuple, TypedDict, SlotContent, SlotFunc
242
+
243
+ ButtonArgs = Tuple[int, str]
244
+
245
+ class ButtonKwargs(TypedDict):
246
+ variable: str
247
+ another: int
248
+ maybe_var: NotRequired[int] # May be omitted
249
+
250
+ class ButtonData(TypedDict):
251
+ variable: str
252
+
253
+ class ButtonSlots(TypedDict):
254
+ my_slot: NotRequired[SlotFunc]
255
+ another_slot: SlotContent
256
+
257
+ ButtonType = Component[ButtonArgs, ButtonKwargs, ButtonSlots, ButtonData, JsData, CssData]
258
+
259
+ class Button(ButtonType):
260
+ def get_context_data(self, *args, **kwargs):
261
+ self.input.args[0] # int
262
+ self.input.kwargs["variable"] # str
263
+ self.input.slots["my_slot"] # SlotFunc[MySlotData]
264
+
265
+ return {} # Error: Key "variable" is missing
266
+ ```
267
+
268
+ When you then call `Button.render()` or `Button.render_to_response()`, you will get type hints:
269
+
270
+ ```py
271
+ Button.render(
272
+ # Error: First arg must be `int`, got `float`
273
+ args=(1.25, "abc"),
274
+ # Error: Key "another" is missing
275
+ kwargs={
276
+ "variable": "text",
277
+ },
278
+ )
279
+ ```
280
+
281
+ ### Debugging features
282
+
283
+ - **Visual component inspection**: Highlight components and slots directly in your browser.
284
+ - **Detailed tracing logs to supply AI-agents with context**: The logs include component and slot names and IDs, and their position in the tree.
285
+
286
+ <div style="text-align: center;">
287
+ <img src="https://github.com/django-components/django-components/blob/master/docs/images/debug-highlight-slots.png?raw=true" alt="Component debugging visualization showing slot highlighting" width="500" style="margin: auto;">
288
+ </div>
289
+
290
+ ### Sharing components
291
+
292
+ - Install and use third-party components from PyPI
293
+ - Or publish your own "component registry"
294
+ - Highly customizable - Choose how the components are called in the template, and more:
295
+
296
+ ```django
297
+ {% component "calendar" date="2024-11-06" %}
298
+ {% endcomponent %}
299
+
300
+ {% calendar date="2024-11-06" %}
301
+ {% endcalendar %}
302
+ ```
303
+
304
+ ### Other features
305
+
306
+ - Vue-like provide / inject system
307
+ - Format HTML attributes with `{% html_attrs %}`
308
+
309
+ ## Documentation
310
+
311
+ [Read the full documentation here](https://django-components.github.io/django-components/latest/).
312
+
313
+ ... or jump right into the code, [check out the example project](https://github.com/django-components/django-components/tree/master/sampleproject).
314
+
315
+ ## Release notes
316
+
317
+ Read the [Release Notes](https://github.com/django-components/django-components/tree/master/CHANGELOG.md)
318
+ to see the latest features and fixes.
319
+
320
+ ## Community examples
321
+
322
+ One of our goals with `django-components` is to make it easy to share components between projects. If you have a set of components that you think would be useful to others, please open a pull request to add them to the list below.
323
+
324
+ - [django-htmx-components](https://github.com/iwanalabs/django-htmx-components): A set of components for use with [htmx](https://htmx.org/). Try out the [live demo](https://dhc.iwanalabs.com/).
325
+
326
+ - [djc-heroicons](https://pypi.org/project/djc-heroicons/): A component that renders icons from [Heroicons.com](https://heroicons.com/).
327
+
328
+ ## Contributing and development
329
+
330
+ Get involved or sponsor this project - [See here](https://django-components.github.io/django-components/dev/overview/contributing/)
331
+
332
+ Running django-components locally for development - [See here](https://django-components.github.io/django-components/dev/overview/development/)
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "django_components"
7
- version = "0.128"
7
+ version = "0.130"
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"]