Formulare & Form Builder

Überblick

Cmssy hat einen eingebauten Form Builder, mit dem du Formulare visuell erstellst und mit jedem eigenen Block verbindest. Formulare übernehmen Validierung, Einsendungen, E-Mail-Benachrichtigungen und Webhooks — deine Blöcke müssen nur die UI rendern.

Das System besteht aus zwei Teilen:

1. Form Builder (Dashboard > Forms) — Felder, Validierung und Aktionen definieren
2. Ein formId-Feld auf deinem Block — speichert, welches Formular der Block rendern soll

Ein Formular erstellen

1. Öffne den Form Builder

Gehe zu Dashboard → Forms → Create Form. Gib ihm einen Namen und einen Slug (z. B. contact-form).

2. Felder hinzufügen

Jedes Feld hat:

3. Einstellungen konfigurieren

4. Veröffentlichen

Setze den Status auf Published. Kopiere seine Formular-ID — du referenzierst sie aus deinem Block.

Formulare in eigenen Blöcken nutzen

Ein Formular referenzieren

Füge deinem Block-Schema ein formId-Feld hinzu und füge dort im Editor die ID des veröffentlichten Formulars ein:

// blocks/contact/block.ts
import type { ComponentType } from "react";
import { defineBlock, fields } from "@cmssy/react";
import Component from "./src";

export const contactBlock = defineBlock({
  type: "contact",
  label: "Contact",
  component: Component as unknown as ComponentType<{ content: Record<string, unknown> }>,
  props: {
    formId: fields.singleLine({ label: "Form", helperText: "Paste the form ID from the Form Builder" }),
    submitLoadingText: fields.singleLine({ label: "Loading Text", defaultValue: "Sending..." }),
    successHeading: fields.singleLine({ label: "Success Heading", defaultValue: "Message Sent!" }),
  },
});

Das Formular rendern

Das SDK löst jedes von einem Block-formId referenzierte Formular automatisch auf und injiziert die Definition in den Block-context als context.forms[formId] — kein Fetching nötig:

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

Das Formular absenden

Sende aus einer Server Action mit client.queryScoped und der exportierten SUBMIT_FORM_MUTATION. Sie validiert Felder, speichert die Einsendung, verschickt E-Mail-Benachrichtigungen, ruft ggf. den Webhook auf und liefert eine Erfolgs-/Fehler-Antwort:

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

const client = createCmssyClient({
  apiUrl: process.env.CMSSY_API_URL!,
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG!,
});

export async function submitForm(formId: string, data: Record<string, string>) {
  const res = await client.queryScoped<{ submitForm: CmssyFormSubmitResponse }>(
    SUBMIT_FORM_MUTATION,
    { formId, input: { data } },
    { workspaceId: process.env.CMSSY_WORKSPACE_ID },
  );
  return res.submitForm; // { success, message }
}

Referenz-Formularblöcke

Cmssy liefert keine Blöcke mit — im Headless-Modell baust du Blöcke mit dem SDK in deinem eigenen Repo. Das sind gängige Formularblöcke, die du als Referenzmuster implementieren kannst; jeder verbindet ein Form-Builder-Formular (seinen actionType) mit einem Block, den du renderst:

Jeder definiert das Formular serverseitig im Form Builder und rendert es über ein formId-Feld in einem Block — das Markup gehört dir als Dev. Siehe Mitglieder-Authentifizierung für die Auth-Flows.

Formular-Einsendungen

Einsendungen ansehen

Gehe zu Dashboard → Forms → [Dein Formular] → Submissions. Jede Einsendung zeigt:

• Alle Feldwerte
• Status (pending, processed, spam, archived)
• IP-Adresse, User Agent, Referrer
• Zeitstempel
• E-Mail-/Webhook-Zustellstatus

Lebenszyklus einer Einsendung

1. Nutzer sendet das Formular auf deiner veröffentlichten Seite ab
2. Der Server validiert die Felder und prüft Rate-Limits
3. Die Einsendung wird mit Status pending gespeichert
4. E-Mail-Benachrichtigung an Empfänger (falls aktiviert)
5. Webhook wird aufgerufen (falls konfiguriert)
6. Status wird auf processed aktualisiert

Spam-Schutz

Formulare bringen eingebautes Rate-Limiting mit:

• Pro-IP-Limit pro Formular
• Optionale Captcha-Unterstützung
• Honeypot-Felder lassen sich als Feldtyp hidden hinzufügen

Referenz der Action Types

contact

Speichert die Einsendung + sendet eine E-Mail an die konfigurierten Empfänger. Der Standard für die meisten Formulare.

newsletter

Abonniert das E-Mail-Feld auf die Newsletter-Liste des Workspace.

login / register

Übernimmt die Authentifizierung. Spezielle Action Types für die Auth-Formularblöcke, die du baust (siehe Mitglieder-Authentifizierung).

custom

POSTet die Einsendungsdaten als JSON an deine Webhook-URL. Nützlich für Integrationen mit externen Diensten (Zapier, Slack, CRMs usw.).

Tipps

• Veröffentliche dein Formular immer, bevor du es referenzierst — Draft-Formulare können nicht aufgelöst werden
• Nutze die Breiten half und third für mehrspaltige Layouts (z. B. Vorname + Nachname nebeneinander)
• Mehrsprachige Labels — Formularfelder unterstützen Labels und Platzhalter pro Sprache, passend zum Sprachsystem der Site
• Test-Einsendungen werden wie echte gespeichert — lösche sie danach im Submissions-Tab
• Webhook-Debugging — prüfe das Feld webhookResponse der Einsendung für Details zur Antwort deines Endpunkts