django-components 0.94__tar.gz → 0.96__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.94/src/django_components.egg-info → django_components-0.96}/PKG-INFO +352 -56
- {django_components-0.94 → django_components-0.96}/README.md +351 -55
- {django_components-0.94 → django_components-0.96}/pyproject.toml +1 -1
- {django_components-0.94 → django_components-0.96}/src/django_components/__init__.py +5 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/app_settings.py +5 -1
- {django_components-0.94 → django_components-0.96}/src/django_components/apps.py +17 -12
- {django_components-0.94 → django_components-0.96}/src/django_components/component.py +211 -29
- {django_components-0.94 → django_components-0.96}/src/django_components/component_registry.py +9 -1
- django_components-0.96/src/django_components/components/__init__.py +3 -0
- django_components-0.96/src/django_components/components/dynamic.py +89 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/slots.py +10 -2
- {django_components-0.94 → django_components-0.96}/src/django_components/types.py +14 -1
- django_components-0.96/src/django_components/utils.py +168 -0
- {django_components-0.94 → django_components-0.96/src/django_components.egg-info}/PKG-INFO +352 -56
- {django_components-0.94 → django_components-0.96}/src/django_components.egg-info/SOURCES.txt +2 -0
- {django_components-0.94 → django_components-0.96}/tests/test_component.py +577 -37
- {django_components-0.94 → django_components-0.96}/tests/test_context.py +50 -17
- {django_components-0.94 → django_components-0.96}/tests/test_templatetags_component.py +298 -14
- django_components-0.94/src/django_components/utils.py +0 -38
- {django_components-0.94 → django_components-0.96}/LICENSE +0 -0
- {django_components-0.94 → django_components-0.96}/setup.cfg +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/attributes.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/autodiscover.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/component_media.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/context.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/expression.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/library.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/logger.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/management/__init__.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/management/commands/__init__.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/management/commands/startcomponent.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/management/commands/upgradecomponent.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/middleware.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/node.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/provide.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/py.typed +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/safer_staticfiles/__init__.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/safer_staticfiles/apps.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/tag_formatter.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/template_loader.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/template_parser.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/templatetags/__init__.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components/templatetags/component_tags.py +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components.egg-info/dependency_links.txt +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components.egg-info/requires.txt +0 -0
- {django_components-0.94 → django_components-0.96}/src/django_components.egg-info/top_level.txt +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_attributes.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_autodiscover.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_command_startcomponent.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_component_as_view.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_component_media.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_dependency_rendering.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_expression.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_registry.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_safer_staticfiles.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_settings.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_tag_formatter.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_template_loader.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_template_parser.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_templatetags.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_templatetags_provide.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_templatetags_slot_fill.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_templatetags_templating.py +0 -0
- {django_components-0.94 → django_components-0.96}/tests/test_utils.py +0 -0
- {django_components-0.94 → django_components-0.96}/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.96
|
|
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
|
|
@@ -68,15 +68,19 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
68
68
|
- [Using single-file components](#using-single-file-components)
|
|
69
69
|
- [Use components in templates](#use-components-in-templates)
|
|
70
70
|
- [Use components outside of templates](#use-components-outside-of-templates)
|
|
71
|
-
- [Registering components](#registering-components)
|
|
72
71
|
- [Use components as views](#use-components-as-views)
|
|
72
|
+
- [Typing and validating components](#typing-and-validating-components)
|
|
73
|
+
- [Pre-defined components](#pre-defined-components)
|
|
74
|
+
- [Registering components](#registering-components)
|
|
73
75
|
- [Autodiscovery](#autodiscovery)
|
|
74
76
|
- [Using slots in templates](#using-slots-in-templates)
|
|
75
77
|
- [Accessing data passed to the component](#accessing-data-passed-to-the-component)
|
|
76
78
|
- [Rendering HTML attributes](#rendering-html-attributes)
|
|
77
79
|
- [Template tag syntax](#template-tag-syntax)
|
|
78
80
|
- [Prop drilling and dependency injection (provide / inject)](#prop-drilling-and-dependency-injection-provide--inject)
|
|
81
|
+
- [Component hooks](#component-hooks)
|
|
79
82
|
- [Component context and scope](#component-context-and-scope)
|
|
83
|
+
- [Pre-defined template variables](#pre-defined-template-variables)
|
|
80
84
|
- [Customizing component tags with TagFormatter](#customizing-component-tags-with-tagformatter)
|
|
81
85
|
- [Defining HTML/JS/CSS files](#defining-htmljscss-files)
|
|
82
86
|
- [Rendering JS/CSS dependencies](#rendering-jscss-dependencies)
|
|
@@ -91,6 +95,15 @@ And this is what gets rendered (plus the CSS and Javascript you've specified):
|
|
|
91
95
|
|
|
92
96
|
## Release notes
|
|
93
97
|
|
|
98
|
+
**Version 0.96**
|
|
99
|
+
- Run-time type validation for Python 3.11+ - If the `Component` class is typed, e.g. `Component[Args, Kwargs, ...]`, the args, kwargs, slots, and data are validated against the given types. (See [Runtime input validation with types](#runtime-input-validation-with-types))
|
|
100
|
+
- Render hooks - Set `on_render_before` and `on_render_after` methods on `Component` to intercept or modify the template or context before rendering, or the rendered result afterwards. (See [Component hooks](#component-hooks))
|
|
101
|
+
- `component_vars.is_filled` context variable can be accessed from within `on_render_before` and `on_render_after` hooks as `self.is_filled.my_slot`
|
|
102
|
+
|
|
103
|
+
**Version 0.95**
|
|
104
|
+
- Added support for dynamic components, where the component name is passed as a variable. (See [Dynamic components](#dynamic-components))
|
|
105
|
+
- Changed `Component.input` to raise `RuntimeError` if accessed outside of render context. Previously it returned `None` if unset.
|
|
106
|
+
|
|
94
107
|
**Version 0.94**
|
|
95
108
|
- django_components now automatically configures Django to support multi-line tags. (See [Multi-line tags](#multi-line-tags))
|
|
96
109
|
- New setting `reload_on_template_change`. Set this to `True` to reload the dev server on changes to component template files. (See [Reload dev server on component file changes](#reload-dev-server-on-component-file-changes))
|
|
@@ -651,58 +664,6 @@ MyComponent.render_to_response(
|
|
|
651
664
|
)
|
|
652
665
|
```
|
|
653
666
|
|
|
654
|
-
### Adding type hints with Generics
|
|
655
|
-
|
|
656
|
-
The `Component` class optionally accepts type parameters
|
|
657
|
-
that allow you to specify the types of args, kwargs, slots, and
|
|
658
|
-
data.
|
|
659
|
-
|
|
660
|
-
```py
|
|
661
|
-
from typing import NotRequired, Tuple, TypedDict, SlotFunc
|
|
662
|
-
|
|
663
|
-
# Positional inputs - Tuple
|
|
664
|
-
Args = Tuple[int, str]
|
|
665
|
-
|
|
666
|
-
# Kwargs inputs - Mapping
|
|
667
|
-
class Kwargs(TypedDict):
|
|
668
|
-
variable: str
|
|
669
|
-
another: int
|
|
670
|
-
maybe_var: NotRequired[int]
|
|
671
|
-
|
|
672
|
-
# Data returned from `get_context_data` - Mapping
|
|
673
|
-
class Data(TypedDict):
|
|
674
|
-
variable: str
|
|
675
|
-
|
|
676
|
-
# The data available to the `my_slot` scoped slot
|
|
677
|
-
class MySlotData(TypedDict):
|
|
678
|
-
value: int
|
|
679
|
-
|
|
680
|
-
# Slot functions - Mapping
|
|
681
|
-
class Slots(TypedDict):
|
|
682
|
-
# Use SlotFunc for slot functions.
|
|
683
|
-
# The generic specifies the `data` dictionary
|
|
684
|
-
my_slot: NotRequired[SlotFunc[MySlotData]]
|
|
685
|
-
|
|
686
|
-
class Button(Component[Args, Kwargs, Data, Slots]):
|
|
687
|
-
def get_context_data(self, variable, another):
|
|
688
|
-
return {
|
|
689
|
-
"variable": variable,
|
|
690
|
-
}
|
|
691
|
-
```
|
|
692
|
-
|
|
693
|
-
When you then call `Component.render` or `Component.render_to_response`, you will get type hints:
|
|
694
|
-
|
|
695
|
-
```py
|
|
696
|
-
Button.render(
|
|
697
|
-
# Error: First arg must be `int`, got `float`
|
|
698
|
-
args=(1.25, "abc"),
|
|
699
|
-
# Error: Key "another" is missing
|
|
700
|
-
kwargs={
|
|
701
|
-
"variable": "text",
|
|
702
|
-
},
|
|
703
|
-
)
|
|
704
|
-
```
|
|
705
|
-
|
|
706
667
|
### Response class of `render_to_response`
|
|
707
668
|
|
|
708
669
|
While `render` method returns a plain string, `render_to_response` wraps the rendered content in a "Response" class. By default, this is `django.http.HttpResponse`.
|
|
@@ -874,6 +835,230 @@ class MyComponent(Component):
|
|
|
874
835
|
do_something_extra(request, *args, **kwargs)
|
|
875
836
|
```
|
|
876
837
|
|
|
838
|
+
## Typing and validating components
|
|
839
|
+
|
|
840
|
+
### Adding type hints with Generics
|
|
841
|
+
|
|
842
|
+
_New in version 0.92_
|
|
843
|
+
|
|
844
|
+
The `Component` class optionally accepts type parameters
|
|
845
|
+
that allow you to specify the types of args, kwargs, slots, and
|
|
846
|
+
data:
|
|
847
|
+
|
|
848
|
+
```py
|
|
849
|
+
class Button(Component[Args, Kwargs, Data, Slots]):
|
|
850
|
+
...
|
|
851
|
+
```
|
|
852
|
+
|
|
853
|
+
- `Args` - Must be a `Tuple` or `Any`
|
|
854
|
+
- `Kwargs` - Must be a `TypedDict` or `Any`
|
|
855
|
+
- `Data` - Must be a `TypedDict` or `Any`
|
|
856
|
+
- `Slots` - Must be a `TypedDict` or `Any`
|
|
857
|
+
|
|
858
|
+
Here's a full example:
|
|
859
|
+
|
|
860
|
+
```py
|
|
861
|
+
from typing import NotRequired, Tuple, TypedDict, SlotContent, SlotFunc
|
|
862
|
+
|
|
863
|
+
# Positional inputs
|
|
864
|
+
Args = Tuple[int, str]
|
|
865
|
+
|
|
866
|
+
# Kwargs inputs
|
|
867
|
+
class Kwargs(TypedDict):
|
|
868
|
+
variable: str
|
|
869
|
+
another: int
|
|
870
|
+
maybe_var: NotRequired[int] # May be ommited
|
|
871
|
+
|
|
872
|
+
# Data returned from `get_context_data`
|
|
873
|
+
class Data(TypedDict):
|
|
874
|
+
variable: str
|
|
875
|
+
|
|
876
|
+
# The data available to the `my_slot` scoped slot
|
|
877
|
+
class MySlotData(TypedDict):
|
|
878
|
+
value: int
|
|
879
|
+
|
|
880
|
+
# Slots
|
|
881
|
+
class Slots(TypedDict):
|
|
882
|
+
# Use SlotFunc for slot functions.
|
|
883
|
+
# The generic specifies the `data` dictionary
|
|
884
|
+
my_slot: NotRequired[SlotFunc[MySlotData]]
|
|
885
|
+
# SlotContent == Union[str, SafeString]
|
|
886
|
+
another_slot: SlotContent
|
|
887
|
+
|
|
888
|
+
class Button(Component[Args, Kwargs, Data, Slots]):
|
|
889
|
+
def get_context_data(self, variable, another):
|
|
890
|
+
return {
|
|
891
|
+
"variable": variable,
|
|
892
|
+
}
|
|
893
|
+
```
|
|
894
|
+
|
|
895
|
+
When you then call `Component.render` or `Component.render_to_response`, you will get type hints:
|
|
896
|
+
|
|
897
|
+
```py
|
|
898
|
+
Button.render(
|
|
899
|
+
# Error: First arg must be `int`, got `float`
|
|
900
|
+
args=(1.25, "abc"),
|
|
901
|
+
# Error: Key "another" is missing
|
|
902
|
+
kwargs={
|
|
903
|
+
"variable": "text",
|
|
904
|
+
},
|
|
905
|
+
)
|
|
906
|
+
```
|
|
907
|
+
|
|
908
|
+
#### Usage for Python <3.11
|
|
909
|
+
|
|
910
|
+
On Python 3.8-3.10, use `typing_extensions`
|
|
911
|
+
|
|
912
|
+
```py
|
|
913
|
+
from typing_extensions import TypedDict, NotRequired
|
|
914
|
+
```
|
|
915
|
+
|
|
916
|
+
Additionally on Python 3.8-3.9, also import `annotations`:
|
|
917
|
+
|
|
918
|
+
```py
|
|
919
|
+
from __future__ import annotations
|
|
920
|
+
```
|
|
921
|
+
|
|
922
|
+
Moreover, on 3.10 and less, you may not be able to use `NotRequired`, and instead you will need to mark either all keys are required, or all keys as optional, using TypeDict's `total` kwarg.
|
|
923
|
+
|
|
924
|
+
[See PEP-655](https://peps.python.org/pep-0655) for more info.
|
|
925
|
+
|
|
926
|
+
|
|
927
|
+
### Passing additional args or kwargs
|
|
928
|
+
|
|
929
|
+
You may have a function that supports any number of args or kwargs:
|
|
930
|
+
|
|
931
|
+
```py
|
|
932
|
+
def get_context_data(self, *args, **kwargs):
|
|
933
|
+
...
|
|
934
|
+
```
|
|
935
|
+
|
|
936
|
+
This is not supported with the typed components.
|
|
937
|
+
|
|
938
|
+
As a workaround:
|
|
939
|
+
- For `*args`, set a positional argument that accepts a list of values:
|
|
940
|
+
|
|
941
|
+
```py
|
|
942
|
+
# Tuple of one member of list of strings
|
|
943
|
+
Args = Tuple[List[str]]
|
|
944
|
+
```
|
|
945
|
+
|
|
946
|
+
- For `*kwargs`, set a keyword argument that accepts a dictionary of values:
|
|
947
|
+
|
|
948
|
+
```py
|
|
949
|
+
class Kwargs(TypedDict):
|
|
950
|
+
variable: str
|
|
951
|
+
another: int
|
|
952
|
+
# Pass any extra keys under `extra`
|
|
953
|
+
extra: Dict[str, any]
|
|
954
|
+
```
|
|
955
|
+
|
|
956
|
+
### Handling no args or no kwargs
|
|
957
|
+
|
|
958
|
+
To declare that a component accepts no Args, Kwargs, etc, you can use `EmptyTuple` and `EmptyDict` types:
|
|
959
|
+
|
|
960
|
+
```py
|
|
961
|
+
from django_components import Component, EmptyDict, EmptyTuple
|
|
962
|
+
|
|
963
|
+
Args = EmptyTuple
|
|
964
|
+
Kwargs = Data = Slots = EmptyDict
|
|
965
|
+
|
|
966
|
+
class Button(Component[Args, Kwargs, Data, Slots]):
|
|
967
|
+
...
|
|
968
|
+
```
|
|
969
|
+
|
|
970
|
+
### Runtime input validation with types
|
|
971
|
+
|
|
972
|
+
_New in version 0.96_
|
|
973
|
+
|
|
974
|
+
> NOTE: Kwargs, slots, and data validation is supported only for Python >=3.11
|
|
975
|
+
|
|
976
|
+
In Python 3.11 and later, when you specify the component types, you will get also runtime validation of the inputs you pass to `Component.render` or `Component.render_to_response`.
|
|
977
|
+
|
|
978
|
+
So, using the example from before, if you ignored the type errors and still ran the following code:
|
|
979
|
+
|
|
980
|
+
```py
|
|
981
|
+
Button.render(
|
|
982
|
+
# Error: First arg must be `int`, got `float`
|
|
983
|
+
args=(1.25, "abc"),
|
|
984
|
+
# Error: Key "another" is missing
|
|
985
|
+
kwargs={
|
|
986
|
+
"variable": "text",
|
|
987
|
+
},
|
|
988
|
+
)
|
|
989
|
+
```
|
|
990
|
+
|
|
991
|
+
This would raise a `TypeError`:
|
|
992
|
+
|
|
993
|
+
```txt
|
|
994
|
+
Component 'Button' expected positional argument at index 0 to be <class 'int'>, got 1.25 of type <class 'float'>
|
|
995
|
+
```
|
|
996
|
+
|
|
997
|
+
In case you need to skip these errors, you can either set the faulty member to `Any`, e.g.:
|
|
998
|
+
|
|
999
|
+
```py
|
|
1000
|
+
# Changed `int` to `Any`
|
|
1001
|
+
Args = Tuple[Any, str]
|
|
1002
|
+
```
|
|
1003
|
+
|
|
1004
|
+
Or you can replace `Args` with `Any` altogether, to skip the validation of args:
|
|
1005
|
+
|
|
1006
|
+
```py
|
|
1007
|
+
# Replaced `Args` with `Any`
|
|
1008
|
+
class Button(Component[Any, Kwargs, Data, Slots]):
|
|
1009
|
+
...
|
|
1010
|
+
```
|
|
1011
|
+
|
|
1012
|
+
Same applies to kwargs, data, and slots.
|
|
1013
|
+
|
|
1014
|
+
## Pre-defined components
|
|
1015
|
+
|
|
1016
|
+
### Dynamic components
|
|
1017
|
+
|
|
1018
|
+
If you are writing something like a form component, you may design it such that users
|
|
1019
|
+
give you the component names, and your component renders it.
|
|
1020
|
+
|
|
1021
|
+
While you can handle this with a series of if / else statements, this is not an extensible solution.
|
|
1022
|
+
|
|
1023
|
+
Instead, you can use **dynamic components**. Dynamic components are used in place of normal components.
|
|
1024
|
+
|
|
1025
|
+
```django
|
|
1026
|
+
{% load component_tags %}
|
|
1027
|
+
{% component "dynamic" is=component_name title="Cat Museum" %}
|
|
1028
|
+
{% fill "content" %}
|
|
1029
|
+
HELLO_FROM_SLOT_1
|
|
1030
|
+
{% endfill %}
|
|
1031
|
+
{% fill "sidebar" %}
|
|
1032
|
+
HELLO_FROM_SLOT_2
|
|
1033
|
+
{% endfill %}
|
|
1034
|
+
{% endcomponent %}
|
|
1035
|
+
```
|
|
1036
|
+
|
|
1037
|
+
These behave same way as regular components. You pass it the same args, kwargs, and slots as you would
|
|
1038
|
+
to the component that you want to render.
|
|
1039
|
+
|
|
1040
|
+
The only exception is that also you supply 1-2 additional inputs:
|
|
1041
|
+
- `is` - Required - The component name or a component class to render
|
|
1042
|
+
- `registry` - Optional - The `ComponentRegistry` that will be searched if `is` is a component name. If omitted, ALL registries are searched.
|
|
1043
|
+
|
|
1044
|
+
By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict, you can change the name used for the dynamic components by defining the [`COMPONENTS.dynamic_component_name` setting](#dynamic_component_name).
|
|
1045
|
+
|
|
1046
|
+
If you need to use the dynamic components in Python, you can also import it from `django_components`:
|
|
1047
|
+
```py
|
|
1048
|
+
from django_components import DynamicComponent
|
|
1049
|
+
|
|
1050
|
+
comp = SimpleTableComp if is_readonly else TableComp
|
|
1051
|
+
|
|
1052
|
+
output = DynamicComponent.render(
|
|
1053
|
+
kwargs={
|
|
1054
|
+
"is": comp,
|
|
1055
|
+
# Other kwargs...
|
|
1056
|
+
},
|
|
1057
|
+
# args: [...],
|
|
1058
|
+
# slots: {...},
|
|
1059
|
+
)
|
|
1060
|
+
```
|
|
1061
|
+
|
|
877
1062
|
## Registering components
|
|
878
1063
|
|
|
879
1064
|
In previous examples you could repeatedly see us using `@register()` to "register"
|
|
@@ -1318,7 +1503,7 @@ This produces:
|
|
|
1318
1503
|
|
|
1319
1504
|
_Added in version 0.26._
|
|
1320
1505
|
|
|
1321
|
-
> NOTE: In version 0.70, `{% if_filled %}` tags were replaced with `{{ component_vars.is_filled }}` variables. If your slot name contained special characters, see the section
|
|
1506
|
+
> NOTE: In version 0.70, `{% if_filled %}` tags were replaced with `{{ component_vars.is_filled }}` variables. If your slot name contained special characters, see the section [Accessing `is_filled` of slot names with special characters](#accessing-is_filled-of-slot-names-with-special-characters).
|
|
1322
1507
|
|
|
1323
1508
|
In certain circumstances, you may want the behavior of slot filling to depend on
|
|
1324
1509
|
whether or not a particular slot is filled.
|
|
@@ -1583,7 +1768,7 @@ This means that you can use `self.input` inside:
|
|
|
1583
1768
|
- `get_template_name`
|
|
1584
1769
|
- `get_template_string`
|
|
1585
1770
|
|
|
1586
|
-
`self.input` is defined only for the duration of `Component.render`, and
|
|
1771
|
+
`self.input` is defined only for the duration of `Component.render`, and raises `RuntimeError` when called outside of this.
|
|
1587
1772
|
|
|
1588
1773
|
`self.input` has the same fields as the input to `Component.render`:
|
|
1589
1774
|
|
|
@@ -2403,6 +2588,88 @@ renders:
|
|
|
2403
2588
|
<div>123</div>
|
|
2404
2589
|
```
|
|
2405
2590
|
|
|
2591
|
+
## Component hooks
|
|
2592
|
+
|
|
2593
|
+
_New in version 0.96_
|
|
2594
|
+
|
|
2595
|
+
Component hooks are functions that allow you to intercept the rendering process at specific positions.
|
|
2596
|
+
|
|
2597
|
+
### Available hooks
|
|
2598
|
+
|
|
2599
|
+
- `on_render_before`
|
|
2600
|
+
|
|
2601
|
+
```py
|
|
2602
|
+
def on_render_before(
|
|
2603
|
+
self: Component,
|
|
2604
|
+
context: Context,
|
|
2605
|
+
template: Template
|
|
2606
|
+
) -> None:
|
|
2607
|
+
```
|
|
2608
|
+
|
|
2609
|
+
Hook that runs just before the component's template is rendered.
|
|
2610
|
+
|
|
2611
|
+
You can use this hook to access or modify the context or the template:
|
|
2612
|
+
|
|
2613
|
+
```py
|
|
2614
|
+
def on_render_before(self, context, template) -> None:
|
|
2615
|
+
# Insert value into the Context
|
|
2616
|
+
context["from_on_before"] = ":)"
|
|
2617
|
+
|
|
2618
|
+
# Append text into the Template
|
|
2619
|
+
template.nodelist.append(TextNode("FROM_ON_BEFORE"))
|
|
2620
|
+
```
|
|
2621
|
+
|
|
2622
|
+
- `on_render_after`
|
|
2623
|
+
|
|
2624
|
+
```py
|
|
2625
|
+
def on_render_after(
|
|
2626
|
+
self: Component,
|
|
2627
|
+
context: Context,
|
|
2628
|
+
template: Template,
|
|
2629
|
+
content: str
|
|
2630
|
+
) -> None | str | SafeString:
|
|
2631
|
+
```
|
|
2632
|
+
|
|
2633
|
+
Hook that runs just after the component's template was rendered.
|
|
2634
|
+
It receives the rendered output as the last argument.
|
|
2635
|
+
|
|
2636
|
+
You can use this hook to access the context or the template, but modifying
|
|
2637
|
+
them won't have any effect.
|
|
2638
|
+
|
|
2639
|
+
To override the content that gets rendered, you can return a string or SafeString from this hook:
|
|
2640
|
+
|
|
2641
|
+
```py
|
|
2642
|
+
def on_render_after(self, context, template, content):
|
|
2643
|
+
# Prepend text to the rendered content
|
|
2644
|
+
return "Chocolate cookie recipe: " + content
|
|
2645
|
+
```
|
|
2646
|
+
|
|
2647
|
+
### Component hooks example
|
|
2648
|
+
|
|
2649
|
+
You can use hooks together with [provide / inject](#how-to-use-provide--inject) to create components
|
|
2650
|
+
that accept a list of items via a slot.
|
|
2651
|
+
|
|
2652
|
+
In the example below, each `tab_item` component will be rendered on a separate tab page, but they are all defined in the default slot of the `tabs` component.
|
|
2653
|
+
|
|
2654
|
+
[See here for how it was done](https://github.com/EmilStenstrom/django-components/discussions/540)
|
|
2655
|
+
|
|
2656
|
+
```django
|
|
2657
|
+
{% component "tabs" %}
|
|
2658
|
+
{% component "tab_item" header="Tab 1" %}
|
|
2659
|
+
<p>
|
|
2660
|
+
hello from tab 1
|
|
2661
|
+
</p>
|
|
2662
|
+
{% component "button" %}
|
|
2663
|
+
Click me!
|
|
2664
|
+
{% endcomponent %}
|
|
2665
|
+
{% endcomponent %}
|
|
2666
|
+
|
|
2667
|
+
{% component "tab_item" header="Tab 2" %}
|
|
2668
|
+
Hello this is tab 2
|
|
2669
|
+
{% endcomponent %}
|
|
2670
|
+
{% endcomponent %}
|
|
2671
|
+
```
|
|
2672
|
+
|
|
2406
2673
|
## Component context and scope
|
|
2407
2674
|
|
|
2408
2675
|
By default, context variables are passed down the template as in regular Django - deeper scopes can access the variables from the outer scopes. So if you have several nested forloops, then inside the deep-most loop you can access variables defined by all previous loops.
|
|
@@ -2421,6 +2688,24 @@ If you find yourself using the `only` modifier often, you can set the [context_b
|
|
|
2421
2688
|
|
|
2422
2689
|
Components can also access the outer context in their context methods like `get_context_data` by accessing the property `self.outer_context`.
|
|
2423
2690
|
|
|
2691
|
+
## Pre-defined template variables
|
|
2692
|
+
|
|
2693
|
+
Here is a list of all variables that are automatically available from within the component's template and `on_render_before` / `on_render_after` hooks.
|
|
2694
|
+
|
|
2695
|
+
- `component_vars.is_filled`
|
|
2696
|
+
|
|
2697
|
+
_New in version 0.70_
|
|
2698
|
+
|
|
2699
|
+
Dictonary describing which slots are filled (`True`) or are not (`False`).
|
|
2700
|
+
|
|
2701
|
+
Example:
|
|
2702
|
+
|
|
2703
|
+
```django
|
|
2704
|
+
{% if component_vars.is_filled.my_slot %}
|
|
2705
|
+
{% slot "my_slot" / %}
|
|
2706
|
+
{% endif %}
|
|
2707
|
+
```
|
|
2708
|
+
|
|
2424
2709
|
## Customizing component tags with TagFormatter
|
|
2425
2710
|
|
|
2426
2711
|
_New in version 0.89_
|
|
@@ -2816,6 +3101,7 @@ Here's overview of all available settings and their defaults:
|
|
|
2816
3101
|
COMPONENTS = {
|
|
2817
3102
|
"autodiscover": True,
|
|
2818
3103
|
"context_behavior": "django", # "django" | "isolated"
|
|
3104
|
+
"dynamic_component_name": "dynamic",
|
|
2819
3105
|
"libraries": [], # ["mysite.components.forms", ...]
|
|
2820
3106
|
"multiline_tags": True,
|
|
2821
3107
|
"reload_on_template_change": False,
|
|
@@ -2876,6 +3162,16 @@ COMPONENTS = {
|
|
|
2876
3162
|
}
|
|
2877
3163
|
```
|
|
2878
3164
|
|
|
3165
|
+
### `dynamic_component_name`
|
|
3166
|
+
|
|
3167
|
+
By default, the dynamic component is registered under the name `"dynamic"`. In case of a conflict, use this setting to change the name used for the dynamic components.
|
|
3168
|
+
|
|
3169
|
+
```python
|
|
3170
|
+
COMPONENTS = {
|
|
3171
|
+
"dynamic_component_name": "new_dynamic",
|
|
3172
|
+
}
|
|
3173
|
+
```
|
|
3174
|
+
|
|
2879
3175
|
### `multiline_tags` - Enable/Disable multiline support
|
|
2880
3176
|
|
|
2881
3177
|
If `True`, template tags can span multiple lines. Default: `True`
|