Pular para o conteúdo principal

Conceitos Básicos de Jinja

A linguagem Jinja assim como a maioria das linguagens de templates, permite através de marcações específicas em um texto, a definição de expressões que são interpoladas pela engine para renderizar o resultado final.

As marcações Jinja em um texto podem ser:

  • {{ ... }}, para expressões que serão renderizadas;
  • {% ... %}, para estruturas de controle;
  • {# ... #}, para comentários.

Confira um exemplo simples de um template Jinja:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Webpage</title>
</head>
<body>
    {# print a Hello message for each name in names list #}
    {% for name in names %}
    <h1>Hello {{ name }}!</h1>
    {% endfor %}
</body>

Quando a variável name receber os valores ['João', 'Maria'], a renderização do template deve retornar o seguinte resultado:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Webpage</title>
</head>
<body>
    <h1>Hello João!</h1>
    <h1>Hello Maria!</h1>
</body>

Quando a variável name receber os valores ['João', 'Maria'], a renderização do template deve retornar o seguinte resultado:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Webpage</title>
</head>
<body>
    <h1>Hello João!</h1>
    <h1>Hello Maria!</h1>
</body>

Em resumo, ao serem avaliadas pela engine de templates da StackSpot, as expressões e estruturas de controle do Jinja são avaliadas para produzir o resultado final.

Expressões Jinja

As expressões devem ser colocadas entre {{ ... }}, isso indica que algo que deve ser renderizado pelo Jinja. As expressões podem conter valores literais, variáveis, cálculos e expressões complexas.

Para saber mais sobre todas as expressões Jinja, consulte a documentação do Jinja.

Filtros

As variáveis podem ser transformadas através de filtros. A sintaxe para aplicar um filtro em uma variável é:

{{ variavel | filtro }}

É possível aplicar mais de um filtro encadeando vários pipes (| ), conforme o exemplo:

{{ variavel | filtro1 | filtro2 }}

No exemplo acima o valor da variável é modificado pelo filtro1 e depois modificado pelo filtro2.

Confira o exemplo do filtro padrão capitalize:
Esse filtro converte o nome informado para o formato onde, a primeira letra é maiúscula e as outras minúsculas.

{{ nome | capitalize }}

Para mais informações sobre os filtros padrões do Jinja, consulte a documentação do Jinja.

Você pode fornecer um terceiro argumento opcional "contador" (count), mas apenas as primeiras ocorrências de contagem serão substituídas:

# {{ "string value" |regex_replace("substring pattern", "replacement string") }}
{{ "Hello World"|regex_replace("Hello", "Goodbye") }}
    -> Goodbye World

# {{ "string value" |regex_replace("substring pattern", "replacement string", count) }}
{{ "aaathree"|replace("a", "two", 2) }}
    -> two, two, athree

Você pode usar variáveis que contenham o valor para ser substituído:

Considere que a variável hello_word possui o valor "dogs, cats, birds";

# {{ variable|regelex_replace('substring pattern', 'replacement string')}}
{{ hello_world|regex_replace('birds', 'humans') }}
    -> docs, cats, humans

A variável hello_word passa a ter o valor "dogs, cats, humans".

É possível usar no campo de substituição os grupos da expressão regular na string substituição:

Considere que a variável hello_word possui o valor 'burger';

# {{ string value or variable | regex_replace(define group pattern, replacement string group)}}
{{ hello_world|regex_replace('((\w+\s*)+)', 'cheese\1y') }}
    -> cheeseburger

A variável hello_word passa a ter o valor 'cheeseburger'.

  • from_json: Converte uma string no formato JSON em um dict python.

Considere a string JSON:

{
  "input1": "value1"
}

Para usar o dict do Python no JINJA, você deve acessá-lo da seguinte forma:

{% set my_dict = json_input | from_json %}
{{my_dict.input1}}

Estruturas de controle

As estruturas de controle presentes no Jinja são as if/elif/else/endif e for/else/endfor.

Usar a estrutura if/elif/else/endif

Os comandos da estrutura if/elif/else/endif permitem a definição de blocos que serão renderizados de acordo com uma condição. O exemplo ilustra a utilização de um bloco if para controlar a impressão de parte de um template:

{% if idade True %}
Aceita um drink?
{% elif idade >= 5 %}
Aceita um refrigerante?
{% else %}
Aceita um suco?
{% endif %}

No exemplo acima, é implementada uma lógica para determinar a mensagem que será impressa de acordo com o valor da variável idade.

Os operadores de comparação disponíveis no Jinja são:

  • ==: Compara os dois operandos retornando true se forem iguais.
  • !=: Compara os dois operandos retornando true se forem diferentes.
  • >: true se o operando à esquerda for maior que o operando à direita.
  • >=: true se o operando à esquerda for maior ou igual ao operando à direita.
  • <: true se o operando à esquerda for menor que o operando à direita.
  • <=: true se o operando à esquerda for menor ou igual ao operando à direita.

Os operadores lógicos podem ser usados nas expressões:

  • and: Retorna true se as expressões à esquerda e à direta forem verdadeiras.
  • or: Retorna true se uma das expressões for verdadeira.
  • not: Nega o resultado de uma expressão.
  • (expr): Agrupa expressões lógicas.

Os blocos elif e else são opcionais e pode-se usar mais de um bloco elif, caso necessário.

Usar a estrutura for/else/endfor

Os comandos da estrutura for/else/endfor permitem a definição de um bloco de repetição para cada elemento de uma lista conforme o exemplo:

{% for nome in nomes %}
Olá {{ nome }}!
{% else %}
Sem nomes informados!
{% endfor %}

No exemplo acima, para cada nome na lista de nomes nomes será renderizada uma linha com uma saudação para o nome informado.

Caso a lista de nomes esteja vazia será renderizado o conteúdo do bloco após o else.

O bloco else é opcional e pode ser omitido caso não seja necessário.

Próximos Passos