Documentação para Desenvolvedores de Variáveis

Variáveis são fragmentos reutilizáveis orientados por template renderizados dentro de contextos gerenciados pelo FaceFlow.

Para usuários técnicos, Variáveis são uma das primitivas de reutilização mais leves no FaceFlow. São apropriadas quando a saída deve ser compartilhada entre layouts, componentes, listas ou outras superfícies de renderização sem introduzir um esquema completo de Componente.

Responsabilidade Principal

Uma Variável é responsável por:

saída de template reutilizável
CSS opcional e comportamento do lado do cliente
parametrização simples através de atributos
renderização sensível ao contexto
entrega sensível ao cache para saídas repetidas

Use uma Variável quando a unidade de reuso for menor que um Componente, mas mais durável do que marcação copiada.

Modelo de Variável

Uma Variável típica inclui:

uma identidade estável
um modelo Facet
CSS opcional
JavaScript opcional
atributos opcionais
metadados de categoria e descrição
um modo de cache

Conceitualmente:

{
  "name": "copyright-notice",
  "title": "Copyright Notice",
  "category": "footer",
  "cacheMode": "auto",
  "attributes": [
    { "name": "company", "default": "PageFace" }
  ],
  "html": "<p>&copy; {{ now.year }} {{ attr.company }}</p>",
  "css": ".copyright { color: #64748b; }",
  "js": ""
}

A implementação exata do armazenamento é interna. O contrato acima é a parte importante para autores técnicos.

Sintaxe de Incorporação

Variáveis são incorporadas com a sintaxe de colchetes duplos:

[[copyright-notice]]

Com atributos:

[[copyright-notice company="Acme Inc"]]

Variáveis também podem ser incorporadas dentro de outros templates:

<footer class="site-footer">
  [[copyright-notice company="Acme Inc"]]
</footer>

Os valores dos atributos devem ser passados como literais entre aspas na sintaxe de incorporação.

Se uma Variável precisar de comportamento sensível à página ou ao tempo de execução, leia do contexto de renderização dentro do template da Variável ao invés de tentar injetar uma expressão não entre aspas na lista de atributos.

Modelo de Atributos

Atributos são entradas nomeadas passadas para a Variável em tempo de renderização.

Eles são apropriados para:

variações de texto
rótulos
opções visuais simples
pequenos valores específicos de negócio

Exemplo:

[[cta-badge label="New" tone="accent"]]

Uso no template:

<span class="badge badge-{{ attr.tone | default('neutral') }}">
  {{ attr.label }}
</span>

Atributos devem permanecer leves. Se a unidade de reuso precisar de um grande esquema editável, isso geralmente indica um Componente em vez disso.

Exemplo de mistura segura de atributos literais com contexto de tempo de execução:

<span class="badge badge-{{ attr.tone | default('neutral') }}">
  {{ attr.label | default(page.title) }}
</span>

Contexto de Renderização

Variáveis podem renderizar contra um contexto de tempo de execução mais amplo. Objetos de contexto comuns incluem:

page
user
pages
site
languages / lang
now
attr

Exemplo:

<p class="eyebrow">
  {{ page.title }} updated {{ now.year }}
</p>

Ou um exemplo dirigido por consulta:

<ul class="recent-posts">
  {{#pages selector="template=blog-post, sort=-published, limit=3" as="item"}}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
  {{/pages}}
</ul>

É isso que torna Variáveis úteis para pequenos fragmentos dinâmicos sem exigir uma Lista ou Componente completo.

Posicionamento Suportado

Variáveis são comumente usadas em:

templates de Layout
templates de Componente
templates de Lista
outras Variáveis
superfícies de conteúdo suportadas que passam pela renderização do FaceFlow

Exemplos típicos:

[[site-announcement]]
[[page-breadcrumbs]]
[[recent-posts title="From the blog"]]

Aninhamento

Variáveis podem referenciar outras Variáveis:

<div class="footer-meta">
  [[social-links]]
  [[copyright-notice company="PageFace"]]
</div>

O aninhamento é útil quando melhora a clareza. Evite cadeias profundas que tornem difícil raciocinar sobre depuração ou impacto de mudanças.

Modos de Cache

Variáveis suportam múltiplas estratégias de cache.

Automático

Use na maioria dos casos. O runtime determina se um comportamento estático ou dinâmico é apropriado com base nas necessidades de renderização.

Estático

Use quando a saída não depende de usuário, tempo ou contexto sensível à requisição que mudem.

Dinâmico

Use quando a saída depende de contexto que muda frequentemente e não deve se comportar como um fragmento totalmente amigável ao cache.

Regra de decisão de exemplo:

current year footer -> auto
simple shared legal text -> static
logged-in user greeting -> dynamic

Orientações de Desempenho

Variáveis são frequentemente reutilizadas amplamente, então disciplina de desempenho importa.

prefira auto ou static a menos que haja uma razão real para dynamic
evite saída cara e com muitas consultas em fragmentos usados em muitas páginas
trate Variáveis amplamente compartilhadas como ativos sensíveis ao desempenho
revise o impacto de mudanças antes de editar uma Variável muito reutilizada

Pré-visualização e Testes

Ao testar uma Variável, revise:

renderização com atributos realistas
comportamento dentro do contexto real da página ou componente
saída sob o modo de cache pretendido
comportamento de Variáveis aninhadas se houver composição envolvida

Padrão de teste exemplo:

[[cta-badge label="Launch Ready" tone="success"]]
[[cta-badge label="New" tone="accent"]]

Quando Usar uma Variável

Use uma Variável quando:

o fragmento é reutilizado em vários lugares
a estrutura é pequena e estável
as entradas são limitadas
a saída precisa de sensibilidade ao contexto

Não use uma Variável quando:

o conteúdo é único para uma Página
é necessário um esquema editável completo
a estrutura é grande o suficiente para ser uma seção reutilizável
a saída é realmente um arquivo dinâmico em vez de um fragmento

Anti-padrões

Evite:

transformar Variáveis em mini-páginas
esconder grandes fluxos de trabalho de negócio dentro de uma única Variável
adicionar muitos atributos para simular um esquema de Componente
cadeias de Variáveis profundamente aninhadas com propriedade pouco clara
usar o modo de cache dynamic por padrão sem uma necessidade real

Padrões de Construção de Exemplo

Pequeno fragmento utilitário:

[[copyright-notice company="PageFace"]]

Trecho reutilizável sensível à página:

<aside class="page-summary">
  <h3>{{ page.title }}</h3>
  <p>{{ page.summary }}</p>
</aside>

Widget dirigido por consulta:

<div class="resource-count">
  {{ pages.count selector="template=resource-item" }} resources
</div>

FaceFlow Variables — Reusable Template Fragments