Facet Template Engine — Developer Guide
Facet is the core rendering engine of FaceFlow.
Documentación para desarrolladores de Facet
Facet es la capa de plantillas que usa FaceFlow para el renderizado dinámico.
Proporciona a los usuarios técnicos una forma controlada de emitir valores, componer fragmentos de plantilla reutilizables, trabajar con bucles y condiciones, y construir lógica de visualización dinámica dentro de PageFace.
Para qué se usa Facet
- plantillas de componentes
- plantillas de variables
- salida dinámica de listas
- renderizado de contenido compartido
- salida contextual de páginas
Facet no es todo el sistema FaceFlow. Es el lenguaje de renderizado dentro de él. FaceFlow define los objetos y contratos. Facet define cómo esos objetos renderizan salida dinámica de forma segura.
Capacidades principales
Los usuarios técnicos normalmente confían en Facet para:
- salida escapada y salida sin escapar
- condicionales y bloques de bucle
- renderizado con contexto de página y de consulta
- cadenas de filtros y formateo
- incrustación de variables
- composición segura de plantillas dentro de objetos reutilizables
Facet vs FaceFlow
Mantén este límite claro:
- FaceFlow define objetos como Pages, Components, Variables, Lists, Forms y Reviews
- Facet define cómo esos objetos renderizan salida dinámica
Si un usuario técnico está decidiendo qué objeto crear, está en territorio de diseño de FaceFlow.
Si está decidiendo cómo debe renderizarse un objeto existente (campos, condiciones y bucles), está en territorio de Facet.
Dónde aparece
Facet suele aparecer en:
- plantillas HTML de Componentes
- plantillas de Variables
- plantillas de ítems de Listas
- fragmentos dinámicos más pequeños que necesitan contexto en tiempo de ejecución
Un ejemplo sencillo:
<section class="hero">
<h1>{{ title }}</h1>
{{#if summary}}
<p>{{ summary }}</p>
{{/if}}
[[sales-contact-badge]]
</section>Este ejemplo muestra el modelo mental más común:
- El objeto FaceFlow proporciona el contrato
- Facet proporciona la lógica de renderizado
Lo que Facet no debe hacer
Facet es poderoso, pero no debe convertirse en un reemplazo de un buen modelado de objetos.
No uses Facet para:
- ocultar una estructura de contenido débil detrás de trucos de plantilla
- convertir una plantilla en un motor de flujo de trabajo empresarial
- reemplazar Listas con lógica de archivo escrita a mano cuando el problema es realmente contenido dirigido por consultas
- simular un esquema editable grande que debería ser un Component
Cómo aprender Facet
Sigue esta ruta de lectura:
- comienza con Template Syntax
- continúa con Reference
- luego vuelve al objeto FaceFlow que posee la plantilla que estás editando
Ese orden funciona porque la sintaxis viene primero, los patrones más profundos después y la aplicación específica del objeto al final.
Casos de uso comunes
Los usuarios técnicos normalmente recurren a Facet cuando necesitan:
- mostrar campos opcionales de forma limpia
- iterar contenido repetido
- formatear valores dependientes de la página
- insertar Variables reutilizables
- construir plantillas de archivo y listas sin código crudo de la plataforma
Errores comunes
Los usuarios técnicos con más frecuencia encuentran problemas cuando:
- meten demasiada lógica en una sola plantilla
- tratan un fragmento repetido como marcado copiado en lugar de una Variable
- usan condicionales para compensar un modelo de campos poco claro
- construyen un archivo dinámico en un Component cuando debería ser una List
- olvidan que la legibilidad es parte de la calidad de la plantilla
Guía de diseño
- mantén las plantillas legibles
- mantén la lógica de negocio superficial
- prefiere un modelado fuerte de objetos sobre trucos ingeniosos de plantilla
- usa Variables para fragmentos repetidos en vez de copiar marcado
- usa Lists cuando el problema sea selección dinámica de contenido, no solo presentación
Atajo para la decisión
Usa Facet cuando la pregunta sea:
- "¿Cómo debe renderizarse este campo?"
- "¿Debe mostrarse esta sección solo cuando exista información?"
- "¿Cómo itero sobre estos elementos?"
- "¿Cómo reutilizo este pequeño fragmento?"
No te detengas en Facet cuando la pregunta realmente sea:
- "¿Debe esto ser un Component o una Variable?"
- "¿Debería este contenido ser una List?"
- "¿Pertenece esto al Layout o a la Page?"