Variáveis e reúso entre sites

As variáveis são o que transforma um template em uma rede. Acerte o desenho das variáveis e 100 sites renderizam de uma única fonte. Erre e você vai colar texto à mão em cada preset.

Três fontes, um escopo só

Na hora do render, a maioria dos motores junta variáveis de três lugares em uma única tabela de consulta. Quando o template lê %SomeName%, o resolvedor percorre essa tabela e substitui o valor.

1. Auxiliares locais do template, declarados com #set ou #def dentro do corpo do template.
2. Variáveis de site, definidas por inquilino — um registro por site, compartilhado por todos os templates daquele site.
3. Variáveis de runtime, passadas ao resolvedor no momento da chamada (contexto do artigo, do sistema, do usuário).

As decisões de autoria se resumem a qual camada é dona de cada fato.

Auxiliares locais com #set

Use #set para auxiliares de vida curta dentro de um template:

#set %Lead% = {Welcome|Greetings|Hello}
%Lead% to %brand_name%!

Bons usos:

• auxiliares de um template só, que de outro jeito encheriam o corpo de repetição;
• frases longas repetidas várias vezes dentro do mesmo template;
• legibilidade, quando o aninhamento fica fundo o bastante para cansar a vista.

Maus usos:

• fatos específicos de um inquilino — esses são variáveis de site;
• qualquer coisa que o runtime já fornece — um #set local perde a disputa de precedência.

Regras de sintaxe que pegam todo mundo

• Nomes de variáveis não diferenciam maiúsculas de minúsculas.
• Use só ASCII: letras, números, underscore. Sem espaços, sem hífens.
• #set só funciona quando abre a linha.
• Comentários usam /# ... #/ e são removidos antes do processamento.
• Variáveis desconhecidas ficam literais. %MissingVar% renderiza como %MissingVar%, não como string vazia nem como erro. Trate sobras como falha de QA.

Variáveis de site — o multiplicador entre sites

As variáveis de site são o motivo de um template compartilhado conseguir servir muitos sites sem ler igual em todos os domínios.

Um preset genérico de site é assim:

#set %BrandTone% = {practical|no-nonsense|straightforward}
#set %Industry% = SaaS analytics
#set %TopFeatures% = [<minsize=3;maxsize=4;sep=", ";lastsep=" and ">dashboards|alerting|audit logs|SSO|role-based access]
#set %Audience% = {teams|product leads|operations}

Agora todo template compartilhado pode ler %BrandTone%, %TopFeatures% etc., e a saída muda por site sem ninguém tocar no template.

Quando criar uma variável de site

Variáveis de runtime

As variáveis de runtime vêm do contexto que chama: o artigo sendo renderizado, o usuário atual, o relógio do sistema. Elas sobrepõem variáveis de site e auxiliares locais de mesmo nome.

Variáveis de runtime comuns entre motores (os nomes dependem da sua implementação):

• %year% — ano atual
• %lang% — código do idioma atual
• %site_domain% — host do site atual
• %brand_name%, %product_name% — marca/produto de que o artigo fala
• %article_topic%, %category% — metadados do artigo

Quem escreve nunca atribui essas variáveis a partir de um template. Basta lê-las.

Precedência de variáveis

Quando o mesmo nome existe em várias camadas, vence a de maior prioridade. Uma ordem padrão, da mais forte para a mais fraca:

1. Variáveis de runtime
2. Variáveis de site
3. Variáveis de sistema
4. #set local do template

Consequência prática: #set %brand_name% = Demo dentro de um template não faz nada se o runtime passar %brand_name%. O runtime vence. Escolha nomes de auxiliar que não sombreiem o runtime.

Convenções de nome

Consistência dentro de um preset importa mais do que qualquer estilo específico. Ainda assim, um padrão razoável:

• Variáveis de runtime: em geral lowercase_snake_case. Elas existem fora do seu controle.
• Variáveis de site: PascalCase para strings comuns, PascalCaseComSufixo para variantes gramaticais.
• Variáveis de lista: no plural (%TopFeatures%, %SupportedLanguages%).
• Auxiliares locais: curtos e descritivos — %Lead%, %Closing%.

Variáveis compostas

Variáveis de site podem se referenciar. O resolvedor do preset substitui as referências entre variáveis primeiro, mantendo o spintax aninhado cru, para que os re-sorteios posteriores continuem funcionando:

