Jinja is a versatile template engine for Python, enabling the creation of dynamic web content by combining static data with object-driven elements. Within SnapApp, Jinja facilitates the seamless integration of structured data into templates, ensuring robust and adaptable presentations. For more comprehensive syntax details, please visit Jinja Documentation.

Table of Contents

• Delimiters in Jinja
• Variables in Jinja
• Variable data types
• Expressions
• Jinja Data Structures
• Adding and removing items from a list
• How to create and access Tuples
• How to define and access Dictionaries?
• Jinja Filters
• Global Variables in Jinja
• Functions on Data Types
• Jinja Blocks
• Block Types
• Macros
• Call
• Raw
• Jinja in SnapApp
• SnapApp function in Jinja

Delimiters in Jinja

In Jinja, delimiters are used to differentiate template code from standard content, ensuring proper parsing and rendering of dynamic data. These delimiters help instruct Jinja on how to process specific sections of the code.

Variables in Jinja

Variables in Jinja are used to store and access dynamic data. They are automatically typed, allowing for flexible use without requiring manual type declarations. Meaningful variable names contribute to clearer, more maintainable templates, reducing potential for errors.

{% set totalOrders = 150 %}
{{ totalOrders }}

Output: 150

Variables can also be conditionally defined, enabling more tailored content:

{% set displayName = user.first_name | title if user.first_name else "SnapApp Invalid User" %}

Variable data types

Jinja supports a variety of data types commonly used in web applications. Understanding these types allows for effective manipulation of variables within SnapApp.

Jinja allows conditional logic to be embedded in templates, enhancing the ability to dynamically adjust output based on variable states.

{% if project.status == 'pending' %}
  {{ "Project is pending." }}
{% elif project.status == 'deal qualified' %}
  {{ "Order has qualified the deal." }}
{% else %}
  {{ "Order is complete." }}
{% endif %}

Expressions

Expressions in Jinja provide the means to perform calculations, make comparisons, and manipulate data. Built on familiar Python syntax, they are intuitive and powerful for creating responsive content in SnapApp templates.

• Math Operators

• + Addition

• - Subtraction
• * Multiplication
• / Division
• // Integer division, rounding down. e.g. 20 // 7 returns 2.

• % Modulus (remainder of division). For instance, 11 % 7 returns 4.

• Comparison Operators

• == Checks for equality.

• != Checks for inequality.
• > Greater than comparison.
• >= Greater than or equal to.
• < Less than comparison.

• <= Less than or equal to.

• Logical Operators

• and Boolean AND operator.

• or Boolean OR operator.
• not Boolean negation.

Other Operators

• in : This operator checks whether a value exists within a sequence (like a list or dictionary). It evaluates based on keys in dictionaries.

