django-components 0.75__tar.gz → 0.77__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.75/src/django_components.egg-info → django_components-0.77}/PKG-INFO +379 -148
- {django_components-0.75 → django_components-0.77}/README.md +378 -147
- {django_components-0.75 → django_components-0.77}/pyproject.toml +1 -1
- {django_components-0.75 → django_components-0.77}/src/django_components/component.py +13 -21
- django_components-0.77/src/django_components/expression.py +46 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/slots.py +74 -33
- {django_components-0.75 → django_components-0.77}/src/django_components/templatetags/component_tags.py +134 -72
- {django_components-0.75 → django_components-0.77/src/django_components.egg-info}/PKG-INFO +379 -148
- {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/SOURCES.txt +1 -0
- {django_components-0.75 → django_components-0.77}/tests/test_template_parser.py +3 -3
- {django_components-0.75 → django_components-0.77}/tests/test_templatetags.py +332 -27
- {django_components-0.75 → django_components-0.77}/LICENSE +0 -0
- {django_components-0.75 → django_components-0.77}/setup.cfg +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/__init__.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/app_settings.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/apps.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/attributes.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/component_registry.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/context.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/logger.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/management/__init__.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/middleware.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/node.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/py.typed +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/template_loader.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/template_parser.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/types.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components/utils.py +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_attributes.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_autodiscover.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_component.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_component_as_view.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_context.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_registry.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_settings.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/test_startcomponent_command.py +0 -0
- {django_components-0.75 → django_components-0.77}/tests/testutils.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: django_components
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.77
|
|
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
|
|
@@ -42,8 +42,38 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
42
42
|
|
|
43
43
|
Read on to learn about the details!
|
|
44
44
|
|
|
45
|
+
## Table of Contents
|
|
46
|
+
|
|
47
|
+
- [Release notes](#release-notes)
|
|
48
|
+
- [Security notes 🚨](#security-notes-)
|
|
49
|
+
- [Installation](#installation)
|
|
50
|
+
- [Compatiblity](#compatiblity)
|
|
51
|
+
- [Create your first component](#create-your-first-component)
|
|
52
|
+
- [Using single-file components](#using-single-file-components)
|
|
53
|
+
- [Use the component in a template](#use-the-component-in-a-template)
|
|
54
|
+
- [Use components as views](#use-components-as-views)
|
|
55
|
+
- [Registering components](#registering-components)
|
|
56
|
+
- [Autodiscovery](#autodiscovery)
|
|
57
|
+
- [Using slots in templates](#using-slots-in-templates)
|
|
58
|
+
- [Passing data to components](#passing-data-to-components)
|
|
59
|
+
- [Rendering HTML attributes](#rendering-html-attributes)
|
|
60
|
+
- [Component context and scope](#component-context-and-scope)
|
|
61
|
+
- [Rendering JS and CSS dependencies](#rendering-js-and-css-dependencies)
|
|
62
|
+
- [Available settings](#available-settings)
|
|
63
|
+
- [Logging and debugging](#logging-and-debugging)
|
|
64
|
+
- [Management Command](#management-command)
|
|
65
|
+
- [Community examples](#community-examples)
|
|
66
|
+
- [Running django-components project locally](#running-django-components-project-locally)
|
|
67
|
+
- [Development guides](#development-guides)
|
|
68
|
+
|
|
45
69
|
## Release notes
|
|
46
70
|
|
|
71
|
+
🚨📢 **Version 0.77** CHANGED the syntax for accessing default slot content.
|
|
72
|
+
- Previously, the syntax was
|
|
73
|
+
`{% fill "my_slot" as "alias" %}` and `{{ alias.default }}`.
|
|
74
|
+
- Now, the syntax is
|
|
75
|
+
`{% fill "my_slot" default="alias" %}` and `{{ alias }}`.
|
|
76
|
+
|
|
47
77
|
**Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
|
|
48
78
|
|
|
49
79
|
🚨📢 **Version 0.70**
|
|
@@ -57,7 +87,7 @@ Read on to learn about the details!
|
|
|
57
87
|
|
|
58
88
|
This change is done to simplify the API in anticipation of a 1.0 release of django_components. After 1.0 we intend to be stricter with big changes like this in point releases.
|
|
59
89
|
|
|
60
|
-
**Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](#components-as-views) for more details.
|
|
90
|
+
**Version 0.34** adds components as views, which allows you to handle requests and render responses from within a component. See the [documentation](#use-components-as-views) for more details.
|
|
61
91
|
|
|
62
92
|
**Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags.
|
|
63
93
|
|
|
@@ -261,19 +291,43 @@ class Calendar(component.Component):
|
|
|
261
291
|
|
|
262
292
|
And voilá!! We've created our first component.
|
|
263
293
|
|
|
264
|
-
##
|
|
294
|
+
## Using single-file components
|
|
265
295
|
|
|
266
|
-
|
|
296
|
+
Components can also be defined in a single file, which is useful for small components. To do this, you can use the `template`, `js`, and `css` class attributes instead of the `template_name` and `Media`. For example, here's the calendar component from above, defined in a single file:
|
|
267
297
|
|
|
268
|
-
|
|
298
|
+
```python
|
|
299
|
+
# In a file called [project root]/components/calendar.py
|
|
300
|
+
from django_components import component
|
|
301
|
+
from django_components import types as t
|
|
269
302
|
|
|
270
|
-
|
|
303
|
+
@component.register("calendar")
|
|
304
|
+
class Calendar(component.Component):
|
|
305
|
+
def get_context_data(self, date):
|
|
306
|
+
return {
|
|
307
|
+
"date": date,
|
|
308
|
+
}
|
|
271
309
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
310
|
+
template: t.django_html = """
|
|
311
|
+
<div class="calendar-component">Today's date is <span>{{ date }}</span></div>
|
|
312
|
+
"""
|
|
275
313
|
|
|
276
|
-
|
|
314
|
+
css: t.css = """
|
|
315
|
+
.calendar-component { width: 200px; background: pink; }
|
|
316
|
+
.calendar-component span { font-weight: bold; }
|
|
317
|
+
"""
|
|
318
|
+
|
|
319
|
+
js: t.js = """
|
|
320
|
+
(function(){
|
|
321
|
+
if (document.querySelector(".calendar-component")) {
|
|
322
|
+
document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
|
|
323
|
+
}
|
|
324
|
+
})()
|
|
325
|
+
"""
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
|
|
329
|
+
|
|
330
|
+
Note that the `t.django_html`, `t.css`, and `t.js` types are used to specify the type of the template, CSS, and JS files, respectively. This is not necessary, but if you're using VSCode with the [Python Inline Source Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=samwillis.python-inline-source) extension, it will give you syntax highlighting for the template, CSS, and JS.
|
|
277
331
|
|
|
278
332
|
## Use the component in a template
|
|
279
333
|
|
|
@@ -320,43 +374,86 @@ The output from the above template will be:
|
|
|
320
374
|
|
|
321
375
|
This makes it possible to organize your front-end around reusable components. Instead of relying on template tags and keeping your CSS and Javascript in the static directory.
|
|
322
376
|
|
|
323
|
-
##
|
|
377
|
+
## Use components as views
|
|
324
378
|
|
|
325
|
-
|
|
379
|
+
_New in version 0.34_
|
|
380
|
+
|
|
381
|
+
Components can now be used as views. To do this, `Component` subclasses Django's `View` class. This means that you can use all of the [methods](https://docs.djangoproject.com/en/5.0/ref/class-based-views/base/#view) of `View` in your component. For example, you can override `get` and `post` to handle GET and POST requests, respectively.
|
|
382
|
+
|
|
383
|
+
In addition, `Component` now has a `render_to_response` method that renders the component template based on the provided context and slots' data and returns an `HttpResponse` object.
|
|
384
|
+
|
|
385
|
+
Here's an example of a calendar component defined as a view:
|
|
326
386
|
|
|
327
387
|
```python
|
|
328
388
|
# In a file called [project root]/components/calendar.py
|
|
329
389
|
from django_components import component
|
|
330
|
-
from django_components import types as t
|
|
331
390
|
|
|
332
391
|
@component.register("calendar")
|
|
333
392
|
class Calendar(component.Component):
|
|
334
|
-
def get_context_data(self, date):
|
|
335
|
-
return {
|
|
336
|
-
"date": date,
|
|
337
|
-
}
|
|
338
393
|
|
|
339
|
-
template
|
|
340
|
-
<div class="calendar-component">
|
|
394
|
+
template = """
|
|
395
|
+
<div class="calendar-component">
|
|
396
|
+
<div class="header">
|
|
397
|
+
{% slot "header" %}{% endslot %}
|
|
398
|
+
</div>
|
|
399
|
+
<div class="body">
|
|
400
|
+
Today's date is <span>{{ date }}</span>
|
|
401
|
+
</div>
|
|
402
|
+
</div>
|
|
341
403
|
"""
|
|
342
404
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
405
|
+
def get(self, request, *args, **kwargs):
|
|
406
|
+
context = {
|
|
407
|
+
"date": request.GET.get("date", "2020-06-06"),
|
|
408
|
+
}
|
|
409
|
+
slots = {
|
|
410
|
+
"header": "Calendar header",
|
|
411
|
+
}
|
|
412
|
+
return self.render_to_response(context, slots)
|
|
413
|
+
```
|
|
347
414
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
415
|
+
Then, to use this component as a view, you should create a `urls.py` file in your components directory, and add a path to the component's view:
|
|
416
|
+
|
|
417
|
+
```python
|
|
418
|
+
# In a file called [project root]/components/urls.py
|
|
419
|
+
from django.urls import path
|
|
420
|
+
from components.calendar.calendar import Calendar
|
|
421
|
+
|
|
422
|
+
urlpatterns = [
|
|
423
|
+
path("calendar/", Calendar.as_view()),
|
|
424
|
+
]
|
|
355
425
|
```
|
|
356
426
|
|
|
357
|
-
|
|
427
|
+
Remember to add `__init__.py` to your components directory, so that Django can find the `urls.py` file.
|
|
358
428
|
|
|
359
|
-
|
|
429
|
+
Finally, include the component's urls in your project's `urls.py` file:
|
|
430
|
+
|
|
431
|
+
```python
|
|
432
|
+
# In a file called [project root]/urls.py
|
|
433
|
+
from django.urls import include, path
|
|
434
|
+
|
|
435
|
+
urlpatterns = [
|
|
436
|
+
path("components/", include("components.urls")),
|
|
437
|
+
]
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Note: slots content are automatically escaped by default to prevent XSS attacks. To disable escaping, set `escape_slots_content=False` in the `render_to_response` method. If you do so, you should make sure that any content you pass to the slots is safe, especially if it comes from user input.
|
|
441
|
+
|
|
442
|
+
If you're planning on passing an HTML string, check Django's use of [`format_html`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.html.format_html) and [`mark_safe`](https://docs.djangoproject.com/en/5.0/ref/utils/#django.utils.safestring.mark_safe).
|
|
443
|
+
|
|
444
|
+
## Autodiscovery
|
|
445
|
+
|
|
446
|
+
By default, the Python files in the `components` app are auto-imported in order to auto-register the components (e.g. `components/button/button.py`).
|
|
447
|
+
|
|
448
|
+
Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
|
|
449
|
+
|
|
450
|
+
If you are using autodiscovery, keep a few points in mind:
|
|
451
|
+
|
|
452
|
+
- Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
|
|
453
|
+
- Components inside the auto-imported files still need to be registered with `@component.register()`
|
|
454
|
+
- Auto-imported component files must be valid Python modules, they must use suffix `.py`, and module name should follow [PEP-8](https://peps.python.org/pep-0008/#package-and-module-names).
|
|
455
|
+
|
|
456
|
+
Autodiscovery can be disabled via in the [settings](#disable-autodiscovery).
|
|
360
457
|
|
|
361
458
|
## Using slots in templates
|
|
362
459
|
|
|
@@ -372,6 +469,7 @@ _New in version 0.26_:
|
|
|
372
469
|
Components support something called 'slots'.
|
|
373
470
|
When a component is used inside another template, slots allow the parent template to override specific parts of the child component by passing in different content.
|
|
374
471
|
This mechanism makes components more reusable and composable.
|
|
472
|
+
This behavior is similar to [slots in Vue](https://vuejs.org/guide/components/slots.html).
|
|
375
473
|
|
|
376
474
|
In the example below we introduce two block tags that work hand in hand to make this work. These are...
|
|
377
475
|
|
|
@@ -399,7 +497,7 @@ When using the component, you specify which slots you want to fill and where you
|
|
|
399
497
|
{% endcomponent %}
|
|
400
498
|
```
|
|
401
499
|
|
|
402
|
-
Since the header
|
|
500
|
+
Since the 'header' fill is unspecified, it's taken from the base template. If you put this in a template, and pass in `date=2020-06-06`, this is what gets rendered:
|
|
403
501
|
|
|
404
502
|
```htmldjango
|
|
405
503
|
<div class="calendar-component">
|
|
@@ -412,6 +510,10 @@ Since the header block is unspecified, it's taken from the base template. If you
|
|
|
412
510
|
</div>
|
|
413
511
|
```
|
|
414
512
|
|
|
513
|
+
### Default slot
|
|
514
|
+
|
|
515
|
+
_Added in version 0.28_
|
|
516
|
+
|
|
415
517
|
As you can see, component slots lets you write reusable containers that you fill in when you use a component. This makes for highly reusable components that can be used in different circumstances.
|
|
416
518
|
|
|
417
519
|
It can become tedious to use `fill` tags everywhere, especially when you're using a component that declares only one slot. To make things easier, `slot` tags can be marked with an optional keyword: `default`. When added to the end of the tag (as shown below), this option lets you pass filling content directly in the body of a `component` tag pair – without using a `fill` tag. Choose carefully, though: a component template may contain at most one slot that is marked as `default`. The `default` option can be combined with other slot options, e.g. `required`.
|
|
@@ -484,86 +586,101 @@ This is fine too:
|
|
|
484
586
|
{% endcomponent %}
|
|
485
587
|
```
|
|
486
588
|
|
|
487
|
-
###
|
|
589
|
+
### Render fill in multiple places
|
|
488
590
|
|
|
489
|
-
|
|
591
|
+
_Added in version 0.70_
|
|
490
592
|
|
|
491
|
-
|
|
593
|
+
You can render the same content in multiple places by defining multiple slots with
|
|
594
|
+
identical names:
|
|
492
595
|
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
596
|
+
```htmldjango
|
|
597
|
+
<div class="calendar-component">
|
|
598
|
+
<div class="header">
|
|
599
|
+
{% slot "image" %}Image here{% endslot %}
|
|
600
|
+
</div>
|
|
601
|
+
<div class="body">
|
|
602
|
+
{% slot "image" %}Image here{% endslot %}
|
|
603
|
+
</div>
|
|
604
|
+
</div>
|
|
605
|
+
```
|
|
496
606
|
|
|
497
|
-
|
|
498
|
-
# In a file called [project root]/components/calendar.py
|
|
499
|
-
from django_components import component
|
|
607
|
+
So if used like:
|
|
500
608
|
|
|
501
|
-
|
|
502
|
-
|
|
609
|
+
```htmldjango
|
|
610
|
+
{% component "calendar" date="2020-06-06" %}
|
|
611
|
+
{% fill "image" %}
|
|
612
|
+
<img src="..." />
|
|
613
|
+
{% endfill %}
|
|
614
|
+
{% endcomponent %}
|
|
615
|
+
```
|
|
503
616
|
|
|
504
|
-
|
|
505
|
-
<div class="calendar-component">
|
|
506
|
-
<div class="header">
|
|
507
|
-
{% slot "header" %}{% endslot %}
|
|
508
|
-
</div>
|
|
509
|
-
<div class="body">
|
|
510
|
-
Today's date is <span>{{ date }}</span>
|
|
511
|
-
</div>
|
|
512
|
-
</div>
|
|
513
|
-
"""
|
|
617
|
+
This renders:
|
|
514
618
|
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
619
|
+
```htmldjango
|
|
620
|
+
<div class="calendar-component">
|
|
621
|
+
<div class="header">
|
|
622
|
+
<img src="..." />
|
|
623
|
+
</div>
|
|
624
|
+
<div class="body">
|
|
625
|
+
<img src="..." />
|
|
626
|
+
</div>
|
|
627
|
+
</div>
|
|
523
628
|
```
|
|
524
629
|
|
|
525
|
-
|
|
630
|
+
#### Default and required slots
|
|
526
631
|
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
from django.urls import path
|
|
530
|
-
from components.calendar.calendar import Calendar
|
|
632
|
+
If you use a slot multiple times, you can still mark the slot as `default` or `required`.
|
|
633
|
+
For that, you must mark ONLY ONE of the identical slots.
|
|
531
634
|
|
|
532
|
-
|
|
533
|
-
path("calendar/", Calendar.as_view()),
|
|
534
|
-
]
|
|
535
|
-
```
|
|
536
|
-
|
|
537
|
-
Remember to add `__init__.py` to your components directory, so that Django can find the `urls.py` file.
|
|
635
|
+
We recommend to mark the first occurence for consistency, e.g.:
|
|
538
636
|
|
|
539
|
-
|
|
637
|
+
```htmldjango
|
|
638
|
+
<div class="calendar-component">
|
|
639
|
+
<div class="header">
|
|
640
|
+
{% slot "image" default required %}Image here{% endslot %}
|
|
641
|
+
</div>
|
|
642
|
+
<div class="body">
|
|
643
|
+
{% slot "image" %}Image here{% endslot %}
|
|
644
|
+
</div>
|
|
645
|
+
</div>
|
|
646
|
+
```
|
|
540
647
|
|
|
541
|
-
|
|
542
|
-
# In a file called [project root]/urls.py
|
|
543
|
-
from django.urls import include, path
|
|
648
|
+
Which you can then use are regular default slot:
|
|
544
649
|
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
650
|
+
```htmldjango
|
|
651
|
+
{% component "calendar" date="2020-06-06" %}
|
|
652
|
+
<img src="..." />
|
|
653
|
+
{% endcomponent %}
|
|
548
654
|
```
|
|
549
655
|
|
|
550
|
-
|
|
656
|
+
### Accessing original content of slots
|
|
551
657
|
|
|
552
|
-
|
|
658
|
+
_Added in version 0.26_
|
|
553
659
|
|
|
554
|
-
|
|
660
|
+
> NOTE: In version 0.77, the syntax was changed from
|
|
661
|
+
> ```django
|
|
662
|
+
> {% fill "my_slot" as "alias" %} {{ alias.default }}
|
|
663
|
+
> ```
|
|
664
|
+
> to
|
|
665
|
+
> ```django
|
|
666
|
+
> {% fill "my_slot" default="slot_default" %} {{ slot_default }}
|
|
667
|
+
> ```
|
|
555
668
|
|
|
556
|
-
|
|
669
|
+
Sometimes you may want to keep the original slot, but only wrap or prepend/append content to it. To do so, you can access the default slot via the `default` kwarg.
|
|
557
670
|
|
|
558
|
-
|
|
671
|
+
Similarly to the `data` attribute, you specify the variable name through which the default slot will be made available.
|
|
672
|
+
|
|
673
|
+
For instance, let's say you're filling a slot called 'body'. To render the original slot, assign it to a variable using the `'default'` keyword. You then render this variable to insert the default content:
|
|
559
674
|
|
|
560
675
|
```htmldjango
|
|
561
676
|
{% component "calendar" date="2020-06-06" %}
|
|
562
|
-
{% fill "body"
|
|
677
|
+
{% fill "body" default="body_default" %}
|
|
678
|
+
{{ body_default }}. Have a great day!
|
|
679
|
+
{% endfill %}
|
|
563
680
|
{% endcomponent %}
|
|
564
681
|
```
|
|
565
682
|
|
|
566
|
-
|
|
683
|
+
This produces:
|
|
567
684
|
|
|
568
685
|
```htmldjango
|
|
569
686
|
<div class="calendar-component">
|
|
@@ -576,7 +693,7 @@ Produces:
|
|
|
576
693
|
</div>
|
|
577
694
|
```
|
|
578
695
|
|
|
579
|
-
|
|
696
|
+
### Conditional slots
|
|
580
697
|
|
|
581
698
|
_Added in version 0.26._
|
|
582
699
|
|
|
@@ -662,7 +779,7 @@ To negate the meaning of `component_vars.is_filled`, simply treat it as boolean
|
|
|
662
779
|
{% endif %}
|
|
663
780
|
```
|
|
664
781
|
|
|
665
|
-
|
|
782
|
+
#### Accessing `is_filled` of slot names with special characters
|
|
666
783
|
|
|
667
784
|
To be able to access a slot name via `component_vars.is_filled`, the slot name needs to be composed of only alphanumeric characters and underscores (e.g. `this__isvalid_123`).
|
|
668
785
|
|
|
@@ -670,27 +787,103 @@ However, you can still define slots with other special characters. In such case,
|
|
|
670
787
|
|
|
671
788
|
So a slot named `"my super-slot :)"` will be available as `component_vars.is_filled.my_super_slot___`.
|
|
672
789
|
|
|
673
|
-
###
|
|
790
|
+
### Scoped slots
|
|
674
791
|
|
|
675
|
-
|
|
792
|
+
_Added in version 0.76_:
|
|
676
793
|
|
|
677
|
-
|
|
794
|
+
Consider a component with slot(s). This component may do some processing on the inputs, and then use the processed variable in the slot's default template:
|
|
678
795
|
|
|
679
|
-
```
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
796
|
+
```py
|
|
797
|
+
@component.register("my_comp")
|
|
798
|
+
class MyComp(component.Component):
|
|
799
|
+
template = """
|
|
800
|
+
<div>
|
|
801
|
+
{% slot "content" default %}
|
|
802
|
+
input: {{ input }}
|
|
803
|
+
{% endslot %}
|
|
804
|
+
</div>
|
|
805
|
+
"""
|
|
806
|
+
|
|
807
|
+
def get_context_data(self, input):
|
|
808
|
+
processed_input = do_something(input)
|
|
809
|
+
return {"input": processed_input}
|
|
685
810
|
```
|
|
686
811
|
|
|
687
|
-
|
|
812
|
+
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.
|
|
688
813
|
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
814
|
+
This behavior is called "scoped slots". This is inspired by [Vue scoped slots](https://vuejs.org/guide/components/slots.html#scoped-slots) and [scoped slots of django-web-components](https://github.com/Xzya/django-web-components/tree/master?tab=readme-ov-file#scoped-slots).
|
|
815
|
+
|
|
816
|
+
Using scoped slots consists of two steps:
|
|
817
|
+
|
|
818
|
+
1. Passing data to `slot` tag
|
|
819
|
+
2. Accessing data in `fill` tag
|
|
820
|
+
|
|
821
|
+
#### Passing data to slots
|
|
822
|
+
|
|
823
|
+
To pass the data to the `slot` tag, simply pass them as keyword attributes (`key=value`):
|
|
824
|
+
|
|
825
|
+
```py
|
|
826
|
+
@component.register("my_comp")
|
|
827
|
+
class MyComp(component.Component):
|
|
828
|
+
template = """
|
|
829
|
+
<div>
|
|
830
|
+
{% slot "content" default input=input %}
|
|
831
|
+
input: {{ input }}
|
|
832
|
+
{% endslot %}
|
|
833
|
+
</div>
|
|
834
|
+
"""
|
|
835
|
+
|
|
836
|
+
def get_context_data(self, input):
|
|
837
|
+
processed_input = do_something(input)
|
|
838
|
+
return {
|
|
839
|
+
"input": processed_input,
|
|
840
|
+
}
|
|
841
|
+
```
|
|
842
|
+
|
|
843
|
+
#### Accessing slot data in fill
|
|
844
|
+
|
|
845
|
+
Next, we head over to where we define a fill for this slot. Here, to access the slot data
|
|
846
|
+
we set the `data` attribute to the name of the variable through which we want to access
|
|
847
|
+
the slot data. In the example below, we set it to `data`:
|
|
848
|
+
|
|
849
|
+
```django
|
|
850
|
+
{% component "my_comp" %}
|
|
851
|
+
{% fill "content" data="data" %}
|
|
852
|
+
{{ data.input }}
|
|
853
|
+
{% endfill %}
|
|
854
|
+
{% endcomponent %}
|
|
855
|
+
```
|
|
856
|
+
|
|
857
|
+
To access slot data on a default slot, you have to explictly define the `{% fill %}` tags.
|
|
858
|
+
|
|
859
|
+
So this works:
|
|
860
|
+
|
|
861
|
+
```django
|
|
862
|
+
{% component "my_comp" %}
|
|
863
|
+
{% fill "content" data="data" %}
|
|
864
|
+
{{ data.input }}
|
|
865
|
+
{% endfill %}
|
|
866
|
+
{% endcomponent %}
|
|
867
|
+
```
|
|
868
|
+
|
|
869
|
+
While this does not:
|
|
870
|
+
|
|
871
|
+
```django
|
|
872
|
+
{% component "my_comp" data="data" %}
|
|
873
|
+
{{ data.input }}
|
|
874
|
+
{% endcomponent %}
|
|
875
|
+
```
|
|
876
|
+
|
|
877
|
+
Note: You cannot set the `data` attribute and
|
|
878
|
+
[`default` attribute)](#accessing-original-content-of-slots)
|
|
879
|
+
to the same name. This raises an error:
|
|
880
|
+
|
|
881
|
+
```django
|
|
882
|
+
{% component "my_comp" %}
|
|
883
|
+
{% fill "content" data="slot_var" default="slot_var" %}
|
|
884
|
+
{{ slot_var.input }}
|
|
885
|
+
{% endfill %}
|
|
886
|
+
{% endcomponent %}
|
|
694
887
|
```
|
|
695
888
|
|
|
696
889
|
## Passing data to components
|
|
@@ -801,7 +994,7 @@ Sweet! Now all the relevant HTML is inside the template, and we can move it to a
|
|
|
801
994
|
```
|
|
802
995
|
|
|
803
996
|
> Note: It is NOT possible to define nested dictionaries, so
|
|
804
|
-
`attrs:my_key:two=2` would be interpreted as:
|
|
997
|
+
> `attrs:my_key:two=2` would be interpreted as:
|
|
805
998
|
>
|
|
806
999
|
> ```py
|
|
807
1000
|
> {"attrs": {"my_key:two": 2}}
|
|
@@ -931,6 +1124,7 @@ We can achieve this by adding extra kwargs. These values
|
|
|
931
1124
|
will be appended, instead of overwriting the previous value.
|
|
932
1125
|
|
|
933
1126
|
So if we have a variable `attrs`:
|
|
1127
|
+
|
|
934
1128
|
```py
|
|
935
1129
|
attrs = {
|
|
936
1130
|
"class": "my-class pa-4",
|
|
@@ -962,19 +1156,20 @@ To simplify merging of variables, you can supply the same key multiple times, an
|
|
|
962
1156
|
Renders:
|
|
963
1157
|
|
|
964
1158
|
```html
|
|
965
|
-
<div
|
|
966
|
-
|
|
1159
|
+
<div
|
|
1160
|
+
data-value="my-class pa-4 some-class another-class class-from-var text-red"
|
|
1161
|
+
></div>
|
|
967
1162
|
```
|
|
968
1163
|
|
|
969
1164
|
### Rules for `html_attrs`
|
|
970
1165
|
|
|
971
1166
|
1. Both `attrs` and `defaults` can be passed as positional args
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
1167
|
+
|
|
1168
|
+
`{% html_attrs attrs defaults key=val %}`
|
|
1169
|
+
|
|
1170
|
+
or as kwargs
|
|
1171
|
+
|
|
1172
|
+
`{% html_attrs key=val defaults=defaults attrs=attrs %}`
|
|
978
1173
|
|
|
979
1174
|
2. Both `attrs` and `defaults` are optional (can be omitted)
|
|
980
1175
|
|
|
@@ -1003,64 +1198,64 @@ defaults = {
|
|
|
1003
1198
|
Then:
|
|
1004
1199
|
|
|
1005
1200
|
- Empty tag <br/>
|
|
1006
|
-
|
|
1201
|
+
`{% html_attr %}`
|
|
1007
1202
|
|
|
1008
|
-
|
|
1009
|
-
|
|
1203
|
+
renders (empty string): <br/>
|
|
1204
|
+
` `
|
|
1010
1205
|
|
|
1011
1206
|
- Only kwargs <br/>
|
|
1012
|
-
|
|
1207
|
+
`{% html_attr class="some-class" class=class_from_var data-id="123" %}`
|
|
1013
1208
|
|
|
1014
|
-
|
|
1015
|
-
|
|
1209
|
+
renders: <br/>
|
|
1210
|
+
`class="some-class from-var" data-id="123"`
|
|
1016
1211
|
|
|
1017
1212
|
- Only attrs <br/>
|
|
1018
|
-
|
|
1213
|
+
`{% html_attr attrs %}`
|
|
1019
1214
|
|
|
1020
|
-
|
|
1021
|
-
|
|
1215
|
+
renders: <br/>
|
|
1216
|
+
`class="from-attrs" type="submit"`
|
|
1022
1217
|
|
|
1023
1218
|
- Attrs as kwarg <br/>
|
|
1024
|
-
|
|
1219
|
+
`{% html_attr attrs=attrs %}`
|
|
1025
1220
|
|
|
1026
|
-
|
|
1027
|
-
|
|
1221
|
+
renders: <br/>
|
|
1222
|
+
`class="from-attrs" type="submit"`
|
|
1028
1223
|
|
|
1029
1224
|
- Only defaults (as kwarg) <br/>
|
|
1030
|
-
|
|
1225
|
+
`{% html_attr defaults=defaults %}`
|
|
1031
1226
|
|
|
1032
|
-
|
|
1033
|
-
|
|
1227
|
+
renders: <br/>
|
|
1228
|
+
`class="from-defaults" role="button"`
|
|
1034
1229
|
|
|
1035
1230
|
- Attrs using the `prefix:key=value` construct <br/>
|
|
1036
|
-
|
|
1231
|
+
`{% html_attr attrs:class="from-attrs" attrs:type="submit" %}`
|
|
1037
1232
|
|
|
1038
|
-
|
|
1039
|
-
|
|
1233
|
+
renders: <br/>
|
|
1234
|
+
`class="from-attrs" type="submit"`
|
|
1040
1235
|
|
|
1041
1236
|
- Defaults using the `prefix:key=value` construct <br/>
|
|
1042
|
-
|
|
1237
|
+
`{% html_attr defaults:class="from-defaults" %}`
|
|
1043
1238
|
|
|
1044
|
-
|
|
1045
|
-
|
|
1239
|
+
renders: <br/>
|
|
1240
|
+
`class="from-defaults" role="button"`
|
|
1046
1241
|
|
|
1047
1242
|
- All together (1) - attrs and defaults as positional args: <br/>
|
|
1048
|
-
|
|
1243
|
+
`{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}`
|
|
1049
1244
|
|
|
1050
|
-
|
|
1051
|
-
|
|
1245
|
+
renders: <br/>
|
|
1246
|
+
`class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
|
|
1052
1247
|
|
|
1053
1248
|
- All together (2) - attrs and defaults as kwargs args: <br/>
|
|
1054
|
-
|
|
1249
|
+
`{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}`
|
|
1055
1250
|
|
|
1056
|
-
|
|
1057
|
-
|
|
1251
|
+
renders: <br/>
|
|
1252
|
+
`class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
|
|
1058
1253
|
|
|
1059
1254
|
- All together (3) - mixed: <br/>
|
|
1060
|
-
|
|
1255
|
+
`{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}`
|
|
1061
1256
|
|
|
1062
|
-
|
|
1063
|
-
|
|
1257
|
+
renders: <br/>
|
|
1258
|
+
`class="from-attrs added_class from-var" type="submit" data-id=123`
|
|
1064
1259
|
|
|
1065
1260
|
### Full example for `html_attrs`
|
|
1066
1261
|
|
|
@@ -1156,14 +1351,16 @@ attrs = {
|
|
|
1156
1351
|
will be merged.
|
|
1157
1352
|
|
|
1158
1353
|
So in the end `MyComp` will render:
|
|
1354
|
+
|
|
1159
1355
|
```html
|
|
1160
1356
|
<div
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1357
|
+
class="pa-0 border-solid my-comp-date extra-class"
|
|
1358
|
+
data-id="123"
|
|
1359
|
+
data-json='{"value": 456}'
|
|
1360
|
+
@click="(e) => onClick(e, 'from_parent')"
|
|
1165
1361
|
>
|
|
1166
|
-
|
|
1362
|
+
...
|
|
1363
|
+
</div>
|
|
1167
1364
|
```
|
|
1168
1365
|
|
|
1169
1366
|
### Rendering HTML attributes outside of templates
|
|
@@ -1199,6 +1396,40 @@ NOTE: `{% csrf_token %}` tags need access to the top-level context, and they wil
|
|
|
1199
1396
|
|
|
1200
1397
|
Components can also access the outer context in their context methods by accessing the property `outer_context`.
|
|
1201
1398
|
|
|
1399
|
+
## Rendering JS and CSS dependencies
|
|
1400
|
+
|
|
1401
|
+
The JS and CSS files included in components are not automatically rendered.
|
|
1402
|
+
Instead, use the following tags to specify where to render the dependencies:
|
|
1403
|
+
- `component_dependencies` - Renders both JS and CSS
|
|
1404
|
+
- `component_js_dependencies` - Renders only JS
|
|
1405
|
+
- `component_css_dependencies` - Reneders only CSS
|
|
1406
|
+
|
|
1407
|
+
JS files are rendered as `<script>` tags.<br/>
|
|
1408
|
+
CSS files are rendered as `<style>` tags.
|
|
1409
|
+
|
|
1410
|
+
### Setting Up `ComponentDependencyMiddleware`
|
|
1411
|
+
|
|
1412
|
+
`ComponentDependencyMiddleware` is a Django middleware designed to manage and inject CSS/JS dependencies for rendered components dynamically. It ensures that only the necessary stylesheets and scripts are loaded in your HTML responses, based on the components used in your Django templates.
|
|
1413
|
+
|
|
1414
|
+
To set it up, add the middleware to your `MIDDLEWARE` in settings.py:
|
|
1415
|
+
|
|
1416
|
+
```python
|
|
1417
|
+
MIDDLEWARE = [
|
|
1418
|
+
# ... other middleware classes ...
|
|
1419
|
+
'django_components.middleware.ComponentDependencyMiddleware'
|
|
1420
|
+
# ... other middleware classes ...
|
|
1421
|
+
]
|
|
1422
|
+
```
|
|
1423
|
+
|
|
1424
|
+
Then, enable `RENDER_DEPENDENCIES` in setting.py:
|
|
1425
|
+
|
|
1426
|
+
```python
|
|
1427
|
+
COMPONENTS = {
|
|
1428
|
+
"RENDER_DEPENDENCIES": True,
|
|
1429
|
+
# ... other component settings ...
|
|
1430
|
+
}
|
|
1431
|
+
```
|
|
1432
|
+
|
|
1202
1433
|
## Available settings
|
|
1203
1434
|
|
|
1204
1435
|
All library settings are handled from a global `COMPONENTS` variable that is read from `settings.py`. By default you don't need it set, there are resonable defaults.
|