🇩🇪 Deutsch 🇺🇸 English 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇳🇱 Nederlands 🇵🇹 Português
🇩🇪 Deutsch 🇺🇸 English 🇪🇸 Español 🇫🇷 Français 🇮🇹 Italiano 🇳🇱 Nederlands 🇵🇹 Português

FaceFlow Components

Reusable business blocks with schema-driven fields, Facet templates, scoped styles, and optional runtime behavior.

Documentación para desarrolladores de Componentes

Los componentes son secciones de sitio web basadas en esquemas renderizadas a través de FaceFlow.

Para usuarios técnicos, los Componentes son el contrato central de sección reutilizable en el sistema. Combinan definiciones de campos, salida de plantillas Facet, estilos opcionales, comportamiento opcional del lado del cliente y reutilización con alcance controlado.

Responsabilidad principal

Un Componente es responsable de:

  • definir un contrato de sección reutilizable
  • exponer un esquema de autoría controlado
  • renderizar la salida a través de Facet
  • adjuntar opcionalmente estilos y comportamiento con alcance
  • soportar la reutilización a nivel de página, diseño o sitio

Los Componentes deben resolver problemas de secciones repetibles. No deben convertirse en contenedores sueltos para marcado arbitrario específico de una página.

Modelo de definición de Componente

Una definición típica de Componente incluye:

{
  "name": "contact-section",
  "title": "Contact Section",
  "version": "1.0.0",
  "type": "component",
  "category": "contact",
  "defaultScope": "page",
  "description": "Contact section with CTA and embedded form support",
  "fields": [
    { "name": "title", "label": "Title", "type": "text" },
    { "name": "summary", "label": "Summary", "type": "textarea" },
    { "name": "contactForm", "label": "Form", "type": "formSelect" }
  ],
  "html": "<section><h2>{{ title }}</h2><p>{{ summary }}</p><div data-form-embed=\"{contactForm}\"></div></section>",
  "style": ".contact-section { padding: 4rem 0; }",
  "script": "/* optional behavior */"
}

Este modelo es lo que permite que un Componente actúe como un contrato de sección gobernado en lugar de un fragmento suelto de código copiado.

Metadatos principales

Los campos de metadatos importantes incluyen:

  • name
  • title
  • version
  • type
  • category
  • defaultScope
  • description

Guía:

  • mantener name estable después del lanzamiento
  • usar title para claridad en el editor
  • actualizar version intencionalmente cuando el esquema o el comportamiento de renderizado cambien
  • elegir defaultScope según la reutilización esperada, no por conveniencia

Esquema de campos

El esquema de campos define lo que los autores pueden cambiar sin alterar la estructura de la sección.

Los tipos de campo de nivel superior compatibles incluyen:

  • text
  • textarea
  • number
  • url
  • date
  • image
  • images
  • file
  • select
  • checkbox
  • richtext
  • htmlcode
  • map
  • repeater
  • formSelect
  • reviewSelect

Se pueden usar tipos de subcampo adicionales dentro de repeater, incluyendo:

  • color
  • email
  • tel
  • range

Ejemplo:

{
  "name": "faqItems",
  "label": "FAQ Items",
  "type": "repeater",
  "fields": [
    { "name": "question", "type": "text" },
    { "name": "answer", "type": "textarea" }
  ]
}

Elija tipos de campo según la intención del contenido, no por conveniencia. Un url debe mantenerse como URL. Un conjunto repetido de tarjetas debe ser un repeater, no varios campos de texto no relacionados.

Vea la referencia completa de campos:

Modelo de plantillas

La porción html de un Componente se renderiza a través de Facet.

Eso significa que las plantillas pueden usar:

  • salida de campos
  • condicionales
  • bucles
  • filtros
  • contexto consciente de la página
  • Variables reutilizables

Ejemplo:

