add new {% bird:var %} templatetag (#170)

* add new `{% bird:var %}` templatetag

* Add tests for custom template variable tag

* Escape regex special characters in pytest raises matcher for template tag tests

* Add tests for variable context isolation in template components

* Add tests for var context and nested component behavior

* Remove unused end var tag and simplify var tag implementation

* Add documentation for project variables

* Add documentation for component variables with `bird:var` tag

* Add documentation for explicit variable cleanup with `endbird:var`

* Add support for explicit variable cleanup in Django Bird template tags

* Update documentation for django-bird variable tag syntax and examples

* Update "Basic Usage" section in documentation with improved examples and clarity

* Add test for resetting template variable to None

* update changelog

* tweak

* add to sidebar

* Update documentation for django-bird variables with clearer examples and explanations

* tweak

* rweak

* uv

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,9 +18,14 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- Added the `{% bird:var %}` templatetag for managing local context variables within components, including support for appending, overwriting, and resetting values. Variables are scoped to components and automatically are cleaned up when the component finishes rendering, with optional explicit cleanup via `{% endbird:var %}`.
+
 ## [0.13.2]
 
 ### Fixed
+
 - Fixed static file URL generation to use correct relative paths when serving component assets through Django's static file storage system.
 
 ## [0.13.1]

docs/index.md

@@ -13,6 +13,7 @@
 :maxdepth: 3
 Naming <naming>
 Attributes/Properties <params>
+Variables <vars>
 slots
 Assets <assets>
 Organization <organization>

docs/vars.md

@@ -0,0 +1,165 @@
+# Variables in Components
+
+django-bird provides a way to manage local variables within components using the `{% bird:var %}` template tag. Similar to Django's built-in `{% with %}` tag, it allows you to create temporary variables, but with some key advantages:
+
+- No closing tag required (unlike `{% with %}` which needs `{% endwith %}`)
+- Variables are automatically cleaned up when the component finishes rendering
+- Variables are properly scoped to each component instance
+- Supports appending to existing values
+
+## Basic Usage
+
+The `{% bird:var %}` tag allows you to create and modify variables that are scoped to the current component. These variables are accessible through the `vars` context dictionary.
+
+### Creating Variables
+
+To create a new variable, use the assignment syntax:
+
+```htmldjango
+{% bird:var name='value' %}
+
+{{ vars.name }}  {# Outputs: value #}
+```
+
+### Overwriting and Clearing Variables
+
+You can overwrite an existing variable by assigning a new value:
+
+```htmldjango
+{% bird:var counter='1' %}
+
+{{ vars.counter }}  {# Outputs: 1 #}
+
+{% bird:var counter='2' %}
+
+{{ vars.counter }}  {# Outputs: 2 #}
+```
+
+To reset/clear a variable, set it to None:
+
+```htmldjango
+{% bird:var message='hello' %}
+
+{{ vars.message }}  {# Outputs: hello #}
+
+{% bird:var message=None %}
+
+{{ vars.message }}  {# Variable is cleared #}
+```
+
+Alternatively, you can use explicit cleanup with `{% endbird:var %}` - see [Explicit Variable Cleanup](#explicit-variable-cleanup) for details.
+
+### Appending to Variables
+
+The `+=` operator lets you append to existing variables:
+
+```htmldjango
+{% bird:var greeting='Hello' %}
+{% bird:var greeting+=' World' %}
+
+{{ vars.greeting }}  {# Outputs: Hello World #}
+```
+
+If you append to a non-existent variable, it will be created:
+
+```htmldjango
+{% bird:var message+='World' %}
+
+{{ vars.message }}  {# Outputs: World #}
+```
+
+## Variable Scope
+
+Variables created with `{% bird:var %}` are:
+
+- Local to the component where they are defined
+- Isolated between different instances of the same component
+- Not accessible outside the component
+- Reset between renders
+
+```{code-block} htmldjango
+:caption: templates/bird/button.html
+
+{% bird:var count='1' %}
+
+Count: {{ vars.count }}
+```
+
+```{code-block} htmldjango
+:caption: template.html
+
+{% bird button %}{% endbird %} {# Count: 1 #}
+{% bird button %}{% endbird %} {# Count: 1 #}
+
+Outside: {{ vars.count }}  {# vars.count is not accessible here #}
+```
+
+Each instance of the button component will have its own isolated `count` variable.
+
+### Explicit Variable Cleanup
+
+While variables are automatically cleaned up when a component finishes rendering, you can explicitly clean up variables using the `{% endbird:var %}` tag:
+
+```htmldjango
+{% bird:var message='Hello' %}
+
+{{ vars.message }}  {# Outputs: Hello #}
+
+{% endbird:var message %}
+
+{{ vars.message }}  {# Variable is now cleaned up #}
+```
+
+This can be useful when you want to ensure a variable is cleaned up at a specific point in your template, rather than waiting for the component to finish rendering.
+
+You can clean up multiple variables independently:
+
+```htmldjango
+{% bird:var x='hello' %}
+{% bird:var y='world' %}
+
+{{ vars.x }} {{ vars.y }}  {# Outputs: hello world #}
+
+{% endbird:var x %}
+
+{{ vars.x }} {{ vars.y }}  {# Outputs: world (x is cleaned up) #}
+
+{% endbird:var y %}
+
+{{ vars.x }} {{ vars.y }}  {# Both variables are now cleaned up #}
+```
+
+## Working with Template Variables
+
+You can use template variables when setting values:
+
+```htmldjango
+{% bird:var greeting='Hello ' %}
+{% bird:var greeting+=user.name %}
+
+{{ vars.greeting }}  {# Outputs: Hello John #}
+```
+
+## Nested Components
+
+Variables are properly scoped in nested components:
+
+```{code-block} htmldjango
+:caption: templates/bird/outer.html
+
+{% bird:var message='Outer' %}
+
+{{ vars.message }}
+
+{% bird inner %}{% endbird %}
+
+{{ vars.message }} {# vars.message still contains 'Outer' here #}
+```
+
+```{code-block} htmldjango
+:caption: templates/bird/inner.html
+
+{% bird:var message='Inner' %}
+
+{{ vars.message }}  {# Contains 'Inner', doesn't affect outer component #}
+```

src/django_bird/components.py

@@ -151,6 +151,7 @@ def render(self, context: Context):
                 "props": props,
                 "slot": slots.get(DEFAULT_SLOT),
                 "slots": slots,
+                "vars": {},
             }
         ):
             return self.component.template.template.render(context)

