feat: @template_tag and refactor how template tags are defined #910

JuroOravec · 2025-01-18T10:57:32Z

No description provided.

JuroOravec · 2025-01-18T10:59:00Z

docs/concepts/advanced/template_tags.md

@@ -0,0 +1,197 @@
+---


Added a documentation page on creating custom template tags that make use of django-component's features.

Here's a preview:

Screen.Recording.2025-01-16.at.10.15.25.mov

JuroOravec · 2025-01-18T11:01:29Z

docs/concepts/advanced/template_tags.md

+- If required parameters are missing, an error is raised
+- If unexpected parameters are passed, an error is raised
+
+To accept keys that are not valid Python identifiers (e.g. `data-id`), or would conflict with Python keywords (e.g. `is`), you can use the `**kwargs` syntax:


This section describes what we outlined in #900 (reply in thread), that kwargs like data-id or class should still be accepted. But when doing so, these kwargs must be collected onto **kwargs.

JuroOravec · 2025-01-18T11:03:50Z

docs/scripts/reference.py

@@ -585,29 +586,29 @@ def _list_urls(urlpatterns: Sequence[Union[URLPattern, URLResolver]], prefix="")
    return urls


-def _format_tag_signature(tag_spec: TagSpec) -> str:
+def _format_tag_signature(node_cls: BaseNode) -> str:


Before, the API reference for template tags was created from the TagSpec objects that were atttached to the template tag definitions. Now the same information is held directly by the Node classes

JuroOravec · 2025-01-18T11:10:13Z

src/django_components/attributes.py

-from django_components.util.template_tag import TagParams
-
-HTML_ATTRS_DEFAULTS_KEY = "defaults"
-HTML_ATTRS_ATTRS_KEY = "attrs"


 class HtmlAttrsNode(BaseNode):


Now, all these 4 are co-located:

