Jinja Default: filter function to set a fallback value

The Ultimate Guide to the Jinja default Filter

The Jinja default filter is a powerful tool for providing a fallback value when a variable is undefined or evaluates to false. This prevents templates from crashing due to missing data and ensures that your application always renders something meaningful to the user. It’s a key filter for building robust and resilient templates that can gracefully handle unexpected or incomplete data.

---

How the default Filter Works

The default filter checks the status of a variable and, if it is considered “empty,” it returns a specified default value. Otherwise, it returns the original value.nnThe syntax is:

{{ my_variable | default('default_value', boolean=False) }}

It takes two optional parameters:

• • default_value (default ''): The value to return if the variable is empty. This can be a string, a number, a list, or any other type.

• • boolean (default False): This parameter changes the filter’s behavior.n
    • • When boolean=False (the default), the filter only returns the default value if the variable is undefined or a jinja2.Undefined object.

     

    • • When boolean=True, the filter returns the default value for any “falsy” value, including None, empty strings (''), empty lists ([]), empty dictionaries ({}), or the number 0. This is particularly useful when you need to handle empty data that is technically “defined” but contains no content.

---

Practical Examples

Let’s look at some examples to see how the default filter can be used to handle various scenarios.

Example 1: Handling an Undefined Variable

This is the most basic use case, where a variable simply isn’t passed to the template.nnJinja Template:

{% set username = 'Alice' %}<p>Welcome, {{ username | default('Guest') }}!</p><p>My role is {{ user_role | default('unassigned') }}.</p>

Rendered HTML:

<p>Welcome, Alice!</p><p>My role is unassigned.</p>

The username variable is defined and its value is used. The user_role variable is undefined, so the filter provides the default value.

Example 2: Handling Falsy Values with the boolean Parameter

This is where the power of the boolean parameter becomes apparent. By setting it to True, you can handle empty data gracefully.nnJinja Template:

{% set my_cart = [] %}n<p>You have {{ my_cart | length }} items in your cart.</p><p>Your cart is {{ my_cart | default('empty', True) }}.</p>

Rendered HTML:

<p>You have 0 items in your cart.</p><p>Your cart is empty.</p>

In the first line, my_cart is an empty list, so its length is 0. In the second line, with boolean=True, the default filter correctly identifies the empty list as a falsy value and substitutes it with the string "empty".

Example 3: Providing a Default for a Falsy Number

Similarly, you can use boolean=True to provide a fallback for a falsy number like 0.

Jinja Template:

{% set product_stock = 0 %}n<p>Stock status: {{ product_stock | default('Out of Stock', True) }}</p>

Rendered HTML:

<p>Stock status: Out of Stock</p>

Without boolean=True, the output would be 0. This makes the default filter a versatile tool for creating user-friendly messages.

---

Conclusion

The Jinja default filter is an indispensable part of a developer’s toolkit. By providing a clean and expressive way to handle missing or empty data, it helps you build templates that are less prone to errors and more user-friendly. Its boolean parameter offers an extra layer of control, allowing you to fine-tune its behavior to suit a wide range of data scenarios.