Variáveis e Modificadores

1. Como Utilizar Variáveis

Em contextos aplicáveis, os usuários podem utilizar variáveis usando a seguinte sintaxe:

{{ data.reference_do_campo }}

A referência do campo pode ser consultada na tela onde os campos são criados e sempre segue o formato snake_case baseado no nome do campo.

Exemplo

Se um usuário criou um campo chamado "Data de vencimento", a referência poderá ser: {{ data.data_de_vencimento }}

2. Estrutura das Variáveis Disponíveis para Itens

Os usuários podem utilizar as seguintes variáveis quando existe um contexto de item:

Dentro de data, estarão os campos personalizados, como:

• {{ data.campo_01 }}
• {{ data.campo_02 }}

3. Como Criar Expressões com Cálculos Matemáticos

O ENSPACE oferece duas formas de realizar operações matemáticas com variáveis. Ambas funcionam perfeitamente — escolha a que preferir.

💡 Dica: Se você está começando, use a Forma Recomendada. Ela é mais fácil de ler e escrever.

3.1. Forma Recomendada (Mais Simples)

Use operadores aritméticos padrão diretamente dentro da função math():

math({{data.campo_01}} + {{data.campo_02}})

Operadores Suportados:

• + (Adição)
• - (Subtração)
• * (Multiplicação)
• / (Divisão)

Exemplos Práticos:

• Soma de dois valores:math({{data.valor_a}} + {{data.valor_b}})
• Subtração:math({{data.total}} - {{data.desconto}})
• Cálculo de média:math(({{data.nota_1}} + {{data.nota_2}} + {{data.nota_3}}) / 3)
• Cálculo de área:math({{data.largura}} * {{data.altura}})

3.2. Forma Alternativa (com Funções Nomeadas)

Você também pode usar funções específicas para cada operação:

math(sum({{data.campo_01}}, {{data.campo_02}}))

Funções Disponíveis:

• sum(): para adição
• subtract(): para subtração
• multiply(): para multiplicação
• divide(): para divisão

3.3. Tabela de Comparação entre as Formas

3.4. Regras Importantes para Operações Matemáticas

⚠️ Uso de Parênteses

Utilize parênteses para controlar a ordem das operações (precedência). Para calcular uma média, por exemplo, você deve somar todos os valores primeiro e depois dividir:

• ✅ Correto: math(({{data.valor_1}} + {{data.valor_2}} + {{data.valor_3}}) / 3)
• ❌ Errado: math({{data.valor_1}} + {{data.valor_2}} + {{data.valor_3}} / 3)
  • Neste caso, apenas o valor_3 seria dividido por 3.

⚠️ Manter as Chaves Duplas

Sempre mantenha {{ }} em volta dos campos para que o sistema injete os valores corretamente antes do cálculo.

• ✅ Correto: math({{data.preco}} * {{data.quantidade}})
• ❌ Errado: math({data.preco} * {data.quantidade})

💡 Combinação de Operadores

Você pode combinar múltiplos operadores na mesma expressão:

math(({{data.preco}} * {{data.quantidade}}) - {{data.desconto}})

4. Como Aplicar Formatação aos Dados

Após criar suas expressões, você pode formatar como os valores serão exibidos. O ENSPACE oferece duas sintaxes diferentes para formatação: Sufixo e Função. Ambas produzem os mesmos resultados.

💡 Pense assim: Use Sufixo para formatar um campo sozinho. Use Função quando precisar fazer cálculos ANTES de formatar o resultado, ou quando tiver muitos parâmetros de formatação.

4.1. Sintaxe com Sufixo (__mod[])

Esta forma é ideal para formatação simples de campos individuais.

Estrutura Básica:

{{ variavel__mod[format?parametro1=valor1&parametro2=valor2] }}

Detalhamento da Sintaxe:

• __mod[]: Indica que uma modificação será aplicada.
• format: Define o tipo de modificador.
• ?: Inicia a lista de parâmetros.
• parametro=valor: Define um parâmetro específico e seu valor correspondente.
• &: Separa múltiplos parâmetros.

Exemplo: Formatação de Moeda

{{ data.valor_total__mod[format?type=number&n_style=currency&n_currency=USD] }}

🔹 Saída esperada: $10.00

4.2. Sintaxe com Função format()

Esta forma é recomendada quando você precisa:

• Formatar o resultado de cálculos ou expressões complexas.
• Aplicar múltiplos parâmetros de formatação de forma organizada.
• Trabalhar com configurações de formatação mais extensas.

Estrutura Básica:

format(VALOR, {"parametro": "valor"})

Argumentos da Função:

A função aceita dois argumentos principais:

• Valor: A variável, o resultado de uma expressão (ex: math()), ou qualquer dado que precise ser formatado.
• Configurações: Um objeto JSON contendo os parâmetros de formatação.