Tag definition (e.g. whether it's {% slot %} or {% provide %}),

The Node class that the tag is converted to

The render logic when said Node is encountered during render

The source of truth for the API documentation of this template tag

So I refactored all our template tags, from templatetags/component_tags.py, so that the actual definitions are stored in the respective files. So now, templatetags/component_tags.py contains no logic, and it only declares which template tags we define.

Previously the documentation for individual tags was in templatetags/component_tags.py, so that's why you can see the docstrings here. The docstrings didn't change.

JuroOravec · 2025-01-18T11:12:47Z

src/django_components/attributes.py

-        append_attrs: List[Tuple[str, Any]] = []
-
-        # Resolve all data
-        args, kwargs = self.params.resolve(context)


Also the render() methods are simpler now, because they no longer have to contain logic for figuring out what inputs the template tag received. This is now done behind the scenes by BaseNode. And the individual template tag implementations only need to declare the signature on the render() method.

JuroOravec · 2025-01-18T11:14:49Z

src/django_components/component.py


        self.name = name
-        self.isolated_context = isolated_context


Flags are not stored on the Node class directly, but instead can be accessed as self.flags["flag_name"]

JuroOravec · 2025-01-18T11:15:54Z

src/django_components/component.py

        self.registry = registry

-    def __repr__(self) -> str:


Common methods like __repr__ were moved up to BaseNode

JuroOravec · 2025-01-18T11:27:32Z

src/django_components/component.py

-            self.name,
-            getattr(self, "nodelist", None),  # 'nodelist' attribute only assigned later.
+    @classmethod
+    def parse(  # type: ignore[override]


The ComponentNode is used when we use {% component %} template tag.

Remember that we use ComponentRegistry:

To allow components to be rendered either as {% component %} or {% comp_name %}

To allow to share components as standalone packages.

Because of that, when we use the {% comp_name %} ("shorthand") syntax, then to play nice with the new definition of template tags, we dynamically create a subclass of BaseNode / ComponentNode, that defines the comp_name / endcomp_name as it's start / end tag.

Looking at the code below, I realize that this creates a subclass of ComponentNode on every {% component %} (or custom named tag). But in reality, we need to define only one subclass for component, etc.

So this could be improved by storing the created subclasses, and reusing them when the start_tag matches (and raise if the end_tag or registry don't match).

But this is already a big MR, so I'll leave that for later.

JuroOravec · 2025-01-18T11:28:04Z

src/django_components/component.py


-    def render(self, context: Context) -> str:
-        trace_msg("RENDR", "COMP", self.name, self.node_id)


Also the tracing logs were moved into BaseNode.

JuroOravec · 2025-01-18T11:30:09Z

src/django_components/util/logger.py

@@ -62,27 +62,18 @@ def trace(logger: logging.Logger, message: str, *args: Any, **kwargs: Any) -> No


 def trace_msg(
-    action: Literal["PARSE", "RENDR", "GET", "SET"],


Removed unused bits from this function

JuroOravec · 2025-01-18T11:31:11Z

tests/django_test_setup.py

@@ -22,6 +22,11 @@ def setup_test_config(
                    "tests/templates/",
                    "tests/components/",  # Required for template relative imports in tests
                ],
+                "OPTIONS": {
+                    "builtins": [
+                        "django_components.templatetags.component_tags",


This makes it so that we don't have to call {% load component_tags %} in tests. See #900 (reply in thread)

JuroOravec · 2025-01-18T11:36:25Z

src/django_components/component_registry.py

+        # the component name and passing the rest to the actual tag function.
+        def tag_fn(parser: Parser, token: Token) -> ComponentNode:
+            # Let the TagFormatter pre-process the tokens
+            bits = token.split_contents()


This couple of next lines previously lived in templatetags/component_tags.py (https://github.com/EmilStenstrom/django-components/pull/910/files#diff-7345171ed38e1dd2e4b8199b65a2fd082323bdb331ff0ef0dc0dd3bd43f111aeL498).

It calls the TagFormatter to figure out which start and end template tags should be used with a particular component (e.g. {% component "table" %} ... {% endcomponent %} vs {% table %} ... {% endtable %}.

I moved it up here, so that, instead, the ComponentNode only accepts the already-resolved start_tag and end_tag.

JuroOravec · 2025-01-18T11:37:21Z

src/django_components/dependencies.py

+#########################################################
+
+
+def _component_dependencies(type: Literal["js", "css"]) -> SafeString:


The {% component_js_dependencies %} and {% component_css_dependencies %} were moved to this file for cosistency.

JuroOravec · 2025-01-18T11:39:25Z

src/django_components/templatetags/component_tags.py

+# NOTE: The documentation generation script in `docs/scripts/reference.py` actually
+#   searches this file for all `Node` classes and uses them to generate the documentation.
+#   The docstring on the Node classes is used as the tag's documentation.
+ComponentNode.register(register)


This file now only register the template tags onto the registry.

JuroOravec · 2025-01-18T11:40:34Z

src/django_components/slots.py


-    @property
-    def active_flags(self) -> List[str]:


active_flags was also moved to BaseNode, so now all our Node classes have this property

JuroOravec · 2025-01-18T11:42:08Z

src/django_components/slots.py


-    def resolve_kwargs(self, context: Context) -> "FillWithData":


FillNode.resolve_kwargs and FIllNode._process_kwarg were removed. Now There is only FillNode.render()

JuroOravec · 2025-01-18T11:43:34Z

src/django_components/util/template_tag.py

-        )
-
-    # For details see https://github.com/EmilStenstrom/django-components/pull/902
-    def validate_params(self, params: List["TagParam"]) -> Tuple[List[Any], Dict[str, Any]]:


TagSpec.validate_params is now a standalone function https://github.com/EmilStenstrom/django-components/pull/910/files#diff-56d60a8b1d11d8ff86b912ddde6d8ee539f71a1fae917bc39a1fd049ea22705cR21.

Also, the body got simpler as we don't need to sort inputs into args and kwargs.

JuroOravec · 2025-01-18T11:44:48Z

src/django_components/util/template_tag.py

@@ -11,152 +16,36 @@
 from django_components.util.tag_parser import TagAttr, parse_tag


-@dataclass
-class TagSpec:


TagSpec was removed. the tag, end_tag, flags and signature are now all defined by the BaseNode subclasses.

JuroOravec · 2025-01-18T11:47:37Z

src/django_components/util/template_tag.py

@@ -180,64 +69,54 @@ class TagParam:
    value: Any


-class TagParams(NamedTuple):


TagParams can be removed as a class. Previously it was meant only to ensure that the params, and tag_spec were held in a joint object. But now that's done by BaseNode.

So, similarly to validation, I refactored TagParams.resolve() into a standalone function resolve_params

JuroOravec · 2025-01-18T11:53:44Z

src/django_components/util/template_tag.py

@@ -348,3 +227,99 @@ def merge_repeated_kwargs(params: List[TagParam]) -> List[TagParam]:
            params_by_key[param.key].value += " " + str(param.value)

    return resolved_params
+
+
+def apply_params_in_original_order(


This logic was previously part of validate_params.

The behaviour of this function relates to what we discussed in #900 (comment).

In the end it's implemented so that template tags can have also kwargs like data-id=123 or `class="pt-4".

{% mytag data-id=123 class="pt-4" %}

This would raise if these kwargs were passed like so:

fn(data-id=123, class="pt-4")

Because the first one is not a valid Python variable name, and the latter is a reserved keyword.

So instead, we pass those through the extra_kwargs, which makes these special kwargs to be applied as:

extra_kwargs = {"data-id": 123, "class": "pt-4"} fn(**extra_kwargs)

Which IS allowed by Python.

JuroOravec · 2025-01-18T11:58:14Z

src/django_components/node.py

+        return cls
+
+
+class BaseNode(Node, metaclass=NodeMeta):


In this file is the core of this PR, which adds the BaseNode class and @template_tag decorator, for an easy creation of template tags that use the same features like other django-components' tags.

JuroOravec · 2025-01-18T12:10:27Z

Note to self: After this, there's a bit of cleanup remaining:

I noticed that in the docs site, the page listing all Django signals is NOT shown. I think I need to push to source control the updated built reference pages in docs/reference.
Avoid duplicitly creating ComponentNode subclasses, as described in feat: @template_tag and refactor how template tags are defined #910 (comment)
I still need to update the documentation regarding the use of literal dicts and lists in template tags, and other changes introduced in feat: Literal dicts and lists part 2 #902. But after this PR things are clearer and I'll be able to do so.

feat: @template_tag and refactor how template tags are defined

bae4091

JuroOravec commented Jan 18, 2025

View reviewed changes

refactor: fix docs generation

61b25c0

JuroOravec marked this pull request as ready for review January 18, 2025 12:05

docs: update changelog

c057796

JuroOravec requested a review from EmilStenstrom January 18, 2025 12:29

refactor: catch if special kwarg is before arg

bf1d643

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: @template_tag and refactor how template tags are defined #910

feat: @template_tag and refactor how template tags are defined #910

JuroOravec commented Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025 •

edited

Loading

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec Jan 18, 2025

JuroOravec commented Jan 18, 2025


		def render(self, context: Context) -> str:
		trace_msg("RENDR", "COMP", self.name, self.node_id)

		@@ -62,27 +62,18 @@ def trace(logger: logging.Logger, message: str, args: Any, *kwargs: Any) -> No


		def trace_msg(
		action: Literal["PARSE", "RENDR", "GET", "SET"],

		#########################################################


		def _component_dependencies(type: Literal["js", "css"]) -> SafeString:


		def resolve_kwargs(self, context: Context) -> "FillWithData":

		@@ -180,64 +69,54 @@ class TagParam:
		value: Any


		class TagParams(NamedTuple):

feat: @template_tag and refactor how template tags are defined #910

Are you sure you want to change the base?

feat: @template_tag and refactor how template tags are defined #910

Conversation

JuroOravec commented Jan 18, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JuroOravec Jan 18, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JuroOravec commented Jan 18, 2025

JuroOravec Jan 18, 2025 •

edited

Loading