Helpers do Handlebars

Esta página lista os helpers personalizados do Handlebars disponíveis para uso nos templates, agrupados por tipo, com uma descrição do que cada um faz e um exemplo prático.

Conteúdo & Strings

concat

Concatena qualquer número de argumentos numa única string.

{{concat "Olá, " "Mundo" "!"}}

> Olá, Mundo!

format

Formata um valor de acordo com um determinado tipo. Atualmente suporta "number", usando Intl.NumberFormat com um objeto de opções opcional (por exemplo, locale, número mínimo/máximo de dígitos decimais). Usa o locale pt-PT por padrão quando nenhum é especificado.

{{format "number" 1234.5}}

> 1 234,5

{{format "number" 1234.5 '{"locale":"en-US"}'}}

> 1,234.5

includes

Verifica se arg1 contém arg2. Funciona com strings e arrays (arrays com um único elemento são desembrulhados antes da comparação). Passe true como terceiro argumento para uma comparação sem distinção entre maiúsculas e minúsculas. Devolve false se qualquer um dos argumentos for null.

{{includes "Olá Mundo" "Mundo"}}

> true

{{includes "Olá Mundo" "mundo" true}}

> true

markdown

Converte uma string em formato Markdown para HTML. Se não for fornecido texto, devolve uma string vazia.

{{markdown "**Importante:** por favor reveja."}}

> <p><strong>Importante:</strong> por favor reveja.</p>

pasteInRm

Constrói um payload JSON usado para colar automaticamente valores de campos nas instâncias do RecordM. Aceita uma lista alternada de pares nome/valor de campo (chave1 valor1 chave2 valor2 ...) e devolve um objeto JSON convertido em string, descrevendo os campos e a opção auto-paste-if-empty. Devolve uma string vazia se não forem fornecidos pares.

{{pasteInRm "nome" "João Silva" "idade" 30}}

> {"opts":{"auto-paste-if-empty":true},"fields":[{"value":"João Silva","fieldDefinition":{"name":"nome"}},{"value":30,"fieldDefinition":{"name":"idade"}}]}

replace

Substitui a primeira ocorrência de oldValue por newValue dentro de uma string. Devolve uma string vazia se word não for uma string.

{{replace "Olá Mundo" "Mundo" "Handlebars"}}

> Olá Handlebars

startsWith

Verifica se arg1 (uma string) começa com arg2.

