Documentation developpeur Component

Les Components sont des sections de site pilotees par schema et rendues via FaceFlow.

Pour les utilisateurs techniques, les Components sont le contrat central de section reutilisable dans le systeme. Ils combinent des definitions de champs, un rendu template Facet, un style optionnel, un comportement cote client optionnel et une reutilisation sensible au scope.

Responsabilite centrale

Un Component est responsable de :

• definir un contrat de section reutilisable
• exposer un schema d'edition controle
• rendre la sortie via Facet
• attacher eventuellement des styles et comportements scopes
• prendre en charge la reutilisation au niveau page, layout ou site

Les Components doivent resoudre des problemes de section repetables. Ils ne doivent pas devenir des conteneurs vagues pour du markup specifique a une page.

Modele de definition d'un Component

Une definition typique de Component comprend :

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

Ce modele permet au Component de se comporter comme un contrat de section gouverne plutot que comme un fragment de code copie sans structure.

Metadonnees centrales

Les champs de metadonnees importants incluent :

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

Conseils :

• gardez name stable apres publication
• utilisez title pour la clarte de l'editeur
• faites evoluer version volontairement lorsque le schema ou le comportement de rendu change
• choisissez defaultScope en fonction de la reutilisation attendue, pas de la commodite

Schema de champs

Le schema de champs definit ce que les auteurs peuvent changer sans modifier la structure de la section.

Les types de champs de premier niveau pris en charge incluent :

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

Des sous-types supplementaires peuvent etre utilises dans repeater, notamment :

• color
• email
• tel
• range

Exemple :

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

Choisissez les types de champs selon l'intention du contenu, pas selon la commodite. Un url doit rester une URL. Un ensemble repetitif de cartes doit etre un repeater, pas plusieurs champs texte sans lien.

Voir la reference complete des champs :

• Component Fields
• Repeater Field

Modele de template

La partie html d'un Component est rendue via Facet.

Cela signifie que les templates peuvent utiliser :

• la sortie de champs
• des conditionnels
• des boucles
• des filtres
• un contexte conscient de la page
• des Variables reutilisables

Exemple :

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

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

Pour les details de syntaxe :

• Facet
• Facet Template Syntax

Modele de scope

Les Components peuvent exister a trois niveaux de reutilisation :

• site
• layout
• page

Conceptuellement :

scope site   -> reutilisable a l'echelle large du site
scope layout -> partage dans une meme famille de pages
scope page   -> local a une seule page

Le scope determine a la fois la visibilite et l'impact des changements. Si un Component change au scope site, il s'agit d'un changement architectural large, pas d'une edition locale.

Pour le modele global :

• Scope System

Comportement de rendu

Au moment du rendu, FaceFlow resout l'instance de Component en combinant :

• la definition du Component
• les valeurs de champs enregistrees
• le contexte courant de rendu
• les services runtime associes comme les medias, les Variables, les Forms et les Reviews

Conceptuellement :

definition du component
  + valeurs de champs enregistrees
  + contexte runtime
  -> rendu Facet
  -> sortie finale de la section

C'est a ce moment que les donnees de champs deviennent du markup runtime.

Styles et comportement

Les Components peuvent attacher des styles et un comportement optionnels.

Exemple :

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

Utilisez cela avec parcimonie. La plupart des comportements de section doivent rester simples, predictibles et faciles a maintenir.

Forms et Reviews dans les Components

Deux types de champs sont particulierement importants pour les sections interactives :

• formSelect
• reviewSelect

Ils permettent aux Components d'embarquer des workflows metier sans figer un modele specifique.

Marqueurs typiques :

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

Cela garde la section reutilisable tout en permettant au Form ou au modele de Review selectionne de changer au moment de l'edition.

Exemples de patterns de Component

Section de contenu simple :

fields:
  title
  summary
template:
  heading + paragraph

Section FAQ :

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

Section de capture de leads :

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

Checklist de revue technique

• le Component resout-il un seul probleme de section repetable ?
• le schema de champs est-il clair et volontaire ?
• le template est-il lisible et stable ?
• le scope choisi est-il correct pour la reutilisation attendue ?
• un futur editeur comprendrait-il comment l'utiliser uniquement a partir du contrat de champs ?

Anti-patterns

Evitez :

• de surcharger un Component avec des cas d'usage sans lien
• d'ajouter une logique metier specifique a une page qui devrait rester hors du contrat de section
• d'utiliser htmlcode quand un schema de champs structure serait plus sur
• d'elargir le scope simplement parce que la section pourrait etre reutilisee un jour
• de renommer les champs apres que du contenu ait deja ete stocke contre eux

Quand scinder un Component

Scindez un Component lorsque :

• le schema de champs est devenu trop large
• plusieurs layouts ou contextes de page ont besoin de versions contradictoires
• le template est plein d'exceptions et de branches ponctuelles
• les editeurs ne comprennent plus ce que la section est censee faire

Si le contrat cesse d'etre clair, la reutilisation cesse en general d'etre utile.

Related

• Vue produit Components
• Guide Component
• Component Fields
• Pages
• Layouts
• Forms
• Reviews