src/django_bird/templatetags/django_bird.py

@@ -6,6 +6,7 @@
 from .tags import bird
 from .tags import prop
 from .tags import slot
+from .tags import var
 
 register = template.Library()
 
@@ -15,3 +16,5 @@
 register.tag(bird.TAG, bird.do_bird)
 register.tag(prop.TAG, prop.do_prop)
 register.tag(slot.TAG, slot.do_slot)
+register.tag(var.TAG, var.do_var)
+register.tag(var.END_TAG, var.do_end_var)

src/django_bird/templatetags/tags/var.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+from typing import final
+
+from django import template
+from django.template.base import Parser
+from django.template.base import Token
+from django.template.context import Context
+
+from django_bird._typing import override
+
+register = template.Library()
+
+TAG = "bird:var"
+END_TAG = "endbird:var"
+
+OPERATOR_PATTERN = re.compile(r"(\w+)\s*(\+=|=)\s*(.+)")
+
+
+@register.tag(name=TAG)
+def do_var(parser: Parser, token: Token):
+    _tag, *bits = token.split_contents()
+    if not bits:
+        msg = f"'{TAG}' tag requires an assignment"
+        raise template.TemplateSyntaxError(msg)
+
+    var_assignment = bits.pop(0)
+    match = re.match(OPERATOR_PATTERN, var_assignment)
+    if not match:
+        msg = (
+            f"Invalid assignment in '{TAG}' tag: {var_assignment}. "
+            f"Expected format: {TAG} variable='value' or {TAG} variable+='value'."
+        )
+        raise template.TemplateSyntaxError(msg)
+
+    var_name, operator, var_value = match.groups()
+    var_value = var_value.strip()
+    value = parser.compile_filter(var_value)
+
+    return VarNode(var_name, operator, value)
+
+
+@register.tag(name=END_TAG)
+def do_end_var(_parser: Parser, token: Token):
+    _tag, *bits = token.split_contents()
+    if not bits:
+        msg = f"{token.contents.split()[0]} tag requires a variable name"
+        raise template.TemplateSyntaxError(msg)
+
+    var_name = bits.pop(0)
+
+    return EndVarNode(var_name)
+
+
+@final
+class VarNode(template.Node):
+    def __init__(self, name: str, operator: str, value: Any):
+        self.name = name
+        self.operator = operator
+        self.value = value
+
+    @override
+    def render(self, context: Context) -> str:
+        if "vars" not in context:
+            context["vars"] = {}
+
+        value = self.value.resolve(context)
+
+        if self.operator == "+=":
+            previous = context["vars"].get(self.name, "")
+            value = f"{previous}{value}"
+
+        context["vars"][self.name] = value
+        return ""
+
+
+@final
+class EndVarNode(template.Node):
+    def __init__(self, name: str):
+        self.name = name
+
+    @override
+    def render(self, context: Context) -> str:
+        if "vars" in context and self.name in context["vars"]:
+            del context["vars"][self.name]
+        return ""