django-components 0.128__tar.gz → 0.129__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- django_components-0.129/PKG-INFO +363 -0
- django_components-0.129/README.md +332 -0
- {django_components-0.128 → django_components-0.129}/pyproject.toml +1 -1
- {django_components-0.128 → django_components-0.129}/src/django_components/component.py +5 -2
- {django_components-0.128 → django_components-0.129}/src/django_components/component_media.py +13 -8
- {django_components-0.128 → django_components-0.129}/src/django_components/slots.py +39 -4
- {django_components-0.128 → django_components-0.129}/src/django_components/util/cache.py +4 -0
- django_components-0.129/src/django_components.egg-info/PKG-INFO +363 -0
- django_components-0.128/PKG-INFO +0 -189
- django_components-0.128/README.md +0 -158
- django_components-0.128/src/django_components.egg-info/PKG-INFO +0 -189
- {django_components-0.128 → django_components-0.129}/LICENSE +0 -0
- {django_components-0.128 → django_components-0.129}/MANIFEST.in +0 -0
- {django_components-0.128 → django_components-0.129}/setup.cfg +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/__init__.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/app_settings.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/apps.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/attributes.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/autodiscovery.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/cache.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/component_registry.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/components/__init__.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/components/dynamic.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/context.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/dependencies.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/expression.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/finders.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/library.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/management/__init__.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/middleware.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/node.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/perfutil/__init__.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/perfutil/component.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/perfutil/provide.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/provide.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/py.typed +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/static/django_components/django_components.min.js +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/tag_formatter.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/template.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/template_loader.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/templatetags/component_tags.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/types.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/urls.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/__init__.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/component_highlight.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/context.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/django_monkeypatch.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/exception.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/loader.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/logger.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/misc.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/nanoid.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/tag_parser.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/template_parser.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/template_tag.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/types.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components/util/validation.py +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components.egg-info/SOURCES.txt +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.128 → django_components-0.129}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.128 → django_components-0.129}/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.129
|
|
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
|
+
[](https://pypi.org/project/django-components/) [](https://pypi.org/project/django-components/) [](https://github.com/django-components/django-components/blob/master/LICENSE/) [](https://pypistats.org/packages/django-components) [](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
|
+
[](https://pypi.org/project/django-components/) [](https://pypi.org/project/django-components/) [](https://github.com/django-components/django-components/blob/master/LICENSE/) [](https://pypistats.org/packages/django-components) [](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.
|
|
7
|
+
version = "0.129"
|
|
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"]
|