Documentación para Desarrolladores de Variables

Las Variables son fragmentos reutilizables basados en plantillas que se renderizan dentro de contextos gestionados por FaceFlow.

Para usuarios técnicos, las Variables son una de las primitivas de reutilización más ligeras en FaceFlow. Son apropiadas cuando la salida debe compartirse entre diseños, componentes, listas u otras superficies de renderizado sin introducir un esquema completo de Component.

Responsabilidad principal

Una Variable es responsable de:

salida de plantilla reutilizable
CSS opcional y comportamiento del lado del cliente
parametrización simple mediante atributos
renderizado con conocimiento del contexto
entrega consciente de caché para salidas repetidas

Use una Variable cuando la unidad de reutilización sea más pequeña que un Component pero más duradera que el marcado copiado.

Modelo de Variable

Una Variable típica incluye:

una identidad estable
una plantilla Facet
CSS opcional
JavaScript opcional
atributos opcionales
metadatos de categoría y descripción
un modo de caché

Conceptualmente:

{
  "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": ""
}

La implementación exacta del almacenamiento es interna. El contrato anterior es la parte importante para autores técnicos.

Sintaxis de inserción

Las Variables se insertan con la sintaxis de doble corchete:

[[copyright-notice]]

Con atributos:

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

Las Variables también pueden insertarse dentro de otras plantillas:

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

Los valores de los atributos deben pasarse como literales entre comillas en la sintaxis de inserción.

Si una Variable necesita comportamiento dependiente de la página o del tiempo de ejecución, lea desde el contexto de renderizado dentro de la plantilla de la Variable en lugar de intentar inyectar una expresión sin comillas en la lista de atributos.

Modelo de atributos

Los atributos son entradas nombradas que se pasan a la Variable en tiempo de renderizado.

Son apropiados para:

variantes de texto
etiquetas
opciones visuales simples
valores pequeños específicos del negocio

Ejemplo:

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

Uso en la plantilla:

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

Los atributos deben mantenerse ligeros. Si la unidad de reutilización necesita un esquema editable grande, eso normalmente indica un Component en su lugar.

Ejemplo de mezcla segura de atributos literales con contexto de tiempo de ejecución:

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

Contexto de renderizado

Las Variables pueden renderizarse frente a un contexto de tiempo de ejecución más amplio. Los objetos de contexto comunes incluyen:

page
user
pages
site
languages / lang
now
attr

Ejemplo:

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

O un ejemplo impulsado por consultas:

<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>

Esto es lo que hace que las Variables sean útiles para fragmentos dinámicos pequeños sin requerir una List o un Component completo.

Colocación admitida

Las Variables se usan comúnmente en:

plantillas de layout
plantillas de Component
plantillas de List
otras Variables
superficies de contenido compatibles que pasan por el renderizado de FaceFlow

Ejemplos típicos:

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

Anidamiento

Las Variables pueden hacer referencia a otras Variables:

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

El anidamiento es útil cuando mejora la claridad. Evite cadenas profundas que hagan que depurar o razonar sobre el impacto de los cambios sea difícil.

Modos de caché

Las Variables soportan múltiples estrategias de caché.

Automático

Úselo en la mayoría de los casos. El tiempo de ejecución determina si un comportamiento estático o dinámico es apropiado en función de las necesidades de renderizado.

Estático

Úselo cuando la salida no dependa de un contexto cambiante de usuario, tiempo o sensible a la solicitud.

Dinámico

Úselo cuando la salida dependa de un contexto que cambia con frecuencia y no deba comportarse como un fragmento totalmente caché-amigable.

Regla de decisión ejemplo:

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

Guía de rendimiento

Las Variables se reutilizan a menudo de forma amplia, por lo que la disciplina de rendimiento importa.

prefiera auto o static a menos que haya una razón real para dynamic
evite salidas costosas con consultas pesadas en fragmentos usados en muchas páginas
trate las Variables ampliamente compartidas como activos sensibles al rendimiento
revise el impacto de los cambios antes de editar una Variable muy reutilizada

Vista previa y pruebas

Al probar una Variable, revise:

renderizado con atributos realistas
comportamiento dentro del contexto real de la página o componente
salida bajo el modo de caché previsto
comportamiento de Variables anidadas si hay composición involucrada

Patrón de prueba ejemplo:

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

Cuándo usar una Variable

Use una Variable cuando:

el fragmento se reutiliza en varios lugares
la estructura es pequeña y estable
las entradas son limitadas
la salida necesita conocimiento del contexto

No use una Variable cuando:

el contenido es único para una sola Page
se requiere un esquema completamente editable
la estructura es lo suficientemente grande como para ser una sección reutilizable
la salida es realmente un archivo dinámico en lugar de un fragmento

Anti-patrones

Evite:

convertir Variables en mini-páginas
ocultar grandes flujos de trabajo de negocio dentro de una sola Variable
añadir demasiados atributos para simular un esquema de Component
cadenas de Variables profundamente anidadas con propiedad poco clara
usar el modo de caché dynamic por defecto sin una necesidad real

Patrones de ejemplo

Fragmento utilitario pequeño:

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

Fragmento reutilizable con conocimiento de la página:

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

Widget impulsado por consulta:

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

FaceFlow Variables — Reusable Template Fragments