Jinja {{ 'status' in order }} {# Checks if 'status' key exists in the order dictionary #}

• is : The is operator applies various tests to validate data, such as determining if a variable is defined or of a certain type.

Jinja {{ order.total is number }} {# Checks if the total is a number #}

• ~ : The ~ (read as “tilde”) operator concatenates operands, converting them into strings before joining them.

Jinja {{ 'Total: ' ~ order.total }} {# Produces "Total: 500" if order.total is 500 #}

Jinja Data Structures

In SnapApp, Jinja offers several core data structures that allow for flexible and dynamic template creation. Lists, tuples, and dictionaries are key elements, enabling the manipulation and organization of data for rendering dynamic content efficiently.

• Lists : A list is a mutable, ordered collection of items that can hold diverse data types without requiring prior declaration. Lists in Jinja are ideal for managing sequences of objects or values, allowing for flexible additions, removals, and retrieval of data.

How to initialize and access items in a list?

To define a list in Jinja, use the following syntax:

{% set sampleList = [10, 20, 30, 40, 50] %}

This creates a list containing the numbers 10 through 50. An empty list can be initialized as:

{% set emptyList = [] %}

Lists are indexed, meaning each item in the list can be accessed by its position. The first element in any list is always at index 0, the second at index 1, and so on. For instance, in the list below:

{% set alphaList = ['X', 'Y', 'Z', 'A'] %}

• X is at index 0,
• A is at index 3.

To retrieve an item, use the index:

{{ alphaList[2] }}  {# Returns 'Z' #}

Adding and removing items from a list

Lists in Jinja allow for dynamic changes, such as appending or removing elements.

Appending Elements: To add an item to an existing list, use the append method.

{% set myList = [2, 4, 6] %}
{% append 8 to myList %}

This adds 8 to the end of myList, resulting in [2, 4, 6, 8].

Removing Elements: Use the pop() method to remove elements from a list. The method can be used with or without an index.

{% set temp = myList.pop(1) %}  {# Removes the second item in the list #}

Example:

{% set myList = [100, 200, 300, 400] %}
{% set temp = myList.pop(2) %}  {# Removes 300 from the list #}
{{ myList }}  {# Outputs [100, 200, 400] #}

To find an element’s index, use the index() function:

{% set myIndex = myList.index(400) %}

• Tuples : Tuples, similar to lists, are ordered collections but are immutable—once created, they cannot be changed. Tuples are often used for fixed data that should remain constant throughout template rendering.

How to create and access Tuples

To define a tuple:

{% set sampleTuple = ('SnapApp', 'is', 'Cool') %}

Elements within a tuple can be accessed via their index, just like lists:

{{ sampleTuple[1] }}  {# Returns 'is' #}

A tuple with a single element requires a trailing comma:

{% set singleItemTuple = ('SnapApp',) %}

Example:

{% set pageData = [] %}
{% append ('home.html', 'Home Page') to pageData %}
{% append ('about.html', 'About SnapApp') to pageData %}
{{ pageData[1][1] }}  {# Outputs 'About SnapApp' #}

• Dictionaries : Dictionaries are collections of key-value pairs, where each key is unique and mapped to a corresponding value. In SnapApp, dictionaries are particularly useful for storing structured data such as customer information, settings, or configuration parameters.

How to define and access Dictionaries?

To create a dictionary:

{% set customerInfo = {"Name": "Alex", "Role": "Administrator"} %}

Access values by referencing their keys:

{{ customerInfo["Name"] }}  {# Outputs 'Alex' #}

Keys in dictionaries can be strings, numbers, or None. Values can be any data type, including other dictionaries, lists, or tuples.

{% set productDetails = {"Product": "Laptop", "Price": 1500, "Stock": 30} %}
{{ productDetails["Product"] }}  {# Returns 'Laptop' #}

Jinja Filters

In SnapApp, filters are a powerful tool that can be used to modify data output dynamically within templates. Filters are applied to variables, allowing content transformations without modifying the original data source.

• Filter Syntax: Filters are applied by using the pipe (|) symbol, followed by the name of the filter. The filter modifies the variable it is applied to. For instance, to convert a customer’s name to uppercase:

{{ customer["name"] | upper }}

This will convert the customer’s name to uppercase. The pipe symbol is an intuitive way to express “apply this filter to the variable.”

Filters that require additional parameters take arguments within parentheses, as demonstrated below:

{{ "product" | replace('p', 'b') }}

This replaces all occurrences of ‘p’ with ‘b’, resulting in the output broduct.

• Chaining Filters : Multiple filters can be applied to a variable in sequence. Filters are evaluated left to right, provided that the output of one filter is a valid input for the next.

Example

{{ "apple" | upper | replace('P', 'b') }}

Output: AbbLE

{{ "apple" | replace('p', 'b') | upper }}

Output: ABBLE

Global Variables in Jinja

Campaigns and Projects have variables. Variables such as ID and name can be used for personalization in campaigns.

• Project Level:
• {{ project[‘id’] }} - Returns the project ID.
• {{ project[‘name’] }} - Returns the project name.
• Scenario, Email Campaign :
• {{ scenario[‘id’] }} - Fetches the unique ID of the scenario or email campaign.
• {{ scenario[‘name’] }} - Retrieves the name of the scenario or email campaign.
• Scenario Node
• {{ action[‘id’] }} - Gets the ID of the action node within the scenario.
• {{ action[‘name’] }} - Returns the name of the action node or email campaign.
• Banner
• {{ banner[‘id’] }} - Returns the banner ID.
• {{ banner[‘name’] }} - Provides the banner name.
• {{ banner[‘variant’][‘id’] }} - Retrieves the ID of the banner variant.
• {{ banner[‘variant’][‘name’] }} - Returns the variant name.
• Experiments
• {{ experiment[‘id’] }} - Fetches the ID of the experiment.
• {{ experiment[‘name’] }} - Returns the name of the experiment.
• {{ experiment[‘variant’][‘id’] }} - Retrieves the variant ID of the experiment.
• {{ experiment[‘variant’][‘name’] }} - Provides the variant name of the experiment.
• Tag manager
• {{ tag[‘id’] }} - Returns the tag ID.
• {{ tag[‘name’] }} - Retrieves the name of the tag.

Technical Expressions

The following expressions are more technical and may be useful in specific scenarios:

• sent_timestamp | from_timestamp: Converts a Unix timestamp into a human-readable format.
• api_base_url: Returns a URL to an API path.
• public_base_url: Returns a URL to a public app-based resource.
• random_bytes(length) | hexencode: Generates a random byte string of the specified length and encodes it in hexadecimal.
• random_bytes(length) | b64encode: Generates a random byte string of the specified length and encodes it in Base64.

Functions on Data Types

Jinja Blocks

Jinja code blocks, defined using the syntax {% blocktype %} … {% endblocktype %}, serve as essential organizational and semantic elements within templates. They enhance code readability and modularity by grouping related code into distinct functional blocks. While Jinja supports eight block types, template importing is currently not implemented, rendering the block block type less practical.

Block Types

• Set

  • If Blocks: The if block enables conditional rendering based on boolean expressions. It includes elif (else if) and else clauses for additional conditions and default behavior. The block is terminated with {% endif %}.

jinja {# If block number one #} {% if 1 < 1 %} One is less than one. {% elif 1< 2 %} One is less than two {% else %} one is greater or equal to two {% endif %}

Output: one is less than two

Because the first condition fails, the second one gets evaluated. It evaluates to true, hence the statements following it gets rendered.

OR

Using Inline Expression

jinja {% set x = 'Project' if 13 is even else 'Task' %} {{ x }}

Output: Task

• For Blocks : The for block facilitates iteration over elements within iterables. It begins with {% for myItem in myIterable %}, where myIterable represents the iterable to be traversed. The subsequent lines define actions to be performed on each element. An optional {% else %} block can be included to handle cases where the iterable is empty. The loop is terminated with {% endfor %}

jinja {% for x in [] %} {{ 'Field' }} {%- else %} {{ 'Object' }} {% endfor %}

Output: Object

jinja {% for x in [1,2] %} {{ x }} {% else %} {{ 'Object' }} {% endfor %}

Output: 1 2

Recursive For Loop : Jinja supports recursive loop with ‘recursive’ flag at the end of for loop statement. Such for loops can use loop(List) function, which repeats the for loop with the recursive flag for each item in List. This allows you to effectively work with nested data structures.

jinja {% set x = [11, [21, 22], [ [23] ] ] %} {% for item in x recursive %} {% if item is iterable %} {{ loop(item) }} {% else %} {{ item ~ ' says hello from depth: ' ~ loop.depth }} {% endif %} {% endfor %}

Output: 11 says hello from depth: 1 21 says hello from depth: 2 22 says hello from depth: 2 23 says hello from depth: 3

For loop filtering : When using a for loop with the recursive flag, the recursive flag should be placed at the end of the statement, following the filter. This ensures that the filtering operation is applied correctly within the recursive context.

jinja {% for item in ['hello', [42], 13, 'world'] if (item is not string) recursive %} {{ loop(item) if item is iterable else item ~ ', depth: ' ~ loop.depth }} {% endfor %}

Output: 42, depth: 2 // 'hello' and 'world' were filtered out 13, depth: 1 // 42 is in extra List, therefore deeper

For blocks loop variables : When inside for loop, a special variable ‘loop’ is available with the properties listed in the following table.

• loop.cycle() : The loop.cycle() is a helper function that for each iteration n in current loop, returns n-th item in the provided sequence of arguments.

jinja {% for item in range(3) %} {{ loop.cycle('hello', 'SnapApp') }} // multiple calls within same loop iteration {{ loop.cycle('hello', 'SnapApp') }} // return item on same n-th position {% endfor %}

output: hello // 1st iteration hello SnapApp // 2nd iteration SnapApp hello // 3rd iteration hello

Macros

Macros in Jinja serve as callable code blocks, analogous to functions. They enhance code clarity and efficiency by encapsulating reusable logic.

Macros are defined using the syntax {% macro macroName(args) %} … {% endmacro %}. Parameters, referred to as arguments, are passed to the macro during invocation. This enables customization and flexibility in macro execution.

{% macro printMood(day, mood='happy') %}
{{ (day | title) ~ ', Weather feels ' ~ mood ~ '!' }}
{% endmacro %}
...
{% set currMood = 'amazing' %}
{% set currDay = 'today' %}
{{ printMood(currDay, currMood) }}

Output:
Today, Weather feels amazing!

Call

The call block, closely related to macros, provides a mechanism for passing content directly to a macro. When a call block is used within a macro invocation, its content is wrapped as a macro and assigned to the ‘caller’ argument. This allows for dynamic content injection and customization within macros.

To access the passed content within the macro, the caller() function is used. This enables the macro to incorporate the provided content into its execution logic, creating more flexible and adaptable templates.

{# This one throws error because argument caller was not declared #}
{% macro errorMacro(arg1) %}
{{ errorMacro.name ~ "'s arg1 is " ~ arg1 }}
{% endmacro %}
...
{% call errorMacro() %}
This is the content of the call block.
{% callend %}

{# This one works because argument caller was declared #}
{% macro workingMacro(arg1='', caller='') %}
{{ workingMacro.name ~ "'s args are " ~ arg1 ~ ' and "' ~ caller() ~ '"' }}
{% endmacro %}
...
{% call workingMacro() %}
This is the content of the call block.
{% endcall %}

Output:
workingMacro's args are and "
This is the content of the call block."

Raw

The raw block treats its content as literal strings, preventing Jinja syntax evaluation. This is particularly useful when you need to display actual Jinja syntax within the template output.

{% raw  %}
{% set x = 5 %}
{% endraw %}

Output:
"{% set x = 5 %}"

Jinja in SnapApp

In SnapApp, this Jinja feature can be used in Page Builder. To access Page Builder, see more details here

For example, the above code is to print the dynamic value of name and address using Jinja in Page Builder.

The above image shows dynamic the value of name and address field from the object along with the static value for a particular record ID.

Pre-conditions: Record must be present in the object in order to pass the value in Page.

SnapApp function in Jinja

In SnapApp, SnapApp function can also be used in Jinja in Page Builder. To create SnapApp function, see more details here

For example, the above code is to select all the contacts from CONTACTS table

The above image shows the values in the page iterated through the SnapApp Function.

Thank you for following these steps to configure your SnapApp components effectively If you have any questions or need further assistance, please don’t hesitate to reach out to our support team. We’re here to help you make the most out of your SnapApp experience.

For support, email us at snapapp@bluevector.ai