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 feitom no Handlebars.