Formulaires & Form Builder

Vue d'ensemble

Cmssy intègre un Form Builder qui vous permet de créer des formulaires visuellement et de les connecter à n'importe quel bloc personnalisé. Les formulaires gèrent la validation, les soumissions, les notifications par e-mail et les webhooks — vos blocs n'ont qu'à rendre l'UI.

Le système comporte deux parties :

1. Form Builder (Dashboard > Forms) — définir les champs, la validation et les actions
2. Un champ formId sur votre bloc — stocke quel formulaire le bloc doit rendre

Créer un formulaire

1. Ouvrez le Form Builder

Allez dans Dashboard → Forms → Create Form. Donnez-lui un nom et un slug (p. ex. contact-form).

2. Ajoutez des champs

Chaque champ possède :

3. Configurez les paramètres

4. Publiez

Passez le statut à Published. Copiez son ID de formulaire — vous le référencerez depuis votre bloc.

Utiliser les formulaires dans des blocs personnalisés

Référencer un formulaire

Ajoutez un champ formId au schéma de votre bloc. Utilisez fields.form() : il affiche un sélecteur de formulaire dans l'éditeur et stocke l'identifiant du formulaire choisi - personne n'a à recopier un ID à la main.

// blocks/contact/block.ts
import { defineBlock, fields } from "@cmssy/react";
import Contact from "./Contact";

export const contactBlock = defineBlock({
  type: "contact",
  label: "Contact",
  component: Contact,
  props: {
    formId: fields.form({ label: "Formulaire" }),
    submitLoadingText: fields.text({ label: "Loading Text", defaultValue: "Sending..." }),
    successHeading: fields.text({ label: "Success Heading", defaultValue: "Message Sent!" }),
  },
});

Rendre le formulaire

Le SDK résout automatiquement tout formulaire référencé par le formId d'un bloc et injecte la définition dans le context du bloc sous context.forms[formId] — aucun fetch nécessaire :

// blocks/contact/src/Contact.tsx
export default function Contact({ content, context }) {
  const { formId } = content;
  const formDef = formId ? context?.forms?.[formId] ?? null : null;
  // formDef.fields   - array of field definitions
  // formDef.settings - submit label, messages, action type
  // ...render the fields
}

Soumettre le formulaire

La soumission passe par public.form.submit. Gardez la mutation dans votre dépôt et envoyez-la avec votre client configuré : le SDK porte la même chaîne sous SUBMIT_FORM_MUTATION, mais dans @cmssy/core/internal, qui n'est pas une API publique. Le backend valide les champs, enregistre la soumission, envoie les e-mails de notification, appelle un éventuel webhook et répond par un succès ou une erreur :

// blocks/contact/actions.ts
"use server";
import { createCmssyClient, type CmssyFormSubmitResponse } from "@cmssy/react";
import { cmssy } from "@/cmssy.config";

const SUBMIT_FORM = `mutation SubmitForm($formId: ID!, $input: SubmitFormInput!) {
  public {
    form {
      submit(formId: $formId, input: $input) {
        success
        message
        submissionId
        redirectUrl
      }
    }
  }
}`;

const client = createCmssyClient(cmssy);

export async function submitForm(formId: string, data: Record<string, string>) {
  const res = await client.query<{
    public: { form: { submit: CmssyFormSubmitResponse } };
  }>(SUBMIT_FORM, { formId, input: { data } });

  return res.public.form.submit; // { success, message, submissionId, redirectUrl }
}

La soumission est la seule écriture qu'un frontend public peut effectuer sans jeton. Tout le reste - créer des formulaires, lire les soumissions, changer un statut - exige un client autorisé.

Blocs de formulaire de référence

Cmssy ne fournit pas de blocs — dans le modèle headless, vous construisez les blocs dans votre propre repo avec le SDK. Voici des blocs de formulaire courants à implémenter comme patrons de référence, chacun reliant un formulaire du Form Builder (son actionType) à un bloc que vous rendez :

Chacun définit le formulaire côté serveur dans le Form Builder et le rend dans un bloc via un champ formId — le markup appartient au développeur. Voir Authentification des membres pour les flux d'authentification.

Soumissions de formulaire

Consulter les soumissions

Allez dans Dashboard → Forms → [Votre formulaire] → Submissions. Chaque soumission affiche :

• Toutes les valeurs des champs
• Le statut (pending, processed, spam, archived)
• Adresse IP, user agent, referrer
• Horodatage
• Statut de livraison e-mail/webhook

Cycle de vie d'une soumission

1. L'utilisateur soumet le formulaire sur votre site publié
2. Le serveur valide les champs et vérifie les limites de débit
3. La soumission est enregistrée avec le statut pending
4. Notification e-mail envoyée aux destinataires (si activée)
5. Webhook appelé (si configuré)
6. Statut mis à jour en processed

Protection anti-spam

Les formulaires incluent une limitation de débit intégrée :

• Limite par IP et par formulaire
• Support optionnel du captcha
• Des champs honeypot peuvent être ajoutés avec le type de champ hidden

Référence des types d'action

contact

Sauvegarde la soumission + envoie un e-mail aux destinataires configurés. Le choix par défaut pour la plupart des formulaires.

newsletter

Abonne le champ e-mail à la liste de newsletter du workspace.

login / register

Gère l'authentification. Ce sont des types d'action spéciaux utilisés par les blocs de formulaire d'authentification que vous construisez (voir Authentification des membres).

custom

Envoie les données de soumission en JSON via POST à votre URL de webhook. Utile pour s'intégrer à des services externes (Zapier, Slack, CRM, etc.).

Conseils

• Publiez toujours votre formulaire avant de le référencer — les formulaires en brouillon ne peuvent pas être résolus
• Utilisez les largeurs half et third pour créer des mises en page multi-colonnes (p. ex. prénom + nom côte à côte)
• Libellés multilingues — les champs de formulaire prennent en charge des libellés et placeholders par langue, en phase avec le système de langues du site
• Les soumissions de test sont enregistrées comme les vraies — supprimez-les de l'onglet Submissions une fois terminé
• Débogage des webhooks — consultez le champ webhookResponse de la soumission pour les détails de la réponse de votre endpoint