Variáveis do HubL e sintaxe de macros

O HubL utiliza variáveis para armazenar e produzir valores para o modelo. As variáveis podem ser usadas na lógica do modelo ou iteradas em loops. Além das variáveis, as macros são outra ferramenta útil para imprimir seções de código repetitivas, mas dinâmicas nos seus modelos.

Variáveis são expressões delimitadas por }}. A sintaxe básica das variáveis é a seguinte:

As variáveis são uma palavra em uma expressão ou um atributo de um dicionário. O HubL usa estruturas de dados baseadas em Python chamadas dicionários ou dicts para armazenar vários conjuntos de variáveis.  Por exemplo, o HubSpot usa um "content" de dicionário para abrigar muitos atributos que pertencem ao conteúdo criado com esse modelo. Por exemplo, content.absolute_url imprime a URL da parte específica do conteúdo.

O HubSpot tem muitas variáveis predefinidas que podem ser usadas em toda a sua página, blog e modelos de e-mail. Temos uma lista de referência de variáveis, você também pode ver as informações do desenvolvedor ao navegar em qualquer página da sua conta para ver as variáveis disponíveis dentro dessa página.

Além de imprimir os valores de variáveis e atributos de dicionário em um modelo, você também pode definir suas próprias variáveis. Você pode armazenar strings, booleanos, inteiros, sequências ou criar dicionários dentro de uma única variável. As variáveis são definidas dentro de delimitadores de instrução usando a palavra "set". Uma vez armazenadas, as variáveis podem então ser impressas declarando o nome da variável como uma expressão. Abaixo você pode ver vários tipos de informações armazenadas em variáveis e depois impressas.

As variáveis devem ser palavras únicas ou usar sublinhados no lugar de espaços (ou seja, my_variable). O HubL não suporta nomes de variáveis separadas por hifens.

Cada exemplo acima armazena um tipo diferente de variável, sendo que o último exemplo armazena duas variáveis diferentes em uma sequência. 

Além de imprimir valores, as variáveis podem ser usadas em instruções If, como em parâmetros de filtro e de função, além de serem iteradas em loops For (somente variáveis de sequência).

É comum usar variáveis para definir valores CSS comuns em sua folha de estilo. Por exemplo, se você usa uma cor repetidas vezes ao longo do seu arquivo CSS. Dessa forma, se você precisar mudar essa cor, poderá alterar o valor da variável, e todas as referências a ela serão atualizadas na próxima vez que você publicar o arquivo.

As macros do HubL permitem imprimir vários comandos com um valor dinâmico. Por exemplo, se houver um bloco de código que você sempre escreve, uma macro poderá ser uma boa solução, pois ela escreverá o bloco de código trocando alguns argumentos determinados por você.

A macro é definida, nomeada e recebe argumentos dentro de uma instrução do HubL. A macro é então chamada em uma instrução que passa seus valores dinâmicos, e o bloco de código final é impresso com os argumentos dinâmicos. A sintaxe básica de uma macro é a seguinte:

Se sua macro retornar espaços em branco na forma de novas linhas, você poderá remover os espaços em branco nos modelos manualmente. Se você adicionar um sinal de menos (-) no início ou no fim de um bloco, comentário ou expressão de variável, os espaços em branco antes ou depois desse bloco serão removidos.

Abaixo está uma aplicação prática de uma macro para imprimir uma propriedade CSS3 com os diferentes prefixos de fornecedor, com um valor dinâmico. Isso permite imprimir cinco linhas de código com uma única tag de macro.

Em alguns casos, você pode querer retornar informações dinâmicas adicionais para o bloco da macro. Por exemplo, você pode ter uma grande porção de código para retornar à macro, além dos argumentos. Você pode fazer isso usando o bloco de chamadas e chamador(). Um bloco de chamada funciona basicamente como uma macro, mas não recebe seu próprio nome. A expressão caller() especifica onde o conteúdo do bloco de chamada renderizará.

No exemplo abaixo, um <p> é adicionado em uma macro, além dos dois argumentos.

Outra característica útil das macros é que elas podem ser usadas nos modelos. Basta importar um arquivo de modelo em outro. Para fazer isso, você precisará usar a tag import. A tag import permitirá especificar um caminho de arquivo do Gerenciador de design para o modelo que contém suas macros e dar um nome às macros no modelo em que você as está incluindo. Você pode passar valores para essas macros sem precisar redefini-los.

Por exemplo, suponha que você tenha um arquivo de modelo .html com as duas macros a seguir. Uma macro define uma tag header e a outra gera uma tag footer. Este arquivo é salvo no Gerenciador de design com o nome my_macros.html.

No modelo que usará essas macros, é utilizada uma tag import que especifica o caminho do arquivo my_macros.html. Ela também nomeia o grupo de macros (neste exemplo header_footer). As macros podem então ser executadas anexando o nome da macro ao nome dado ao modelo importado. Veja o exemplo abaixo.

Se você quiser importar apenas macros específicas, ao invés de todas as macros contidas em um arquivo .html separado, use a tag from. Com a tag from, especifique apenas as macros que você quer importar. Geralmente, a utilização de import irá proporcionar maior flexibilidade, mas esta alternativa também é suportada.

O exemplo abaixo acessa o mesmo arquivo my_macros.html da seção anterior deste artigo. Porém, em vez de importar todas as macros, ele acessa apenas a macro footer.

Você pode chamar variáveis que são definidas dentro ou fora de um loop, mas não no sentido contrário. 

Você também pode usar funções para silenciar objetos para valores de configuração em dicionários ou operações de lista de execução. O seguinte exemplo usa a operação de lista .update: