django-components 0.75__tar.gz → 0.76__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.76}/PKG-INFO +359 -147
- {django_components-0.75 → django_components-0.76}/README.md +358 -146
- {django_components-0.75 → django_components-0.76}/pyproject.toml +1 -1
- {django_components-0.75 → django_components-0.76}/src/django_components/component.py +11 -19
- django_components-0.76/src/django_components/expression.py +46 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/slots.py +42 -8
- {django_components-0.75 → django_components-0.76}/src/django_components/templatetags/component_tags.py +126 -71
- {django_components-0.75 → django_components-0.76/src/django_components.egg-info}/PKG-INFO +359 -147
- {django_components-0.75 → django_components-0.76}/src/django_components.egg-info/SOURCES.txt +1 -0
- {django_components-0.75 → django_components-0.76}/tests/test_template_parser.py +3 -3
- {django_components-0.75 → django_components-0.76}/tests/test_templatetags.py +211 -0
- {django_components-0.75 → django_components-0.76}/LICENSE +0 -0
- {django_components-0.75 → django_components-0.76}/setup.cfg +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/__init__.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/app_settings.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/apps.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/attributes.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/component_registry.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/context.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/logger.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/management/__init__.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/middleware.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/node.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/py.typed +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/template_loader.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/template_parser.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/types.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components/utils.py +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.75 → django_components-0.76}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_attributes.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_autodiscover.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_component.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_component_as_view.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_context.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_registry.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_settings.py +0 -0
- {django_components-0.75 → django_components-0.76}/tests/test_startcomponent_command.py +0 -0
- {django_components-0.75 → django_components-0.76}/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.76
|
|
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,6 +42,30 @@ 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
|
|
|
47
71
|
**Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
|
|
@@ -57,7 +81,7 @@ Read on to learn about the details!
|
|
|
57
81
|
|
|
58
82
|
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
83
|
|
|
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.
|
|
84
|
+
**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
85
|
|
|
62
86
|
**Version 0.28** introduces 'implicit' slot filling and the `default` option for `slot` tags.
|
|
63
87
|
|
|
@@ -261,19 +285,43 @@ class Calendar(component.Component):
|
|
|
261
285
|
|
|
262
286
|
And voilá!! We've created our first component.
|
|
263
287
|
|
|
264
|
-
##
|
|
288
|
+
## Using single-file components
|
|
265
289
|
|
|
266
|
-
|
|
290
|
+
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
291
|
|
|
268
|
-
|
|
292
|
+
```python
|
|
293
|
+
# In a file called [project root]/components/calendar.py
|
|
294
|
+
from django_components import component
|
|
295
|
+
from django_components import types as t
|
|
269
296
|
|
|
270
|
-
|
|
297
|
+
@component.register("calendar")
|
|
298
|
+
class Calendar(component.Component):
|
|
299
|
+
def get_context_data(self, date):
|
|
300
|
+
return {
|
|
301
|
+
"date": date,
|
|
302
|
+
}
|
|
271
303
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
304
|
+
template: t.django_html = """
|
|
305
|
+
<div class="calendar-component">Today's date is <span>{{ date }}</span></div>
|
|
306
|
+
"""
|
|
275
307
|
|
|
276
|
-
|
|
308
|
+
css: t.css = """
|
|
309
|
+
.calendar-component { width: 200px; background: pink; }
|
|
310
|
+
.calendar-component span { font-weight: bold; }
|
|
311
|
+
"""
|
|
312
|
+
|
|
313
|
+
js: t.js = """
|
|
314
|
+
(function(){
|
|
315
|
+
if (document.querySelector(".calendar-component")) {
|
|
316
|
+
document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
|
|
317
|
+
}
|
|
318
|
+
})()
|
|
319
|
+
"""
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
This makes it easy to create small components without having to create a separate template, CSS, and JS file.
|
|
323
|
+
|
|
324
|
+
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
325
|
|
|
278
326
|
## Use the component in a template
|
|
279
327
|
|
|
@@ -320,43 +368,86 @@ The output from the above template will be:
|
|
|
320
368
|
|
|
321
369
|
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
370
|
|
|
323
|
-
##
|
|
371
|
+
## Use components as views
|
|
324
372
|
|
|
325
|
-
|
|
373
|
+
_New in version 0.34_
|
|
374
|
+
|
|
375
|
+
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.
|
|
376
|
+
|
|
377
|
+
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.
|
|
378
|
+
|
|
379
|
+
Here's an example of a calendar component defined as a view:
|
|
326
380
|
|
|
327
381
|
```python
|
|
328
382
|
# In a file called [project root]/components/calendar.py
|
|
329
383
|
from django_components import component
|
|
330
|
-
from django_components import types as t
|
|
331
384
|
|
|
332
385
|
@component.register("calendar")
|
|
333
386
|
class Calendar(component.Component):
|
|
334
|
-
def get_context_data(self, date):
|
|
335
|
-
return {
|
|
336
|
-
"date": date,
|
|
337
|
-
}
|
|
338
387
|
|
|
339
|
-
template
|
|
340
|
-
<div class="calendar-component">
|
|
388
|
+
template = """
|
|
389
|
+
<div class="calendar-component">
|
|
390
|
+
<div class="header">
|
|
391
|
+
{% slot "header" %}{% endslot %}
|
|
392
|
+
</div>
|
|
393
|
+
<div class="body">
|
|
394
|
+
Today's date is <span>{{ date }}</span>
|
|
395
|
+
</div>
|
|
396
|
+
</div>
|
|
341
397
|
"""
|
|
342
398
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
399
|
+
def get(self, request, *args, **kwargs):
|
|
400
|
+
context = {
|
|
401
|
+
"date": request.GET.get("date", "2020-06-06"),
|
|
402
|
+
}
|
|
403
|
+
slots = {
|
|
404
|
+
"header": "Calendar header",
|
|
405
|
+
}
|
|
406
|
+
return self.render_to_response(context, slots)
|
|
407
|
+
```
|
|
347
408
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
409
|
+
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:
|
|
410
|
+
|
|
411
|
+
```python
|
|
412
|
+
# In a file called [project root]/components/urls.py
|
|
413
|
+
from django.urls import path
|
|
414
|
+
from components.calendar.calendar import Calendar
|
|
415
|
+
|
|
416
|
+
urlpatterns = [
|
|
417
|
+
path("calendar/", Calendar.as_view()),
|
|
418
|
+
]
|
|
355
419
|
```
|
|
356
420
|
|
|
357
|
-
|
|
421
|
+
Remember to add `__init__.py` to your components directory, so that Django can find the `urls.py` file.
|
|
358
422
|
|
|
359
|
-
|
|
423
|
+
Finally, include the component's urls in your project's `urls.py` file:
|
|
424
|
+
|
|
425
|
+
```python
|
|
426
|
+
# In a file called [project root]/urls.py
|
|
427
|
+
from django.urls import include, path
|
|
428
|
+
|
|
429
|
+
urlpatterns = [
|
|
430
|
+
path("components/", include("components.urls")),
|
|
431
|
+
]
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
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.
|
|
435
|
+
|
|
436
|
+
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).
|
|
437
|
+
|
|
438
|
+
## Autodiscovery
|
|
439
|
+
|
|
440
|
+
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`).
|
|
441
|
+
|
|
442
|
+
Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
|
|
443
|
+
|
|
444
|
+
If you are using autodiscovery, keep a few points in mind:
|
|
445
|
+
|
|
446
|
+
- Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
|
|
447
|
+
- Components inside the auto-imported files still need to be registered with `@component.register()`
|
|
448
|
+
- 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).
|
|
449
|
+
|
|
450
|
+
Autodiscovery can be disabled via in the [settings](#disable-autodiscovery).
|
|
360
451
|
|
|
361
452
|
## Using slots in templates
|
|
362
453
|
|
|
@@ -372,6 +463,7 @@ _New in version 0.26_:
|
|
|
372
463
|
Components support something called 'slots'.
|
|
373
464
|
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
465
|
This mechanism makes components more reusable and composable.
|
|
466
|
+
This behavior is similar to [slots in Vue](https://vuejs.org/guide/components/slots.html).
|
|
375
467
|
|
|
376
468
|
In the example below we introduce two block tags that work hand in hand to make this work. These are...
|
|
377
469
|
|
|
@@ -399,7 +491,7 @@ When using the component, you specify which slots you want to fill and where you
|
|
|
399
491
|
{% endcomponent %}
|
|
400
492
|
```
|
|
401
493
|
|
|
402
|
-
Since the header
|
|
494
|
+
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
495
|
|
|
404
496
|
```htmldjango
|
|
405
497
|
<div class="calendar-component">
|
|
@@ -412,6 +504,10 @@ Since the header block is unspecified, it's taken from the base template. If you
|
|
|
412
504
|
</div>
|
|
413
505
|
```
|
|
414
506
|
|
|
507
|
+
### Default slot
|
|
508
|
+
|
|
509
|
+
_Added in version 0.28_
|
|
510
|
+
|
|
415
511
|
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
512
|
|
|
417
513
|
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 +580,88 @@ This is fine too:
|
|
|
484
580
|
{% endcomponent %}
|
|
485
581
|
```
|
|
486
582
|
|
|
487
|
-
###
|
|
583
|
+
### Render fill in multiple places
|
|
488
584
|
|
|
489
|
-
|
|
585
|
+
_Added in version 0.70_
|
|
490
586
|
|
|
491
|
-
|
|
587
|
+
You can render the same content in multiple places by defining multiple slots with
|
|
588
|
+
identical names:
|
|
492
589
|
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
590
|
+
```htmldjango
|
|
591
|
+
<div class="calendar-component">
|
|
592
|
+
<div class="header">
|
|
593
|
+
{% slot "image" %}Image here{% endslot %}
|
|
594
|
+
</div>
|
|
595
|
+
<div class="body">
|
|
596
|
+
{% slot "image" %}Image here{% endslot %}
|
|
597
|
+
</div>
|
|
598
|
+
</div>
|
|
599
|
+
```
|
|
500
600
|
|
|
501
|
-
|
|
502
|
-
class Calendar(component.Component):
|
|
601
|
+
So if used like:
|
|
503
602
|
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
Today's date is <span>{{ date }}</span>
|
|
511
|
-
</div>
|
|
512
|
-
</div>
|
|
513
|
-
"""
|
|
514
|
-
|
|
515
|
-
def get(self, request, *args, **kwargs):
|
|
516
|
-
context = {
|
|
517
|
-
"date": request.GET.get("date", "2020-06-06"),
|
|
518
|
-
}
|
|
519
|
-
slots = {
|
|
520
|
-
"header": "Calendar header",
|
|
521
|
-
}
|
|
522
|
-
return self.render_to_response(context, slots)
|
|
603
|
+
```htmldjango
|
|
604
|
+
{% component "calendar" date="2020-06-06" %}
|
|
605
|
+
{% fill "image" %}
|
|
606
|
+
<img src="..." />
|
|
607
|
+
{% endfill %}
|
|
608
|
+
{% endcomponent %}
|
|
523
609
|
```
|
|
524
610
|
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
```python
|
|
528
|
-
# In a file called [project root]/components/urls.py
|
|
529
|
-
from django.urls import path
|
|
530
|
-
from components.calendar.calendar import Calendar
|
|
611
|
+
This renders:
|
|
531
612
|
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
613
|
+
```htmldjango
|
|
614
|
+
<div class="calendar-component">
|
|
615
|
+
<div class="header">
|
|
616
|
+
<img src="..." />
|
|
617
|
+
</div>
|
|
618
|
+
<div class="body">
|
|
619
|
+
<img src="..." />
|
|
620
|
+
</div>
|
|
621
|
+
</div>
|
|
535
622
|
```
|
|
536
623
|
|
|
537
|
-
|
|
624
|
+
#### Default and required slots
|
|
538
625
|
|
|
539
|
-
|
|
626
|
+
If you use a slot multiple times, you can still mark the slot as `default` or `required`.
|
|
627
|
+
For that, you must mark ONLY ONE of the identical slots.
|
|
540
628
|
|
|
541
|
-
|
|
542
|
-
# In a file called [project root]/urls.py
|
|
543
|
-
from django.urls import include, path
|
|
629
|
+
We recommend to mark the first occurence for consistency, e.g.:
|
|
544
630
|
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
631
|
+
```htmldjango
|
|
632
|
+
<div class="calendar-component">
|
|
633
|
+
<div class="header">
|
|
634
|
+
{% slot "image" default required %}Image here{% endslot %}
|
|
635
|
+
</div>
|
|
636
|
+
<div class="body">
|
|
637
|
+
{% slot "image" %}Image here{% endslot %}
|
|
638
|
+
</div>
|
|
639
|
+
</div>
|
|
548
640
|
```
|
|
549
641
|
|
|
550
|
-
|
|
642
|
+
Which you can then use are regular default slot:
|
|
551
643
|
|
|
552
|
-
|
|
644
|
+
```htmldjango
|
|
645
|
+
{% component "calendar" date="2020-06-06" %}
|
|
646
|
+
<img src="..." />
|
|
647
|
+
{% endcomponent %}
|
|
648
|
+
```
|
|
553
649
|
|
|
554
|
-
###
|
|
650
|
+
### Accessing original content of slots
|
|
555
651
|
|
|
556
|
-
|
|
652
|
+
_Added in version 0.26_
|
|
557
653
|
|
|
558
654
|
Certain properties of a slot can be accessed from within a 'fill' context. They are provided as attributes on a user-defined alias of the targeted slot. For instance, let's say you're filling a slot called 'body'. To access properties of this slot, alias it using the 'as' keyword to a new name -- or keep the original name. With the new slot alias, you can call `<alias>.default` to insert the default content.
|
|
559
655
|
|
|
656
|
+
Notice the use of `as "body"` below:
|
|
657
|
+
|
|
560
658
|
```htmldjango
|
|
561
659
|
{% component "calendar" date="2020-06-06" %}
|
|
562
660
|
{% fill "body" as "body" %}{{ body.default }}. Have a great day!{% endfill %}
|
|
563
661
|
{% endcomponent %}
|
|
564
662
|
```
|
|
565
663
|
|
|
566
|
-
|
|
664
|
+
This produces:
|
|
567
665
|
|
|
568
666
|
```htmldjango
|
|
569
667
|
<div class="calendar-component">
|
|
@@ -576,7 +674,7 @@ Produces:
|
|
|
576
674
|
</div>
|
|
577
675
|
```
|
|
578
676
|
|
|
579
|
-
|
|
677
|
+
### Conditional slots
|
|
580
678
|
|
|
581
679
|
_Added in version 0.26._
|
|
582
680
|
|
|
@@ -662,7 +760,7 @@ To negate the meaning of `component_vars.is_filled`, simply treat it as boolean
|
|
|
662
760
|
{% endif %}
|
|
663
761
|
```
|
|
664
762
|
|
|
665
|
-
|
|
763
|
+
#### Accessing `is_filled` of slot names with special characters
|
|
666
764
|
|
|
667
765
|
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
766
|
|
|
@@ -670,27 +768,103 @@ However, you can still define slots with other special characters. In such case,
|
|
|
670
768
|
|
|
671
769
|
So a slot named `"my super-slot :)"` will be available as `component_vars.is_filled.my_super_slot___`.
|
|
672
770
|
|
|
673
|
-
###
|
|
771
|
+
### Scoped slots
|
|
674
772
|
|
|
675
|
-
|
|
773
|
+
_Added in version 0.76_:
|
|
676
774
|
|
|
677
|
-
|
|
775
|
+
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
776
|
|
|
679
|
-
```
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
777
|
+
```py
|
|
778
|
+
@component.register("my_comp")
|
|
779
|
+
class MyComp(component.Component):
|
|
780
|
+
template = """
|
|
781
|
+
<div>
|
|
782
|
+
{% slot "content" default %}
|
|
783
|
+
input: {{ input }}
|
|
784
|
+
{% endslot %}
|
|
785
|
+
</div>
|
|
786
|
+
"""
|
|
787
|
+
|
|
788
|
+
def get_context_data(self, input):
|
|
789
|
+
processed_input = do_something(input)
|
|
790
|
+
return {"input": processed_input}
|
|
685
791
|
```
|
|
686
792
|
|
|
687
|
-
|
|
793
|
+
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
794
|
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
795
|
+
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).
|
|
796
|
+
|
|
797
|
+
Using scoped slots consists of two steps:
|
|
798
|
+
|
|
799
|
+
1. Passing data to `slot` tag
|
|
800
|
+
2. Accessing data in `fill` tag
|
|
801
|
+
|
|
802
|
+
#### Passing data to slots
|
|
803
|
+
|
|
804
|
+
To pass the data to the `slot` tag, simply pass them as keyword attributes (`key=value`):
|
|
805
|
+
|
|
806
|
+
```py
|
|
807
|
+
@component.register("my_comp")
|
|
808
|
+
class MyComp(component.Component):
|
|
809
|
+
template = """
|
|
810
|
+
<div>
|
|
811
|
+
{% slot "content" default input=input %}
|
|
812
|
+
input: {{ input }}
|
|
813
|
+
{% endslot %}
|
|
814
|
+
</div>
|
|
815
|
+
"""
|
|
816
|
+
|
|
817
|
+
def get_context_data(self, input):
|
|
818
|
+
processed_input = do_something(input)
|
|
819
|
+
return {
|
|
820
|
+
"input": processed_input,
|
|
821
|
+
}
|
|
822
|
+
```
|
|
823
|
+
|
|
824
|
+
#### Accessing slot data in fill
|
|
825
|
+
|
|
826
|
+
Next, we head over to where we define a fill for this slot. Here, to access the slot data
|
|
827
|
+
we set the `data` attribute to the name of the variable through which we want to access
|
|
828
|
+
the slot data. In the example below, we set it to `data`:
|
|
829
|
+
|
|
830
|
+
```django
|
|
831
|
+
{% component "my_comp" %}
|
|
832
|
+
{% fill "content" data="data" %}
|
|
833
|
+
{{ data.input }}
|
|
834
|
+
{% endfill %}
|
|
835
|
+
{% endcomponent %}
|
|
836
|
+
```
|
|
837
|
+
|
|
838
|
+
To access slot data on a default slot, you have to explictly define the `{% fill %}` tags.
|
|
839
|
+
|
|
840
|
+
So this works:
|
|
841
|
+
|
|
842
|
+
```django
|
|
843
|
+
{% component "my_comp" %}
|
|
844
|
+
{% fill "content" data="data" %}
|
|
845
|
+
{{ data.input }}
|
|
846
|
+
{% endfill %}
|
|
847
|
+
{% endcomponent %}
|
|
848
|
+
```
|
|
849
|
+
|
|
850
|
+
While this does not:
|
|
851
|
+
|
|
852
|
+
```django
|
|
853
|
+
{% component "my_comp" data="data" %}
|
|
854
|
+
{{ data.input }}
|
|
855
|
+
{% endcomponent %}
|
|
856
|
+
```
|
|
857
|
+
|
|
858
|
+
Note: You cannot set the `data` attribute and
|
|
859
|
+
[slot alias (`as var` syntax)](#accessing-original-content-of-slots)
|
|
860
|
+
to the same name. This raises an error:
|
|
861
|
+
|
|
862
|
+
```django
|
|
863
|
+
{% component "my_comp" %}
|
|
864
|
+
{% fill "content" data="slot_var" as "slot_var" %}
|
|
865
|
+
{{ slot_var.input }}
|
|
866
|
+
{% endfill %}
|
|
867
|
+
{% endcomponent %}
|
|
694
868
|
```
|
|
695
869
|
|
|
696
870
|
## Passing data to components
|
|
@@ -801,7 +975,7 @@ Sweet! Now all the relevant HTML is inside the template, and we can move it to a
|
|
|
801
975
|
```
|
|
802
976
|
|
|
803
977
|
> Note: It is NOT possible to define nested dictionaries, so
|
|
804
|
-
`attrs:my_key:two=2` would be interpreted as:
|
|
978
|
+
> `attrs:my_key:two=2` would be interpreted as:
|
|
805
979
|
>
|
|
806
980
|
> ```py
|
|
807
981
|
> {"attrs": {"my_key:two": 2}}
|
|
@@ -931,6 +1105,7 @@ We can achieve this by adding extra kwargs. These values
|
|
|
931
1105
|
will be appended, instead of overwriting the previous value.
|
|
932
1106
|
|
|
933
1107
|
So if we have a variable `attrs`:
|
|
1108
|
+
|
|
934
1109
|
```py
|
|
935
1110
|
attrs = {
|
|
936
1111
|
"class": "my-class pa-4",
|
|
@@ -962,19 +1137,20 @@ To simplify merging of variables, you can supply the same key multiple times, an
|
|
|
962
1137
|
Renders:
|
|
963
1138
|
|
|
964
1139
|
```html
|
|
965
|
-
<div
|
|
966
|
-
|
|
1140
|
+
<div
|
|
1141
|
+
data-value="my-class pa-4 some-class another-class class-from-var text-red"
|
|
1142
|
+
></div>
|
|
967
1143
|
```
|
|
968
1144
|
|
|
969
1145
|
### Rules for `html_attrs`
|
|
970
1146
|
|
|
971
1147
|
1. Both `attrs` and `defaults` can be passed as positional args
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
1148
|
+
|
|
1149
|
+
`{% html_attrs attrs defaults key=val %}`
|
|
1150
|
+
|
|
1151
|
+
or as kwargs
|
|
1152
|
+
|
|
1153
|
+
`{% html_attrs key=val defaults=defaults attrs=attrs %}`
|
|
978
1154
|
|
|
979
1155
|
2. Both `attrs` and `defaults` are optional (can be omitted)
|
|
980
1156
|
|
|
@@ -1003,64 +1179,64 @@ defaults = {
|
|
|
1003
1179
|
Then:
|
|
1004
1180
|
|
|
1005
1181
|
- Empty tag <br/>
|
|
1006
|
-
|
|
1182
|
+
`{% html_attr %}`
|
|
1007
1183
|
|
|
1008
|
-
|
|
1009
|
-
|
|
1184
|
+
renders (empty string): <br/>
|
|
1185
|
+
` `
|
|
1010
1186
|
|
|
1011
1187
|
- Only kwargs <br/>
|
|
1012
|
-
|
|
1188
|
+
`{% html_attr class="some-class" class=class_from_var data-id="123" %}`
|
|
1013
1189
|
|
|
1014
|
-
|
|
1015
|
-
|
|
1190
|
+
renders: <br/>
|
|
1191
|
+
`class="some-class from-var" data-id="123"`
|
|
1016
1192
|
|
|
1017
1193
|
- Only attrs <br/>
|
|
1018
|
-
|
|
1194
|
+
`{% html_attr attrs %}`
|
|
1019
1195
|
|
|
1020
|
-
|
|
1021
|
-
|
|
1196
|
+
renders: <br/>
|
|
1197
|
+
`class="from-attrs" type="submit"`
|
|
1022
1198
|
|
|
1023
1199
|
- Attrs as kwarg <br/>
|
|
1024
|
-
|
|
1200
|
+
`{% html_attr attrs=attrs %}`
|
|
1025
1201
|
|
|
1026
|
-
|
|
1027
|
-
|
|
1202
|
+
renders: <br/>
|
|
1203
|
+
`class="from-attrs" type="submit"`
|
|
1028
1204
|
|
|
1029
1205
|
- Only defaults (as kwarg) <br/>
|
|
1030
|
-
|
|
1206
|
+
`{% html_attr defaults=defaults %}`
|
|
1031
1207
|
|
|
1032
|
-
|
|
1033
|
-
|
|
1208
|
+
renders: <br/>
|
|
1209
|
+
`class="from-defaults" role="button"`
|
|
1034
1210
|
|
|
1035
1211
|
- Attrs using the `prefix:key=value` construct <br/>
|
|
1036
|
-
|
|
1212
|
+
`{% html_attr attrs:class="from-attrs" attrs:type="submit" %}`
|
|
1037
1213
|
|
|
1038
|
-
|
|
1039
|
-
|
|
1214
|
+
renders: <br/>
|
|
1215
|
+
`class="from-attrs" type="submit"`
|
|
1040
1216
|
|
|
1041
1217
|
- Defaults using the `prefix:key=value` construct <br/>
|
|
1042
|
-
|
|
1218
|
+
`{% html_attr defaults:class="from-defaults" %}`
|
|
1043
1219
|
|
|
1044
|
-
|
|
1045
|
-
|
|
1220
|
+
renders: <br/>
|
|
1221
|
+
`class="from-defaults" role="button"`
|
|
1046
1222
|
|
|
1047
1223
|
- All together (1) - attrs and defaults as positional args: <br/>
|
|
1048
|
-
|
|
1224
|
+
`{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}`
|
|
1049
1225
|
|
|
1050
|
-
|
|
1051
|
-
|
|
1226
|
+
renders: <br/>
|
|
1227
|
+
`class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
|
|
1052
1228
|
|
|
1053
1229
|
- All together (2) - attrs and defaults as kwargs args: <br/>
|
|
1054
|
-
|
|
1230
|
+
`{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}`
|
|
1055
1231
|
|
|
1056
|
-
|
|
1057
|
-
|
|
1232
|
+
renders: <br/>
|
|
1233
|
+
`class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
|
|
1058
1234
|
|
|
1059
1235
|
- All together (3) - mixed: <br/>
|
|
1060
|
-
|
|
1236
|
+
`{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}`
|
|
1061
1237
|
|
|
1062
|
-
|
|
1063
|
-
|
|
1238
|
+
renders: <br/>
|
|
1239
|
+
`class="from-attrs added_class from-var" type="submit" data-id=123`
|
|
1064
1240
|
|
|
1065
1241
|
### Full example for `html_attrs`
|
|
1066
1242
|
|
|
@@ -1156,14 +1332,16 @@ attrs = {
|
|
|
1156
1332
|
will be merged.
|
|
1157
1333
|
|
|
1158
1334
|
So in the end `MyComp` will render:
|
|
1335
|
+
|
|
1159
1336
|
```html
|
|
1160
1337
|
<div
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1338
|
+
class="pa-0 border-solid my-comp-date extra-class"
|
|
1339
|
+
data-id="123"
|
|
1340
|
+
data-json='{"value": 456}'
|
|
1341
|
+
@click="(e) => onClick(e, 'from_parent')"
|
|
1165
1342
|
>
|
|
1166
|
-
|
|
1343
|
+
...
|
|
1344
|
+
</div>
|
|
1167
1345
|
```
|
|
1168
1346
|
|
|
1169
1347
|
### Rendering HTML attributes outside of templates
|
|
@@ -1199,6 +1377,40 @@ NOTE: `{% csrf_token %}` tags need access to the top-level context, and they wil
|
|
|
1199
1377
|
|
|
1200
1378
|
Components can also access the outer context in their context methods by accessing the property `outer_context`.
|
|
1201
1379
|
|
|
1380
|
+
## Rendering JS and CSS dependencies
|
|
1381
|
+
|
|
1382
|
+
The JS and CSS files included in components are not automatically rendered.
|
|
1383
|
+
Instead, use the following tags to specify where to render the dependencies:
|
|
1384
|
+
- `component_dependencies` - Renders both JS and CSS
|
|
1385
|
+
- `component_js_dependencies` - Renders only JS
|
|
1386
|
+
- `component_css_dependencies` - Reneders only CSS
|
|
1387
|
+
|
|
1388
|
+
JS files are rendered as `<script>` tags.<br/>
|
|
1389
|
+
CSS files are rendered as `<style>` tags.
|
|
1390
|
+
|
|
1391
|
+
### Setting Up `ComponentDependencyMiddleware`
|
|
1392
|
+
|
|
1393
|
+
`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.
|
|
1394
|
+
|
|
1395
|
+
To set it up, add the middleware to your `MIDDLEWARE` in settings.py:
|
|
1396
|
+
|
|
1397
|
+
```python
|
|
1398
|
+
MIDDLEWARE = [
|
|
1399
|
+
# ... other middleware classes ...
|
|
1400
|
+
'django_components.middleware.ComponentDependencyMiddleware'
|
|
1401
|
+
# ... other middleware classes ...
|
|
1402
|
+
]
|
|
1403
|
+
```
|
|
1404
|
+
|
|
1405
|
+
Then, enable `RENDER_DEPENDENCIES` in setting.py:
|
|
1406
|
+
|
|
1407
|
+
```python
|
|
1408
|
+
COMPONENTS = {
|
|
1409
|
+
"RENDER_DEPENDENCIES": True,
|
|
1410
|
+
# ... other component settings ...
|
|
1411
|
+
}
|
|
1412
|
+
```
|
|
1413
|
+
|
|
1202
1414
|
## Available settings
|
|
1203
1415
|
|
|
1204
1416
|
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.
|