{{#if (startsWith "Sr. Silva" "Sr.")}}
  Saudação formal
{{/if}}

> Saudação formal

Listas & Arrays

createVar

Define varsObject[varName] = value, permitindo guardar um valor num objeto partilhado para reutilização posterior dentro de um template. Não devolve nenhum valor.

{{createVar minhasVars "total" 42}}
{{minhasVars.total}}

> 42

every

Percorre as chaves/valores de um objeto ou array, avaliando uma expressão JavaScript (evalCode) para cada elemento, e devolve true apenas se todos os elementos satisfizerem a expressão, caso contrário devolve false. Dentro de evalCode, key e val referem-se à chave e ao valor do elemento atual.

{{every utilizadores "val.idade >= 18"}}

> true

Dado utilizadores = [{"idade": 20}, {"idade": 25}]

filter

Percorre as chaves/valores de um objeto ou array, avaliando uma expressão JavaScript (evalCode) para cada elemento, e devolve um novo objeto/array contendo apenas os elementos para os quais a expressão é verdadeira. Dentro de evalCode, key e val referem-se à chave e ao valor do elemento atual. Devolve um array vazio se nada corresponder.

{{filter utilizadores "val.idade >= 18"}}

> [{"idade": 20}, {"idade": 30}]

Dado utilizadores = [{"idade": 15}, {"idade": 20}, {"idade": 30}]

listFilter

Filtra uma lista de objetos, mantendo apenas aqueles cujo field corresponde a value (funciona tanto com valores diretos como com valores de campo do tipo array, comparando como strings). Se first for "true", apenas a primeira correspondência é devolvida. Devolve null se nada corresponder.

{{listFilter tickets "status" "open"}}

> [{"status": "open"}]

Dado tickets = [{"status": "open"}, {"status": "closed"}]

{{listFilter tickets "status" "open" "true"}}

> [{"status": "open"}]

listSort

Ordena um array, opcionalmente por um determinado campo, em ordem ascendente ("asc") ou descendente (padrão).

{{listSort tickets "prioridade" "asc"}}

> [{"prioridade": 1}, {"prioridade": 2}, {"prioridade": 3}]

Dado tickets = [{"prioridade": 3}, {"prioridade": 1}, {"prioridade": 2}]

lookupWithDefault

Procura key em obj e devolve o seu valor, ou defaultValue se o valor for falso/inexistente.

{{lookupWithDefault utilizador "apelido" "N/D"}}

> N/D

Dado utilizador = {"nome": "João"} (sem apelido)

some

Percorre as chaves/valores de um objeto ou array, avaliando uma expressão JavaScript (evalCode) para cada elemento, e devolve true logo que um elemento satisfaça a expressão, caso contrário devolve false. Dentro de evalCode, key e val referem-se à chave e ao valor do elemento atual.

{{some utilizadores "val.idade < 18"}}

> true

Dado utilizadores = [{"idade": 20}, {"idade": 15}]

times

Helper de bloco que repete o seu conteúdo n vezes, fornecendo ao bloco o índice da iteração atual (a começar em 1).

{{#times 3}}
  Item {{this}}
{{/times}}

> Item 1 Item 2 Item 3

Lógica & Comparação

and

Devolve o AND lógico de dois argumentos.

{{#if (and estaAtivo estaVerificado)}}
  Conta aprovada
{{/if}}

> Conta aprovada

Dado estaAtivo = true e estaVerificado = true

eq

Verifica se dois valores são iguais. Se ambos os argumentos forem arrays, compara os seus primeiros elementos como arrays; caso contrário, faz uma comparação simples (==).

{{#if (eq status "open")}}
  Ticket está aberto
{{/if}}

> Ticket está aberto

Dado status = "open"

greaterOrEq

Helper de bloco. Renderiza o bloco se arg1 >= arg2 (comparação numérica), caso contrário renderiza o bloco inverso.

{{#greaterOrEq 75 70}}
  Aprovado
{{else}}
  Reprovado
{{/greaterOrEq}}

> Aprovado

greaterThan

Devolve true se arg1 > arg2 (comparação numérica; arg1 assume 0 por padrão se for falso).

{{#if (greaterThan 75 70)}}
  Acima do limite
{{/if}}

> Acima do limite

lesserOrEq

Helper de bloco. Renderiza o bloco se arg1 <= arg2 (comparação numérica), caso contrário renderiza o bloco inverso.

{{#lesserOrEq 40 50}}
  Baixo
{{else}}
  Alto
{{/lesserOrEq}}

> Baixo

lessThan

Devolve true se arg1 < arg2 (comparação numérica; arg1 assume 0 por padrão se for falso).

{{#if (lessThan 40 50)}}
  Abaixo do limite
{{/if}}

> Abaixo do limite

not

Devolve a negação lógica do seu argumento.

{{#if (not estaEscondido)}}
  Visível
{{/if}}

> Visível

Dado estaEscondido = false

or

Devolve o OR lógico de dois argumentos.

{{#if (or temPapelAdmin temPapelEditor)}}
  Pode editar
{{/if}}

> Pode editar

Dado temPapelAdmin = false e temPapelEditor = true

Matemática

add

Soma dois valores numéricos. arg1 assume 0 por padrão se for falso.

{{add 5 3}}

> 8

div

Divide a por b, devolvendo um resultado decimal. Devolve 0 se qualquer um dos argumentos for falso ou zero.

{{div 10 4}}

> 2.5

max

Devolve o maior de dois números.

{{max 10 20}}

> 20

min

Devolve o menor de dois números.

{{min 10 20}}

> 10

multiply

Multiplica arg1 por arg2. Ambos assumem 0 por padrão se forem falsos.

{{multiply 6 7}}

> 42

subtract

Subtrai arg2 a arg1. Ambos assumem 0 por padrão se forem falsos.

{{subtract 10 4}}

> 6

Datas & Tempo

compareDates

Compara duas datas (aceitando strings de data ou timestamps), ignorando a hora do dia. Devolve -1 se a primeira data for anterior, 1 se for posterior, ou 0 se caírem no mesmo dia.

{{compareDates "2024-01-01" "2024-01-02"}}

> -1

compareDateTimes

Igual a compareDates, mas também considera as horas e minutos ao determinar a igualdade.

{{compareDateTimes "2024-01-01T10:00:00" "2024-01-01T09:00:00"}}

> 1

dateInfo

Dada uma string de data e uma palavra-chave, devolve um valor de data derivado. Palavras-chave suportadas: LastDateOfYear, FirstDateOfYear, LastDateOfMonth, FirstDateOfMonth, MonthText, FullDateText, WeekDayText, FullYear, MonthIndexAt1, FirstEpochOfYear, LastEpochOfYear, FirstEpochOfMonth, LastEpochOfMonth, FirstEpochOfDay, LastEpochOfDay. Devolve uma string vazia se não for fornecida uma string de data, ou undefined para uma palavra-chave não reconhecida.

{{dateInfo "2024-03-15" "FirstDateOfMonth"}}

> 2024-03-01T00:00:00.000Z

A hora exata depende do fuso horário do servidor.

{{dateInfo "2024-03-15" "MonthText"}}

> Mar

dateInfoTimestamp

Dado um timestamp Unix e uma palavra-chave, devolve uma string de data/hora formatada. Palavras-chave suportadas: FullDateTime, FullDate, FullTime, FullWithWeekDay, WeekDay. Devolve "No date." se não for fornecido nenhum timestamp ou se a palavra-chave não for reconhecida.

{{dateInfoTimestamp 1710500000000 "FullDate"}}

> 15/03/2024

O formato exato depende do locale e fuso horário do browser.

nextPage

Avança uma data ou número para a frente por um determinado tamanho de passo, útil para controlos de paginação/navegação. Para datas, size é uma string como "1d", "2w", "1m" ou "1y" (dias/semanas/meses/anos). Para números, size é somado diretamente. Um limit opcional limita o resultado para que não vá além de uma determinada data ou número.

{{nextPage "2024-01-15" "1m"}}

> 2024-02-15T00:00:00.000Z

{{nextPage 10 10 100}}

> 20

prevPage

Igual a nextPage, mas move para trás em vez de para a frente.

{{prevPage "2024-01-15" "1m"}}

> 2023-12-15T00:00:00.000Z

{{prevPage 10 10 0}}

> 0

today

Devolve a data/hora atual como uma string ISO 8601.

{{today}}

> 2026-08-07T09:15:00.000Z

todayTimestamp

Devolve a data/hora atual como um timestamp Unix em milissegundos.

{{todayTimestamp}}

> 1786100514408

Ambiente & Contexto

isNaked

Devolve true se a aplicação estiver atualmente em execução no modo "naked".

{{#if (isNaked)}}
  Interface simplificada
{{/if}}

> Interface simplificada

Mostrado quando a aplicação está em modo naked.

screenMd

Devolve true se a largura atual do viewport for 768px ou menos.

{{#if (screenMd)}}
  Mostrar menu mobile
{{/if}}

> Mostrar menu mobile

Mostrado quando o viewport tem 768px ou menos de largura.

screenSm

Devolve true se a largura atual do viewport for 640px ou menos.

{{#if (screenSm)}}
  Mostrar layout compacto
{{/if}}

> Mostrar layout compacto

Mostrado quando o viewport tem 640px ou menos de largura.