Komponenten-Entwicklerdokumentation

Komponenten sind schemagesteuerte Website-Abschnitte, die durch FaceFlow gerendert werden.

Für technische Anwender sind Komponenten der zentrale wiederverwendbare Abschnittsvertrag im System. Sie kombinieren Felddefinitionen, Facet-Template-Ausgabe, optionale Styles, optionales clientseitiges Verhalten und kontextsensitive Wiederverwendung.

Hauptverantwortung

Eine Komponente ist verantwortlich für:

• die Definition eines wiederverwendbaren Abschnittsvertrags
• das Offenlegen eines kontrollierten Authoring-Schemas
• das Rendern der Ausgabe durch Facet
• optionales Anhängen von scoped Styles und Verhalten
• die Unterstützung von Wiederverwendung auf Seiten-, Layout- oder Site-Ebene

Komponenten sollten wiederkehrende Abschnittsprobleme lösen. Sie sollten nicht zu losen Container für beliebiges seiten-spezifisches Markup werden.

Modell der Komponenten-Definition

Eine typische Komponenten-Definition beinhaltet:

{
  "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 */"
}

Dieses Modell ermöglicht, dass eine Komponente wie ein geregelter Abschnittsvertrag wirkt, anstatt ein loses Fragment kopierten Codes zu sein.

Wichtige Metadaten

Wichtige Metadatenfelder umfassen:

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

Hinweise:

• name nach der Freigabe stabil halten
• title für Klarheit im Editor verwenden
• version gezielt aktualisieren, wenn sich Schema oder Render-Verhalten ändern
• defaultScope nach erwarteter Wiederverwendung wählen, nicht nach Bequemlichkeit

Feld-Schema

Das Feld-Schema definiert, was Autoren ändern können, ohne die Struktur des Abschnitts zu verändern.

Unterstützte Top-Level-Feldtypen umfassen:

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

Zusätzliche Subfeldtypen können innerhalb von repeater verwendet werden, einschließlich:

• color
• email
• tel
• range

Beispiel:

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

Wählen Sie Feldtypen nach Inhaltsintention, nicht nach Bequemlichkeit. Ein url sollte eine URL bleiben. Ein wiederholtes Kartenset sollte ein repeater sein, nicht mehrere nicht zusammenhängende Textfelder.

Siehe die vollständige Feldreferenz:

• Component Fields
• Repeater Field

Template-Modell

Der html-Teil einer Komponente wird durch Facet gerendert.

Das bedeutet, Templates können verwenden:

• Feldausgabe
• Bedingungen
• Schleifen
• Filter
• seitenbewussten Kontext
• wiederverwendbare Variablen

Beispiel:

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

Oder mit einem Repeater:

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

Für Syntaxdetails:

• Facet
• Facet Template Syntax

Scope-Modell

Komponenten können auf drei Wiederverwendungsstufen existieren:

• site
• layout
• page

Begrifflich:

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

Der Scope bestimmt sowohl Sichtbarkeit als auch Auswirkungen von Änderungen. Wenn sich eine Komponente im Site-Scope ändert, ist das eine weitreichende architektonische Änderung, keine lokale Bearbeitung.

Für das übergeordnete Modell:

• Scope System

Render-Verhalten

Zur Renderzeit löst FaceFlow die Komponenten-Instanz auf, indem es kombiniert:

• die Komponenten-Definition
• gespeicherte Feldwerte
• den aktuellen Render-Kontext
• zugehörige Laufzeitdienste wie Medien, Variablen, Formulare und Reviews

Begrifflich:

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

Dies ist der Punkt, an dem Felddaten zur Laufzeit in Markup überführt werden.

Styles und Verhalten

Komponenten können optionale Styles und optionales Verhalten anhängen.

Beispiel:

.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');
  });
});

Verwenden Sie dies sparsam. Das Verhalten der meisten Abschnitte sollte einfach, vorhersehbar und leicht wartbar bleiben.

Formulare und Reviews innerhalb von Komponenten

Zwei Feldtypen sind besonders wichtig für interaktive Abschnitte:

• formSelect
• reviewSelect

Diese ermöglichen es Komponenten, Geschäfts-Workflows einzubetten, ohne ein spezifisches Modell hart zu kodieren.

Typische Marker:

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

Dies hält den Abschnitt wiederverwendbar, während das ausgewählte Formular- oder Review-Modell zur Authoring-Zeit geändert werden kann.

Beispielhafte Komponentenmuster

Basic-Content-Abschnitt:

fields:
  title
  summary
template:
  heading + paragraph

FAQ-Abschnitt:

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

Lead-Capture-Abschnitt:

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

Technische Prüfcheckliste

• löst die Komponente ein wiederkehrendes Abschnittsproblem?
• ist das Feld-Schema klar und bewusst gestaltet?
• ist das Template lesbar und stabil?
• ist der gewählte Scope korrekt für die erwartete Wiederverwendung?
• würde ein zukünftiger Redakteur verstehen, wie man es nur aus dem Feldvertrag verwendet?

Anti-Pattern

Vermeiden Sie:

• eine Komponente mit nicht zusammenhängenden Anwendungsfällen zu überladen
• seiten-spezifische Geschäftslogik hinzuzufügen, die außerhalb des Abschnittsvertrags bleiben sollte
• htmlcode zu verwenden, wenn ein strukturiertes Feldmodell sicherer wäre
• den Scope zu verbreitern, nur weil der Abschnitt vielleicht irgendwann wiederverwendet wird
• Felder umzubenennen, nachdem Inhalte bereits dagegen gespeichert wurden

Wann eine Komponente aufgeteilt werden sollte

Teilen Sie eine Komponente, wenn:

• das Feld-Schema zu breit geworden ist
• mehrere Layouts oder Seitenkontexte widersprüchliche Versionen benötigen
• das Template voller Ausnahmen und einmaliger Verzweigungen ist
• Redakteure nicht mehr verstehen, wofür der Abschnitt gedacht ist

Wenn der Vertrag nicht mehr klar ist, verliert Wiederverwendung in der Regel ihren Wert.

Verwandte Themen

• Components Product Overview
• Component Guide
• Component Fields
• Pages
• Layouts
• Forms
• Reviews