Exemplos Práticos:

• Formatação de Data:
  format({{data.data_vencimento}}, {"type": "date", "locale": "pt-BR", "d_style": "full", "dt_style": "short"}):br 🔹 Saída: terça-feira, 8 de março de 2025 14:30
• Formatação de Moeda:
  format({{data.preco}}, {"type": "number", "locale": "pt-BR", "n_style": "currency", "n_currency": "BRL", "n_minimumFractionDigits": 2}):br 🔹 Saída: R$ 1.250,50
• Formatação de Média com Cálculo:
  format(math(({{data.campo_01}} + {{data.campo_02}} + {{data.campo_03}} + {{data.campo_04}}) / 4), {"type": "number", "locale": "pt-BR", "n_style": "decimal", "n_maximumFractionDigits": 0, "n_minimumFractionDigits": 0}):br 🔹 Calcula a média dos quatro campos e exibe sem casas decimais.
• Formatação de Lista:
  format({{data.produtos}}, {"type": "list", "value_path": "nome", "l_separator": " | "}):br 🔹 Saída: Produto A | Produto B | Produto C

4.3. Tabela de Equivalência entre as Sintaxes

4.4. Vantagens de Cada Sintaxe

Sufixo (__mod[]):

• Sintaxe mais curta e direta: Ideal para inserções rápidas.
• Campos simples: Perfeito para formatações básicas de um único campo.
• Legibilidade: Mais fácil de ler em casos de uso cotidianos.

Função format():

• Aninhamento: Permite a combinação de funções (uma dentro da outra).
• Organização: O formato JSON facilita a visualização de configurações complexas.
• Extensibilidade: Ideal quando você possui muitos parâmetros de formatação.
• Poder de Processamento: Melhor para trabalhar com cálculos, transformações e formatações avançadas.
• Precisão: O sistema trata o valor corretamente (tipo de dado) antes de aplicar o formato.

📘 Guia de Termos Técnicos

• Query string: Formato de texto que lista parâmetros separados por &, similar ao que aparece em URLs após o símbolo ?.
• Aninhamento: Combinação de funções, uma dentro da outra. Exemplo: format(math(...)) — a função math() está aninhada dentro de format().
• JSON: Formato de texto estruturado que usa chaves {} e aspas "" para organizar informações de forma padronizada.
• Sintaxe funcional: Estilo de escrita que usa funções (ex: format()) em vez de sufixos (ex: __mod[]).

5. Parâmetros de Formatação Disponíveis

Independentemente da sintaxe escolhida (Sufixo ou Função), os parâmetros disponíveis são os mesmos.

5.1. Parâmetros Gerais

5.2. Parâmetros para type="date" (Datas)

📅 Use estes parâmetros quando quiser exibir datas de forma mais legível para seus usuários.

Exemplos Práticos:

• Data Completa:
  {{ data.custom_due_date__mod[format?type=date&d_style=full] }}:br 🔹 Saída: terça-feira, 8 de março de 2025
• Data e Hora Médias:
  {{ data.server_time__mod[format?type=date&d_style=medium&dt_style=short] }}:br 🔹 Saída: 8 de mar. de 2025 13:30
• Data Curta com Hora Curta:
  {{ data.server_time__mod[format?type=date&d_style=short&dt_style=short] }}:br 🔹 Saída: 08/03/2025, 13:30

5.3. Parâmetros para type="number" (Números e Moedas)

💰 Use estes parâmetros para exibir valores monetários, percentuais ou números com formatação específica.

Exemplos Práticos:

• Formatação de Moeda (Dólar):
  {{ data.preco__mod[format?type=number&n_style=currency&n_currency=USD] }}:br 🔹 Saída esperada: $10.00
• Formatação de Percentual com Casas Decimais:
  {{ data.taxa__mod[format?type=number&n_style=percent&n_minimumFractionDigits=2] }}:br 🔹 Se o valor for 0.075, a saída será: 7,50%
• Uso de Multiplicador (Conversão de Unidades):
  {{ data.tempo__mod[format?type=number&n_multiplier=60] }}:br 🔹 Se o valor for 2, a saída será: 120 (ex: converte horas para minutos)
• Usando a Sintaxe de Função:
  format({{data.preco}}, {"type": "number", "locale": "pt-BR", "n_style": "currency", "n_currency": "BRL"}):br 🔹 Saída esperada: R$ 10,00

5.4. Parâmetros para type="text" (Texto)

📝 Use estes parâmetros para limitar o tamanho de textos longos.

Exemplo:

{{ data.descricao__mod[format?type=text&t_length=20&t_suffix="..."] }}

🔹 Se o texto for "Este é um exemplo de texto muito longo", a saída será: "Este é um exemplo..."

5.5. Parâmetros para type="list" (Listas)

📋 Use estes parâmetros para exibir múltiplos itens de forma organizada.

