django-components 0.73__tar.gz → 0.74__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 (46) hide show
  1. {django_components-0.73/src/django_components.egg-info → django_components-0.74}/PKG-INFO +458 -2
  2. {django_components-0.73 → django_components-0.74}/README.md +457 -1
  3. {django_components-0.73 → django_components-0.74}/pyproject.toml +1 -1
  4. django_components-0.74/src/django_components/attributes.py +96 -0
  5. {django_components-0.73 → django_components-0.74}/src/django_components/component.py +7 -2
  6. {django_components-0.73 → django_components-0.74}/src/django_components/template_parser.py +93 -14
  7. {django_components-0.73 → django_components-0.74}/src/django_components/templatetags/component_tags.py +105 -14
  8. {django_components-0.73 → django_components-0.74/src/django_components.egg-info}/PKG-INFO +458 -2
  9. {django_components-0.73 → django_components-0.74}/src/django_components.egg-info/SOURCES.txt +2 -0
  10. django_components-0.74/tests/test_attributes.py +364 -0
  11. {django_components-0.73 → django_components-0.74}/tests/test_component.py +33 -0
  12. {django_components-0.73 → django_components-0.74}/LICENSE +0 -0
  13. {django_components-0.73 → django_components-0.74}/setup.cfg +0 -0
  14. {django_components-0.73 → django_components-0.74}/src/django_components/__init__.py +0 -0
  15. {django_components-0.73 → django_components-0.74}/src/django_components/app_settings.py +0 -0
  16. {django_components-0.73 → django_components-0.74}/src/django_components/apps.py +0 -0
  17. {django_components-0.73 → django_components-0.74}/src/django_components/component_registry.py +0 -0
  18. {django_components-0.73 → django_components-0.74}/src/django_components/context.py +0 -0
  19. {django_components-0.73 → django_components-0.74}/src/django_components/logger.py +0 -0
  20. {django_components-0.73 → django_components-0.74}/src/django_components/management/__init__.py +0 -0
  21. {django_components-0.73 → django_components-0.74}/src/django_components/management/commands/__init__.py +0 -0
  22. {django_components-0.73 → django_components-0.74}/src/django_components/management/commands/startcomponent.py +0 -0
  23. {django_components-0.73 → django_components-0.74}/src/django_components/management/commands/upgradecomponent.py +0 -0
  24. {django_components-0.73 → django_components-0.74}/src/django_components/middleware.py +0 -0
  25. {django_components-0.73 → django_components-0.74}/src/django_components/node.py +0 -0
  26. {django_components-0.73 → django_components-0.74}/src/django_components/py.typed +0 -0
  27. {django_components-0.73 → django_components-0.74}/src/django_components/safer_staticfiles/__init__.py +0 -0
  28. {django_components-0.73 → django_components-0.74}/src/django_components/safer_staticfiles/apps.py +0 -0
  29. {django_components-0.73 → django_components-0.74}/src/django_components/slots.py +0 -0
  30. {django_components-0.73 → django_components-0.74}/src/django_components/template_loader.py +0 -0
  31. {django_components-0.73 → django_components-0.74}/src/django_components/templatetags/__init__.py +0 -0
  32. {django_components-0.73 → django_components-0.74}/src/django_components/types.py +0 -0
  33. {django_components-0.73 → django_components-0.74}/src/django_components/utils.py +0 -0
  34. {django_components-0.73 → django_components-0.74}/src/django_components.egg-info/dependency_links.txt +0 -0
  35. {django_components-0.73 → django_components-0.74}/src/django_components.egg-info/requires.txt +0 -0
  36. {django_components-0.73 → django_components-0.74}/src/django_components.egg-info/top_level.txt +0 -0
  37. {django_components-0.73 → django_components-0.74}/tests/test_autodiscover.py +0 -0
  38. {django_components-0.73 → django_components-0.74}/tests/test_component_as_view.py +0 -0
  39. {django_components-0.73 → django_components-0.74}/tests/test_context.py +0 -0
  40. {django_components-0.73 → django_components-0.74}/tests/test_dependency_rendering.py +0 -0
  41. {django_components-0.73 → django_components-0.74}/tests/test_registry.py +0 -0
  42. {django_components-0.73 → django_components-0.74}/tests/test_settings.py +0 -0
  43. {django_components-0.73 → django_components-0.74}/tests/test_startcomponent_command.py +0 -0
  44. {django_components-0.73 → django_components-0.74}/tests/test_template_parser.py +0 -0
  45. {django_components-0.73 → django_components-0.74}/tests/test_templatetags.py +0 -0
  46. {django_components-0.73 → django_components-0.74}/tests/testutils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: django_components
