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.
Files changed (47) hide show
  1. {django_components-0.75/src/django_components.egg-info → django_components-0.77}/PKG-INFO +379 -148
  2. {django_components-0.75 → django_components-0.77}/README.md +378 -147
  3. {django_components-0.75 → django_components-0.77}/pyproject.toml +1 -1
  4. {django_components-0.75 → django_components-0.77}/src/django_components/component.py +13 -21
  5. django_components-0.77/src/django_components/expression.py +46 -0
  6. {django_components-0.75 → django_components-0.77}/src/django_components/slots.py +74 -33
  7. {django_components-0.75 → django_components-0.77}/src/django_components/templatetags/component_tags.py +134 -72
  8. {django_components-0.75 → django_components-0.77/src/django_components.egg-info}/PKG-INFO +379 -148
  9. {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/SOURCES.txt +1 -0
  10. {django_components-0.75 → django_components-0.77}/tests/test_template_parser.py +3 -3
  11. {django_components-0.75 → django_components-0.77}/tests/test_templatetags.py +332 -27
  12. {django_components-0.75 → django_components-0.77}/LICENSE +0 -0
  13. {django_components-0.75 → django_components-0.77}/setup.cfg +0 -0
  14. {django_components-0.75 → django_components-0.77}/src/django_components/__init__.py +0 -0
  15. {django_components-0.75 → django_components-0.77}/src/django_components/app_settings.py +0 -0
  16. {django_components-0.75 → django_components-0.77}/src/django_components/apps.py +0 -0
  17. {django_components-0.75 → django_components-0.77}/src/django_components/attributes.py +0 -0
  18. {django_components-0.75 → django_components-0.77}/src/django_components/component_registry.py +0 -0
  19. {django_components-0.75 → django_components-0.77}/src/django_components/context.py +0 -0
  20. {django_components-0.75 → django_components-0.77}/src/django_components/logger.py +0 -0
  21. {django_components-0.75 → django_components-0.77}/src/django_components/management/__init__.py +0 -0
  22. {django_components-0.75 → django_components-0.77}/src/django_components/management/commands/__init__.py +0 -0
  23. {django_components-0.75 → django_components-0.77}/src/django_components/management/commands/startcomponent.py +0 -0
  24. {django_components-0.75 → django_components-0.77}/src/django_components/management/commands/upgradecomponent.py +0 -0
  25. {django_components-0.75 → django_components-0.77}/src/django_components/middleware.py +0 -0
  26. {django_components-0.75 → django_components-0.77}/src/django_components/node.py +0 -0
  27. {django_components-0.75 → django_components-0.77}/src/django_components/py.typed +0 -0
  28. {django_components-0.75 → django_components-0.77}/src/django_components/safer_staticfiles/__init__.py +0 -0
  29. {django_components-0.75 → django_components-0.77}/src/django_components/safer_staticfiles/apps.py +0 -0
  30. {django_components-0.75 → django_components-0.77}/src/django_components/template_loader.py +0 -0
  31. {django_components-0.75 → django_components-0.77}/src/django_components/template_parser.py +0 -0
  32. {django_components-0.75 → django_components-0.77}/src/django_components/templatetags/__init__.py +0 -0
  33. {django_components-0.75 → django_components-0.77}/src/django_components/types.py +0 -0
  34. {django_components-0.75 → django_components-0.77}/src/django_components/utils.py +0 -0
  35. {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/dependency_links.txt +0 -0
  36. {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/requires.txt +0 -0
  37. {django_components-0.75 → django_components-0.77}/src/django_components.egg-info/top_level.txt +0 -0
  38. {django_components-0.75 → django_components-0.77}/tests/test_attributes.py +0 -0
  39. {django_components-0.75 → django_components-0.77}/tests/test_autodiscover.py +0 -0
  40. {django_components-0.75 → django_components-0.77}/tests/test_component.py +0 -0
  41. {django_components-0.75 → django_components-0.77}/tests/test_component_as_view.py +0 -0
  42. {django_components-0.75 → django_components-0.77}/tests/test_context.py +0 -0
  43. {django_components-0.75 → django_components-0.77}/tests/test_dependency_rendering.py +0 -0
  44. {django_components-0.75 → django_components-0.77}/tests/test_registry.py +0 -0
  45. {django_components-0.75 → django_components-0.77}/tests/test_settings.py +0 -0
  46. {django_components-0.75 → django_components-0.77}/tests/test_startcomponent_command.py +0 -0
  47. {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.75
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
- ## Autodiscovery
294
+ ## Using single-file components
265
295
 
266
- 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`).
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
- Autodiscovery occurs when Django is loaded, during the `ready` hook of the `apps.py` file.
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
- If you are using autodiscovery, keep a few points in mind:
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
- - Avoid defining any logic on the module-level inside the `components` dir, that you would not want to run anyway.
273
- - Components inside the auto-imported files still need to be registered with `@component.register()`
274
- - 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).
310
+ template: t.django_html = """
311
+ <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
312
+ """
275
313
 
276
- Autodiscovery can be disabled via in the [settings](#disable-autodiscovery).
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
- ## Using single-file components
377
+ ## Use components as views
324
378
 
325
- 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:
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: t.django_html = """
340
- <div class="calendar-component">Today's date is <span>{{ date }}</span></div>
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
- css: t.css = """
344
- .calendar-component { width: 200px; background: pink; }
345
- .calendar-component span { font-weight: bold; }
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
- js: t.js = """
349
- (function(){
350
- if (document.querySelector(".calendar-component")) {
351
- document.querySelector(".calendar-component").onclick = function(){ alert("Clicked calendar!"); };
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
- This makes it easy to create small components without having to create a separate template, CSS, and JS file.
427
+ Remember to add `__init__.py` to your components directory, so that Django can find the `urls.py` file.
358
428
 
359
- 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.
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 block 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:
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
- ### Components as views
589
+ ### Render fill in multiple places
488
590
 
489
- _New in version 0.34_
591
+ _Added in version 0.70_
490
592
 
491
- 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.
593
+ You can render the same content in multiple places by defining multiple slots with
594
+ identical names:
492
595
 
493
- 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.
494
-
495
- Here's an example of a calendar component defined as a view:
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
- ```python
498
- # In a file called [project root]/components/calendar.py
499
- from django_components import component
607
+ So if used like:
500
608
 
501
- @component.register("calendar")
502
- class Calendar(component.Component):
609
+ ```htmldjango
610
+ {% component "calendar" date="2020-06-06" %}
611
+ {% fill "image" %}
612
+ <img src="..." />
613
+ {% endfill %}
614
+ {% endcomponent %}
615
+ ```
503
616
 
504
- template = """
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
- 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)
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
- 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:
630
+ #### Default and required slots
526
631
 
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
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
- urlpatterns = [
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
- Finally, include the component's urls in your project's `urls.py` file:
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
- ```python
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
- urlpatterns = [
546
- path("components/", include("components.urls")),
547
- ]
650
+ ```htmldjango
651
+ {% component "calendar" date="2020-06-06" %}
652
+ <img src="..." />
653
+ {% endcomponent %}
548
654
  ```
549
655
 
550
- 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.
656
+ ### Accessing original content of slots
551
657
 
552
- 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).
658
+ _Added in version 0.26_
553
659
 
554
- ### Advanced
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
- #### Re-using content defined in the original slot
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
- 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.
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" as "body" %}{{ body.default }}. Have a great day!{% endfill %}
677
+ {% fill "body" default="body_default" %}
678
+ {{ body_default }}. Have a great day!
679
+ {% endfill %}
563
680
  {% endcomponent %}
564
681
  ```
565
682
 
566
- Produces:
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
- #### Conditional slots
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
- **Accessing slot names with special characters**
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
- ### Setting Up `ComponentDependencyMiddleware`
790
+ ### Scoped slots
674
791
 
675
- `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.
792
+ _Added in version 0.76_:
676
793
 
677
- To set it up, add the middleware to your `MIDDLEWARE` in settings.py:
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
- ```python
680
- MIDDLEWARE = [
681
- # ... other middleware classes ...
682
- 'django_components.middleware.ComponentDependencyMiddleware'
683
- # ... other middleware classes ...
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
- Then, enable `RENDER_DEPENDENCIES` in setting.py:
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
- ```python
690
- COMPONENTS = {
691
- "RENDER_DEPENDENCIES": True,
692
- # ... other component settings ...
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 data-value="my-class pa-4 some-class another-class class-from-var text-red">
966
- </div>
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
- `{% html_attrs attrs defaults key=val %}`
974
-
975
- or as kwargs
976
-
977
- `{% html_attrs key=val defaults=defaults attrs=attrs %}`
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
- `{% html_attr %}`
1201
+ `{% html_attr %}`
1007
1202
 
1008
- renders (empty string): <br/>
1009
- ` `
1203
+ renders (empty string): <br/>
1204
+ ` `
1010
1205
 
1011
1206
  - Only kwargs <br/>
1012
- `{% html_attr class="some-class" class=class_from_var data-id="123" %}`
1207
+ `{% html_attr class="some-class" class=class_from_var data-id="123" %}`
1013
1208
 
1014
- renders: <br/>
1015
- `class="some-class from-var" data-id="123"`
1209
+ renders: <br/>
1210
+ `class="some-class from-var" data-id="123"`
1016
1211
 
1017
1212
  - Only attrs <br/>
1018
- `{% html_attr attrs %}`
1213
+ `{% html_attr attrs %}`
1019
1214
 
1020
- renders: <br/>
1021
- `class="from-attrs" type="submit"`
1215
+ renders: <br/>
1216
+ `class="from-attrs" type="submit"`
1022
1217
 
1023
1218
  - Attrs as kwarg <br/>
1024
- `{% html_attr attrs=attrs %}`
1219
+ `{% html_attr attrs=attrs %}`
1025
1220
 
1026
- renders: <br/>
1027
- `class="from-attrs" type="submit"`
1221
+ renders: <br/>
1222
+ `class="from-attrs" type="submit"`
1028
1223
 
1029
1224
  - Only defaults (as kwarg) <br/>
1030
- `{% html_attr defaults=defaults %}`
1225
+ `{% html_attr defaults=defaults %}`
1031
1226
 
1032
- renders: <br/>
1033
- `class="from-defaults" role="button"`
1227
+ renders: <br/>
1228
+ `class="from-defaults" role="button"`
1034
1229
 
1035
1230
  - Attrs using the `prefix:key=value` construct <br/>
1036
- `{% html_attr attrs:class="from-attrs" attrs:type="submit" %}`
1231
+ `{% html_attr attrs:class="from-attrs" attrs:type="submit" %}`
1037
1232
 
1038
- renders: <br/>
1039
- `class="from-attrs" type="submit"`
1233
+ renders: <br/>
1234
+ `class="from-attrs" type="submit"`
1040
1235
 
1041
1236
  - Defaults using the `prefix:key=value` construct <br/>
1042
- `{% html_attr defaults:class="from-defaults" %}`
1237
+ `{% html_attr defaults:class="from-defaults" %}`
1043
1238
 
1044
- renders: <br/>
1045
- `class="from-defaults" role="button"`
1239
+ renders: <br/>
1240
+ `class="from-defaults" role="button"`
1046
1241
 
1047
1242
  - All together (1) - attrs and defaults as positional args: <br/>
1048
- `{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}`
1243
+ `{% html_attrs attrs defaults class="added_class" class=class_from_var data-id=123 %}`
1049
1244
 
1050
- renders: <br/>
1051
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
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
- `{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}`
1249
+ `{% html_attrs class="added_class" class=class_from_var data-id=123 attrs=attrs defaults=defaults %}`
1055
1250
 
1056
- renders: <br/>
1057
- `class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
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
- `{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}`
1255
+ `{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}`
1061
1256
 
1062
- renders: <br/>
1063
- `class="from-attrs added_class from-var" type="submit" data-id=123`
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
- class="pa-0 border-solid my-comp-date extra-class"
1162
- data-id="123"
1163
- data-json='{"value": 456}'
1164
- @click="(e) => onClick(e, 'from_parent')"
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.