📢 Importante: value_path é obrigatório para type=list, pois ele determina de onde os valores serão extraídos dentro dos itens da lista.

Exemplo:

{{ data.produtos__mod[format?type=list&value_path=name&l_separator=", "] }}

Se a lista contiver:

[
  { "name": "Produto A" },
  { "name": "Produto B" },
  { "name": "Produto C" }
]

🔹 Saída esperada: Produto A, Produto B, Produto C

5.6. Parâmetros para type="object" (Objetos JSON)

🔧 Use estes parâmetros para trabalhar com dados estruturados complexos.

Exemplo:

{{ data.detalhes__mod[format?type=object] }}

Se o objeto contiver:

{
  "nome": "João",
  "idade": 30
}

🔹 Saída esperada: {"nome":"João","idade":30}

6. Como Usar o Modificador transformText

O modificador transformText permite realizar transformações no formato do texto. Ele funciona apenas com a sintaxe de sufixo e aceita uma lista de opções dentro do parâmetro options.

6.1. Opções Disponíveis

6.2. Exemplos de Uso

• Converter para maiúsculas:
  {{ data.nome_cliente__mod[transformText?options=uppercase] }}:br 🔹 Entrada: "joão silva" → Saída: "JOÃO SILVA"
• Aplicar múltiplas transformações: (Remove espaços extras e capitaliza a primeira letra)
  {{ data.nome_cliente__mod[transformText?options=trim&options=capitalize] }}:br 🔹 Entrada: " maria santos " → Saída: "Maria santos"
• Remover acentos e converter para kebab-case:
  {{ data.titulo__mod[transformText?options=deburr&options=kebabCase] }}:br 🔹 Entrada: "Página Inicial" → Saída: "pagina-inicial"
• Gerar um slug a partir de um título:
  {{ data.titulo__mod[transformText?options=slugify] }}:br 🔹 Entrada: "Como Usar Variáveis?" → Saída: "como-usar-variaveis"

7. Guia Rápido de Decisão

Use este guia para decidir rapidamente qual abordagem utilizar:

8. Erros Comuns a Evitar

⚠️ Quantidade Incorreta de Chaves

O erro mais comum ao trabalhar com variáveis é usar uma quantidade errada de chaves.

• ❌ Errado:
  • { data.campo } (Apenas uma chave)
  • {{{ data.campo }}} (Três chaves)
  • {{ data.campo } (Esqueceu de fechar)
• ✅ Correto:
  • {{ data.campo }} (Sempre duas chaves de cada lado)

⚠️ Esquecer de Fechar Parênteses

Ao usar funções como math() e format(), é fácil esquecer de fechar todos os parênteses, especialmente em funções aninhadas.

• ❌ Errado: format(math({{a}} + {{b}}), {"type":"number"}
• ✅ Correto: format(math({{a}} + {{b}}), {"type":"number"})

💡 Dica: Conte os parênteses de abertura ( e fechamento ) — eles devem sempre estar em igual quantidade.

⚠️ Esquecer Aspas no JSON

Ao usar a sintaxe de função format(), todos os nomes de parâmetros e valores de texto precisam estar entre aspas duplas.

• ❌ Errado:
  • format({{data.valor}}, {type: number}) (Faltam aspas nos nomes e valores)
  • format({{data.valor}}, {"type": 'number'}) (Aspas simples não são suportadas)
• ✅ Correto:
  • format({{data.valor}}, {"type": "number"}) (Aspas duplas em tudo)

⚠️ Misturar Sintaxes

Não é possível combinar a sintaxe de sufixo com a sintaxe de função no mesmo campo.

• ❌ Errado:{{ data.valor__mod[format?type=number] }}({"n_style":"currency"})
• ✅ Correto (Escolha uma das duas):
  • Opção 1 (Sufixo): {{ data.valor__mod[format?type=number&n_style=currency] }}
  • Opção 2 (Função): format({{data.valor}}, {"type":"number", "n_style":"currency"})

⚠️ Esquecer o value_path em Listas

Ao formatar listas (type=list), o parâmetro value_path é obrigatório.

• ❌ Errado:{{ data.produtos__mod[format?type=list&l_separator=", "] }}
• ✅ Correto:{{ data.produtos__mod[format?type=list&value_path=name&l_separator=", "] }}

⚠️ Ordem de Operações sem Parênteses

Em expressões matemáticas complexas, a ausência de parênteses pode gerar resultados inesperados devido à precedência aritmética.

• ❌ Errado (para calcular média):math({{data.a}} + {{data.b}} + {{data.c}} / 3):brIsso divide apenas c por 3, e depois soma o resultado com a e b.
• ✅ Correto:math(({{data.a}} + {{data.b}} + {{data.c}}) / 3):brIsso soma todos os valores primeiro e, em seguida, divide o total por 3.