3
- Version: 0.73
3
+ Version: 0.74
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
@@ -44,6 +44,8 @@ Read on to learn about the details!
44
44
 
45
45
  ## Release notes
46
46
 
47
+ **Version 0.74** introduces `html_attrs` tag and `prefix:key=val` construct for passing dicts to components.
48
+
47
49
  🚨📢 **Version 0.70**
48
50
 
49
51
  - `{% if_filled "my_slot" %}` tags were replaced with `{{ component_vars.is_filled.my_slot }}` variables.
@@ -704,6 +706,8 @@ As seen above, you can pass arguments to components like so:
704
706
 
705
707
  ### Special characters
706
708
 
709
+ _New in version 0.71_:
710
+
707
711
  Keyword arguments can contain special characters `# @ . - _`, so keywords like
708
712
  so are still valid:
709
713
 
@@ -725,8 +729,460 @@ class Calendar(component.Component):
725
729
  return {
726
730
  "date": kwargs["my-date"],
727
731
  "id": kwargs["#some_id"],
728
- "@click.native": kwargs["@click.native"]
732
+ "on_click": kwargs["@click.native"]
733
+ }
734
+ ```
735
+
736
+ ### Pass dictonary by its key-value pairs
737
+
738
+ _New in version 0.74_:
739
+
740
+ Sometimes, a component may expect a dictionary as one of its inputs.
741
+
742
+ Most commonly, this happens when a component accepts a dictionary
743
+ of HTML attributes (usually called `attrs`) to pass to the underlying template.
744
+
745
+ In such cases, we may want to define some HTML attributes statically, and other dynamically.
746
+ But for that, we need to define this dictionary on Python side:
747
+
748
+ ```py
749
+ @component.register("my_comp")
750
+ class MyComp(component.Component):
751
+ template = """
752
+ {% component "other" attrs=attrs %}
753
+ {% endcomponent %}
754
+ """
755
+
756
+ def get_context_data(self, some_id: str):
757
+ attrs = {
758
+ "class": "pa-4 flex",
759
+ "data-some-id": some_id,
760
+ "@click.stop": "onClickHandler",
761
+ }
762
+ return {"attrs": attrs}
763
+ ```
764
+
765
+ But as you can see in the case above, the event handler `@click.stop` and styling `pa-4 flex`
766
+ are disconnected from the template. If the component grew in size and we moved the HTML
767
+ to a separate file, we would have hard time reasoning about the component's template.
768
+
769
+ Luckily, there's a better way.
770
+
771
+ When we want to pass a dictionary to a component, we can define individual key-value pairs
772
+ as component kwargs, so we can keep all the relevant information in the template. For that,
773
+ we prefix the key with the name of the dict and `:`. So key `class` of input `attrs` becomes
774
+ `attrs:class`. And our example becomes:
775
+
776
+ ```py
777
+ @component.register("my_comp")
778
+ class MyComp(component.Component):
779
+ template = """
780
+ {% component "other"
781
+ attrs:class="pa-4 flex"
782
+ attrs:data-some-id=some_id
783
+ attrs:@click.stop="onClickHandler"
784
+ %}
785
+ {% endcomponent %}
786
+ """
787
+
788
+ def get_context_data(self, some_id: str):
789
+ return {"some_id": some_id}
790
+ ```
791
+
792
+ Sweet! Now all the relevant HTML is inside the template, and we can move it to a separate file with confidence:
793
+
794
+ ```django
795
+ {% component "other"
796
+ attrs:class="pa-4 flex"
797
+ attrs:data-some-id=some_id
798
+ attrs:@click.stop="onClickHandler"
799
+ %}
800
+ {% endcomponent %}
801
+ ```
802
+
803
+ > Note: It is NOT possible to define nested dictionaries, so
804
+ `attrs:my_key:two=2` would be interpreted as:
805
+ >
806
+ > ```py
807
+ > {"attrs": {"my_key:two": 2}}
808
+ > ```
809
+
810
+ ## Rendering HTML attributes
811
+
812
+ _New in version 0.74_:
813
+
814
+ You can use the `html_attrs` tag to render HTML attributes, given a dictionary
815
+ of values.
816
+
817
+ So if you have a template:
818
+
819
+ ```django
820
+ <div class="{{ classes }}" data-id="{{ my_id }}">
821
+ </div>
822
+ ```
823
+
824
+ You can simplify it with `html_attrs` tag:
825
+
826
+ ```django
827
+ <div {% html_attrs attrs %}>
828
+ </div>
829
+ ```
830
+
831
+ where `attrs` is:
832
+
833
+ ```py
834
+ attrs = {
835
+ "class": classes,
836
+ "data-id": my_id,
837
+ }
838
+ ```
839
+
840
+ This feature is inspired by [`merge_attrs` tag of django-web-components](https://github.com/Xzya/django-web-components/tree/master?tab=readme-ov-file#default--merged-attributes) and
841
+ ["fallthrough attributes" feature of Vue](https://vuejs.org/guide/components/attrs).
842
+
843
+ ### Removing atttributes
844
+
845
+ Attributes that are set to `None` or `False` are NOT rendered.
846
+
847
+ So given this input:
848
+
849
+ ```py
850
+ attrs = {
851
+ "class": "text-green",
852
+ "required": False,
853
+ "data-id": None,
854
+ }
855
+ ```
856
+
857
+ And template:
858
+
859
+ ```django
860
+ <div {% html_attrs attrs %}>
861
+ </div>
862
+ ```
863
+
864
+ Then this renders:
865
+
866
+ ```html
867
+ <div class="text-green">
868
+ </div>
869
+ ```
870
+
871
+ ### Boolean attributes
872
+
873
+ In HTML, boolean attributes are usually rendered with no value. Consider the example below where the first button is disabled and the second is not:
874
+
875
+ ```html
876
+ <button disabled> Click me! </button>
877
+ <button> Click me! </button>
878
+ ```
879
+
880
+ HTML rendering with `html_attrs` tag or `attributes_to_string` works the same way, where `key=True` is rendered simply as `key`, and `key=False` is not render at all.
881
+
882
+ So given this input:
883
+
884
+ ```py
885
+ attrs = {
886
+ "disabled": True,
887
+ "autofocus": False,
888
+ }
889
+ ```
890
+
891
+ And template:
892
+
893
+ ```django
894
+ <div {% html_attrs attrs %}>
895
+ </div>
896
+ ```
897
+
898
+ Then this renders:
899
+
900
+ ```html
901
+ <div disabled>
902
+ </div>
903
+ ```
904
+
905
+ ### Default attributes
906
+
907
+ Sometimes you may want to specify default values for attributes. You can pass a second argument (or kwarg `defaults`) to set the defaults.
908
+
909
+ ```django
910
+ <div {% html_attrs attrs defaults %}>
911
+ ...
912
+ </div>
913
+ ```
914
+
915
+ In the example above, if `attrs` contains e.g. the `class` key, `html_attrs` will render:
916
+
917
+ `class="{{ attrs.class }}"`
918
+
919
+ Otherwise, `html_attrs` will render:
920
+
921
+ `class="{{ defaults.class }}"`
922
+
923
+ ### Appending attributes
924
+
925
+ For the `class` HTML attribute, it's common that we want to _join_ multiple values,
926
+ instead of overriding them. For example, if you're authoring a component, you may
927
+ want to ensure that the component will ALWAYS have a specific class. Yet, you may
928
+ want to allow users of your component to supply their own classes.
929
+
930
+ We can achieve this by adding extra kwargs. These values
931
+ will be appended, instead of overwriting the previous value.
932
+
933
+ So if we have a variable `attrs`:
934
+ ```py
935
+ attrs = {
936
+ "class": "my-class pa-4",
937
+ }
938
+ ```
939
+
940
+ And on `html_attrs` tag, we set the key `class`:
941
+
942
+ ```django
943
+ <div {% html_attrs attrs class="some-class" %}>
944
+ </div>
945
+ ```
946
+
947
+ Then these will be merged and rendered as:
948
+
949
+ ```html
950
+ <div data-value="my-class pa-4 some-class">
951
+ </div>
952
+ ```
953
+
954
+ To simplify merging of variables, you can supply the same key multiple times, and these will be all joined together:
955
+
956
+ ```django
957
+ {# my_var = "class-from-var text-red" #}
958
+ <div {% html_attrs attrs class="some-class another-class" class=my_var %}>
959
+ </div>
960
+ ```
961
+
962
+ Renders:
963
+
964
+ ```html
965
+ <div data-value="my-class pa-4 some-class another-class class-from-var text-red">
966
+ </div>
967
+ ```
968
+
969
+ ### Rules for `html_attrs`
970
+
971
+ 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 %}`
978
+
979
+ 2. Both `attrs` and `defaults` are optional (can be omitted)
980
+
981
+ 3. Both `attrs` and `defaults` are dictionaries, and we can define them the same way [we define dictionaries for the `component` tag](#pass-dictonary-by-its-key-value-pairs). So either as `attrs=attrs` or `attrs:key=value`.
982
+
983
+ 4. All other kwargs are appended and can be repeated.
984
+
985
+ ### Examples for `html_attrs`
986
+
987
+ Assuming that:
988
+
989
+ ```py
990
+ class_from_var = "from-var"
991
+
992
+ attrs = {
993
+ "class": "from-attrs",
994
+ "type": "submit",
995
+ }
996
+
997
+ defaults = {
998
+ "class": "from-defaults",
999
+ "role": "button",
1000
+ }
1001
+ ```
1002
+
1003
+ Then:
1004
+
1005
+ - Empty tag <br/>
1006
+ `{% html_attr %}`
1007
+
1008
+ renders (empty string): <br/>
1009
+ ` `
1010
+
1011
+ - Only kwargs <br/>
1012
+ `{% html_attr class="some-class" class=class_from_var data-id="123" %}`
1013
+
1014
+ renders: <br/>
1015
+ `class="some-class from-var" data-id="123"`
1016
+
1017
+ - Only attrs <br/>
1018
+ `{% html_attr attrs %}`
1019
+
1020
+ renders: <br/>
1021
+ `class="from-attrs" type="submit"`
1022
+
1023
+ - Attrs as kwarg <br/>
1024
+ `{% html_attr attrs=attrs %}`
1025
+
1026
+ renders: <br/>
1027
+ `class="from-attrs" type="submit"`
1028
+
1029
+ - Only defaults (as kwarg) <br/>
1030
+ `{% html_attr defaults=defaults %}`
1031
+
1032
+ renders: <br/>
1033
+ `class="from-defaults" role="button"`
1034
+
1035
+ - Attrs using the `prefix:key=value` construct <br/>
1036
+ `{% html_attr attrs:class="from-attrs" attrs:type="submit" %}`
1037
+
1038
+ renders: <br/>
1039
+ `class="from-attrs" type="submit"`
1040
+
1041
+ - Defaults using the `prefix:key=value` construct <br/>
1042
+ `{% html_attr defaults:class="from-defaults" %}`
1043
+
1044
+ renders: <br/>
1045
+ `class="from-defaults" role="button"`
1046
+
1047
+ - 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 %}`
1049
+
1050
+ renders: <br/>
1051
+ `class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
1052
+
1053
+ - 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 %}`
1055
+
1056
+ renders: <br/>
1057
+ `class="from-attrs added_class from-var" type="submit" role="button" data-id=123`
1058
+
1059
+ - All together (3) - mixed: <br/>
1060
+ `{% html_attrs attrs defaults:class="default-class" class="added_class" class=class_from_var data-id=123 %}`
1061
+
1062
+ renders: <br/>
1063
+ `class="from-attrs added_class from-var" type="submit" data-id=123`
1064
+
1065
+ ### Full example for `html_attrs`
1066
+
1067
+ ```py
1068
+ @component.register("my_comp")
1069
+ class MyComp(component.Component):
1070
+ template: t.django_html = """
1071
+ <div
1072
+ {% html_attrs attrs
1073
+ defaults:class="pa-4 text-red"
1074
+ class="my-comp-date"
1075
+ class=class_from_var
1076
+ data-id="123"
1077
+ %}
1078
+ >
1079
+ Today's date is <span>{{ date }}</span>
1080
+ </div>
1081
+ """
1082
+
1083
+ def get_context_data(self, date: Date, attrs: dict):
1084
+ return {
1085
+ "date": date,
1086
+ "attrs": attrs,
1087
+ "class_from_var": "extra-class"
729
1088
  }