#set %FoundedLine% = launched in %FoundedYear%, based in %HQ%
#set %Pitch% = {fast|lightweight|self-hosted} %ProductCategory%

Use compostas para montar uma vez os fatos repetidos e reaproveitá-los entre templates.

A pegadinha do re-sorteio

Esta é de longe a maior fonte de confusão para quem está começando. Se uma variável contém spintax cru, cada ocorrência sorteia de novo, de forma independente.

#set %Tone% = {safe|trusted}
%Tone% and %Tone%

Saída possível:

Safe and trusted

Não assuma que uma variável de #set resolve uma vez e depois só ecoa. Se você precisa de dois adjetivos diferentes, use duas variáveis.

Quando você precisa de repetição exata: #def

A regra acima vale para #set, que é uma macro. A irmã #def tem a mesma forma e faz o oposto: resolve o valor uma vez por render e entrega esse mesmo resultado a todas as referências.

#def %Tone% = {safe|trusted|secure}

%Tone% and %Tone%

Agora os dois espaços sempre concordam — "safe and safe", "trusted and trusted" — porque o sorteio aconteceu uma vez, antes de qualquer referência ser preenchida. É toda a diferença entre as duas diretivas; o resto (presa à linha, uma por linha, removida da saída, mesmas regras de nome) é idêntico.

Chame o #def quando um valor precisa ficar estável ao longo do template: uma contagem que alimenta um bloco {plural}, um substantivo tirado de dentro de uma forma plural, ou qualquer frase que você repete de propósito. Chame o #set quando você quer a variação, que é o caso comum no corpo do texto.

Uma ressalva que vale dizer com todas as letras: o #def deixa uma variável consistente consigo mesma. Ele não correlaciona duas variáveis diferentes — cada #def sorteia por conta própria, então %Noun% e %NounGenitive% ainda podem cair em palavras diferentes. Quando dois valores precisam concordar entre si, prenda os dois em uma única enumeração em vez de duas variáveis.

Fragmentos opcionais

Um ramo vazio numa enumeração dá um fragmento opcional:

{|official }website
{fast|secure|} withdrawals

Coloque o espaço dentro do ramo opcional quando o fragmento puder sumir; caso contrário você ganha espaços dobrados ou palavras grudadas. Para uma lista opcional (uma permutação que pode ficar vazia), envolva a permutação inteira:

{|[<minsize=2;maxsize=3;sep=", ";lastsep=" and ">Slack|Jira|Linear]}

O motor não consegue escolher zero itens de uma permutação. Envolver é o único jeito de tornar "nenhuma lista" um desfecho possível.

Colisões de separador

Um bug de renderização comum: a variável de lista já contém um and, e o texto em volta acrescenta outro and.

%Integrations% and other tools

Se %Integrations% resolver para Slack, Jira, and Linear, o texto final fica:

Slack, Jira, and Linear and other tools

Correções:

• colocar uma vírgula: %Integrations%, and other tools;
• reestruturar: {Besides|Along with} %Integrations%, other tools...;
• abandonar a conjunção final e usar dois-pontos ou travessão.

O mesmo acontece com uma permutação com lastsep=" and " seguida de texto fixo que começa com and. Pré-visualize algumas variantes antes de publicar.

Variáveis x spintax inline

Regra prática: extraia para variáveis as frases repetidas e sensíveis à gramática antes de sair criando pequenos espaços de sinônimo inline. A variável te dá um lugar só para corrigir erros. O inline espalha os erros.

Erros comuns com variáveis

Checklist de desenho de variáveis

• Todo fato específico de um inquilino mora numa variável de site, não no template compartilhado.
• Todo fato específico do artigo mora numa variável de runtime, não num #set.
• Nenhum nome de auxiliar #set sombreia uma variável de runtime.
• Os nomes das variáveis são ASCII, sem espaços e sem hífens.
• Toda variável repetida foi revisada quanto ao efeito de re-sorteio.
• Todo fragmento opcional tem o espaço tratado dentro do ramo.
• Toda variável de lista seguida de conjunção foi checada quanto a colisão de separador.
• Cinco amostras resolvidas não têm nenhum %...% sobrando.

Pronto para a estrutura? O próximo guia cobre permutações na prática — onde a variedade realmente mora.

Continuar a série