<section class="hero-section">
  <div class="container">
    <h1>{{ title }}</h1>

    {{#if summary}}
      <p>{{ summary }}</p>
    {{/if}}

    {{#if ctaUrl}}
      <a href="{{ ctaUrl }}" class="btn-primary">{{ ctaLabel }}</a>
    {{/if}}
  </div>
</section>

O con un repeater:

<div class="faq-list">
  {{#each faqItems as="item"}}
    <article class="faq-item">
      <h3>{{ item.question }}</h3>
      <p>{{ item.answer }}</p>
    </article>
  {{/each}}
</div>

Para detalles de sintaxis:

Modelo de alcance

Los Componentes pueden existir en tres niveles de reutilización:

  • site
  • layout
  • page

Conceptualmente:

site scope   -> reusable across the broader site
layout scope -> shared inside one page family
page scope   -> local to one page

El alcance determina tanto la visibilidad como el impacto de los cambios. Si un Componente cambia en el scope site, eso es un cambio arquitectónico amplio, no una edición local.

Para el modelo más amplio:

Comportamiento de renderizado

En tiempo de renderizado, FaceFlow resuelve la instancia del Componente combinando:

  • la definición del Componente
  • los valores de campos guardados
  • el contexto de renderizado actual
  • servicios de tiempo de ejecución relacionados como media, Variables, Formularios y Reseñas

Conceptualmente:

component definition
  + saved field values
  + runtime context
  -> Facet render
  -> final section output

Este es el punto en el que los datos de los campos se convierten en marcado en tiempo de ejecución.

Estilos y comportamiento

Los Componentes pueden adjuntar estilos opcionales y comportamiento opcional.

Ejemplo:

.pricing-card {
  border-radius: 1rem;
  padding: 2rem;
}
document.querySelectorAll('.faq-item button').forEach((button) => {
  button.addEventListener('click', () => {
    button.closest('.faq-item').classList.toggle('is-open');
  });
});

Use esto con moderación. La mayoría del comportamiento de sección debe permanecer simple, predecible y fácil de mantener.

Formularios y Reseñas dentro de Componentes

Dos tipos de campo son especialmente importantes para secciones interactivas:

  • formSelect
  • reviewSelect

Estos permiten que los Componentes incrusten flujos de trabajo de negocio sin codificar de forma rígida un modelo específico.

Marcadores típicos:

<div data-form-embed="{contactForm}"></div>
<div data-review-embed="{serviceReview}"></div>

Esto mantiene la sección reutilizable mientras permite que el Formulario o el modelo de Reseña seleccionado cambie en el momento de la autoría.

Patrones de ejemplo de Componentes

Basic content section:

fields:
  title
  summary
template:
  heading + paragraph

FAQ section:

fields:
  faqItems repeater
template:
  each item -> question + answer

Lead capture section:

fields:
  title
  summary
  contactForm (formSelect)
template:
  copy + data-form-embed marker

Lista de verificación para revisión técnica

  • ¿resuelve el Componente un problema de sección repetible?
  • ¿el esquema de campos es claro e intencional?
  • ¿la plantilla es legible y estable?
  • ¿el alcance elegido es correcto para la reutilización esperada?
  • ¿un editor futuro entendería cómo usarlo solo con el contrato de campos?

Anti-patrones

Evite:

  • sobrecargar un Componente con casos de uso no relacionados
  • añadir lógica de negocio específica de la página que debería permanecer fuera del contrato de la sección
  • usar htmlcode cuando un modelo de campo estructurado sería más seguro
  • ampliar el scope solo porque la sección podría reutilizarse algún día
  • renombrar campos después de que el contenido ya esté almacenado contra ellos

Cuándo dividir un Componente

Divida un Componente cuando:

  • el esquema de campos se haya vuelto demasiado amplio
  • varios diseños o contextos de página necesiten versiones en conflicto
  • la plantilla esté llena de excepciones y ramas únicas
  • los editores ya no entiendan lo que se supone que debe hacer la sección

Si el contrato deja de ser claro, la reutilización suele dejar de ser valiosa.

Relacionado