1089
+
1090
+ @component.register("parent")
1091
+ class Parent(component.Component):
1092
+ template: t.django_html = """
1093
+ {% component "my_comp"
1094
+ date=date
1095
+ attrs:class="pa-0 border-solid border-red"
1096
+ attrs:data-json=json_data
1097
+ attrs:@click="(e) => onClick(e, 'from_parent')"
1098
+ %}
1099
+ {% endcomponent %}
1100
+ """
1101
+
1102
+ def get_context_data(self, date: Date):
1103
+ return {
1104
+ "date": datetime.now(),
1105
+ "json_data": json.dumps({"value": 456})
1106
+ }
1107
+ ```
1108
+
1109
+ Note: For readability, we've split the tags across multiple lines.
1110
+
1111
+ Inside `MyComp`, we defined a default attribute
1112
+
1113
+ `defaults:class="pa-4 text-red"`
1114
+
1115
+ So if `attrs` includes key `class`, the default above will be ignored.
1116
+
1117
+ `MyComp` also defines `class` key twice. It means that whether the `class`
1118
+ attribute is taken from `attrs` or `defaults`, the two `class` values
1119
+ will be appended to it.
1120
+
1121
+ So by default, `MyComp` renders:
1122
+
1123
+ ```html
1124
+ <div class="pa-4 text-red my-comp-date extra-class" data-id="123">
1125
+ ...
1126
+ ```
1127
+
1128
+ Next, let's consider what will be rendered when we call `MyComp` from `Parent`
1129
+ component.
1130
+
1131
+ `MyComp` accepts a `attrs` dictionary, that is passed to `html_attrs`, so the
1132
+ contents of that dictionary are rendered as the HTML attributes.
1133
+
1134
+ In `Parent`, we make use of passing dictionary key-value pairs as kwargs to define
1135
+ individual attributes as if they were regular kwargs.
1136
+
1137
+ So all kwargs that start with `attrs:` will be collected into an `attrs` dict.
1138
+
1139
+ ```django
1140
+ attrs:class="pa-0 border-solid border-red"
1141
+ attrs:data-json=json_data
1142
+ attrs:@click="(e) => onClick(e, 'from_parent')"
1143
+ ```
1144
+
1145
+ And `get_context_data` of `MyComp` will receive `attrs` input with following keys:
1146
+
1147
+ ```py
1148
+ attrs = {
1149
+ "class": "pa-0 border-solid",
1150
+ "data-json": '{"value": 456}',
1151
+ "@click": "(e) => onClick(e, 'from_parent')",
1152
+ }
1153
+ ```
1154
+
1155
+ `attrs["class"]` overrides the default value for `class`, whereas other keys
1156
+ will be merged.
1157
+
1158
+ So in the end `MyComp` will render:
1159
+ ```html
1160
+ <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')"
1165
+ >
1166
+ ...
1167
+ ```
1168
+
1169
+ ### Rendering HTML attributes outside of templates
1170
+
1171
+ If you need to use serialize HTML attributes outside of Django template and the `html_attrs` tag, you can use `attributes_to_string`:
1172
+
1173
+ ```py
1174
+ from django_components.attributes import attributes_to_string
1175
+
1176
+ attrs = {
1177
+ "class": "my-class text-red pa-4",
1178
+ "data-id": 123,
1179
+ "required": True,
1180
+ "disabled": False,
1181
+ "ignored-attr": None,
1182
+ }
1183
+
1184
+ attributes_to_string(attrs)
1185
+ # 'class="my-class text-red pa-4" data-id="123" required'
730
1186
  ```
731
1187
 
732
1188
  ## Component context and scope