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:

{% bird:var name='value' %}

{{ vars.name }}  {# Outputs: value #}

Overwriting and Clearing Variables¶

You can overwrite an existing variable by assigning a new value:

{% 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:

{% 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 for details.

Appending to Variables¶

The += operator lets you append to existing variables:

{% 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:

{% 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

templates/bird/button.html¶

{% bird:var count='1' %}

Count: {{ vars.count }}

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:

{% 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:

{% 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:

{% bird:var greeting='Hello ' %}
{% bird:var greeting+=user.name %}

{{ vars.greeting }}  {# Outputs: Hello John #}

Nested Components¶

Variables are properly scoped in nested components:

templates/bird/outer.html¶

{% bird:var message='Outer' %}

{{ vars.message }}

{% bird inner %}{% endbird %}

{{ vars.message }} {# vars.message still contains 'Outer' here #}

templates/bird/inner.html¶

{% bird:var message='Inner' %}

{{ vars.message }}  {# Contains 'Inner', doesn't affect outer component #}