Handlebars e Helpers

Introdução

Handlebars é uma linguagem de programação utilizada para trabalhar com templates.

Você pode entender um pouco mais sobre ele aqui:

https://handlebarsjs.com/

Todos os templates da Yourviews que utilizam HTML também utilizam o Handlebars.

Em seu uso mais simples, o Handlebars permite utilizar valores das Models. Por exemplo, ao exibir um review precisamos mostrar o total de avaliações coletadas. Esse totalizador está na model, dentro da variáveil "Total", conforme abaixo:

Helpers

Helpers são funções pré-definidas do Handlebars que facilitam a exibição dos templates. O helper mais básico é o condicional (if).

Helper - if

O "if" é o helper mais básico do Handlebars e está presente originalmente no framework. Seu uso segue o padrão:

{{#if CONDIÇÃO}} bloco exibido se a condição for verdadeira {{else}} bloco exibido se a condição for falsa {{/if}}

A condição é uma variável da Model que pode representar um valor booleano (true/false) ou existente/nulo.

Por exemplo, no código abaixo:

O trecho de HTML somente será exibido se o valor de Comparation.HasResult for igual a "true"

Helper - ifCond

O helper "if", padrão do Handlebars, não permite condicionais complexos, como "maior ou igual" ou "igual a". De fato, seu uso é restrito para condições com booleanos envolvidos.

Para condições mais complexas utilizamos o helper "ifCond".

Seu uso segue o padrão: {{#ifCond LadoEsquerdo "condição" LadoDireito}}

O LadoEsquerdo e o LadoDireito são as variáveis ou valores que se deseja validar a condição

A "condição" pode ser: '==', '!=', '>', '>=', '<', '<=' exatamente como utilizando em linguagens de programação.

Um exemplo comum do seu uso:

No exemplo acima, o condicional compara se o valor da variável "Category" é igual a 1.

Da mesma forma que o "if", pode-se utilizar o {{else}} para criar condição contrária.

Helper - with

Permite forçar o contexto para dentro de um objeto da model. Por exemplo: supondo que exista uma model:

Review

.IdReview

.User

..UserName

Para que seja possível utilizar a variável "UserName", é necessário utilizar Review.User.UserName. Para evitar a utilização constante da tipagem completa, pode-se utilizar o bloco {{#with Review.User}} e, dentro dele, utilizar diretamente {{UserName}}

Se, dentro desse bloco, for necessário utilizar o IdReview (que agora está fora do contexto), é necessário utilizar a notação {{../IdReview}}

Helper - each

O helper "each" é padrão do Handlebars. Ele permite iterar sobre uma lista (array) de items, como uma espécie de foreach.  Por ex:

No exemplo acima, o código HTML será exibido para cada review da lista ReviewList. Pode-se utilizar normalmente as variáveis de cada item do ReviewList.

Ao utilizar esse bloco é criado um contexto próprio. Dessa forma, para acessar variáveis fora desse contexto deve-se usar a notação ../

Helper**- times**

Atua como um loop for. Tem o formato {{#times contadorInicial contadorFinal incremento}}. O funcionamento é parecido com um for(var i = contadorInicial; i<contadorFinal; i+= incremento)

Helper - math

Permite fazer contas matemáticas entre dois valores. Tem o formato {{math valorDireta "OPERADOR" valorEsquerda}}.

Os operadores podem ser "+" , "-" , "*" , "/" , "ceil" , "floor"

Helper - timeago

Retorna a data informada com formato variável - "1 dia atrás", "3 anos atrás", etc.

Helper - substr

Trunca a string informada com a quantidade de caracteres informada e adicionada reticências ao final da mesma.

Helper - pluralize

Permite deixar duas versões da mesma string (plural e singular) a depender do valor informado.

{{pluralize Quantidade "avaliação" "avaliações"}}

No exemplo acima, se Quantidade for = 0, retorna no singular, caso contrário retorna no plural.

Helper - firstName

Se o valor informado contiver espaços, retorna apenas a primeira parte. Útil para retornar apenas o primeiro nome de um nome completo

Helper - firstLastName

Idêntico ao anterior, mas retorna também o último nome.

Helper - replace

Troca uma palavra (ou trecho) de uma string por outra palavra (ou trecho).

Helper - dateFormat

Formata uma data de conforme desejado. Utiliza a sintaxe do moment.js

Helper - viewMore

Permite truncar uma string no tamanho informado, além disso cria um "ver mais" que ao ser clicado permite visualizar todo o texto.

Helper - percent

Calcula o percentual de um valor

Helper - withNull

Idêntico ao "with" mas o bloco é renderizado mesmo se a Model informada for nula.

Helper - join

Dado um array de strings, permite concactená-los em apenas uma string separada pelo valor desejado.

Dessa forma, dada um objeto:

Review

.Preferences

..[Cabelo liso],[Cabelo seco]

Pode-se utilizar o "join" para exibir o array como uma coisa só. Dessa forma, utilizando: {{join Review.Preferences ","}}

Temos o retorno: Cabelo liso, Cabelo seco

Helper - superCond

Permite criar um condicional dentro de outro, evitando uso de vários "ifCond".

Ex: {{superCond Gender 'M' 'F' 'Avatar Masc' 'Avatar Fem' 'Avatar Indefinido'}}

Se o valor de "Gender" for "M" exibe "Avatar Masc". Se o valor for "F" exibe "Avatar Fem". Caso contrário exibe "Avatar indefinido"

Helper - capitalize

Faz com que a primeira letra de cada palavra fique em maiúsculo. O texto "nome sobrenome" se torna "Nome Sobrenome"

Helper - regexReplace

Faz a troca de uma string por outra baseada na Expressão Regular informada.

{{regexReplace '$TESTONE' '\$TESTONE' 'foo'}}

Helper - eachReverse

O mesmo que o "each" mas inverte a ordem do array

Helper - hasvalues

Retorna true ou false dependendo se o array informado contém ou não valores;

Helper - urlConcat

Concactena uma URL com uma querystring, utilizando apropriadamente o "?" ou "&" conforme necessário

Helper - stringLength

Retorna o tamanho da string informada

Helper - firstLastPartName

Retorna apenas o primeiro e o último nome de uma pessoa.

Helper - nameInitials

Retorna as iniciais do nome informado

Helper - contains

Informa se um texto está presente em uma frase.

Helper -  ifIn

Informa se um item está presente em um array

Helper - decimalFormat

Formata um número com as casas decimais informadas

Helper - getSize

Retorna quantos itens o array possui

Helper - include

O includeé um helper especial da Yourviews. Ele permite incluir um template dentro de outro.

No exemplo abaixo:

Estamos incluindo o template "reviewform_fileupload" no template atual (no caso, template de formulário de avaliação). Você pode visualizar esse template clicando no ícone de "novo" e informando o nome acima

IMPORTANTE: Esse helper especial requer o uso de três chaves ({{{ e }}}) ao invés de apenas duas, como é normalmente feit com no Handlebars.