Formularios y Form Builder

Resumen

Cmssy incluye un Form Builder integrado que te permite crear formularios visualmente y conectarlos a cualquier bloque personalizado. Los formularios gestionan la validación, los envíos, las notificaciones por email y los webhooks — tus bloques solo tienen que renderizar la UI.

El sistema tiene dos partes:

1. Form Builder (Dashboard > Forms) — define campos, validación y acciones
2. Un campo formId en tu bloque — guarda qué formulario debe renderizar el bloque

Crear un formulario

1. Abre el Form Builder

Ve a Dashboard → Forms → Create Form. Dale un nombre y un slug (p. ej. contact-form).

2. Añade campos

Cada campo tiene:

3. Configura los ajustes

4. Publica

Cambia el estado a Published. Copia su ID de formulario — lo referenciarás desde tu bloque.

Usar formularios en bloques personalizados

Referenciar un formulario

Añade un campo formId al esquema de tu bloque y pega en él el ID del formulario publicado desde el editor:

// 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!" }),
  },
});

Renderizar el formulario

El SDK resuelve automáticamente cualquier formulario referenciado por el formId de un bloque e inyecta la definición en el context del bloque como context.forms[formId] — sin necesidad de hacer fetch:

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

Enviar el formulario

Envía desde una server action usando client.queryScoped con la mutación exportada SUBMIT_FORM_MUTATION. Valida los campos, guarda el envío, manda notificaciones por email, llama al webhook si existe y devuelve una respuesta de éxito/error:

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

Bloques de formulario de referencia

Cmssy no incluye bloques — en el modelo headless construyes los bloques en tu propio repo con el SDK. Estos son bloques de formulario habituales que puedes implementar como patrones de referencia; cada uno conecta un formulario del Form Builder (su actionType) con un bloque que tú renderizas:

Cada uno define el formulario en el servidor con el Form Builder y lo renderiza en un bloque mediante un campo formId — el markup es del desarrollador. Consulta Autenticación de miembros para los flujos de autenticación.

Envíos de formulario

Ver los envíos

Ve a Dashboard → Forms → [Tu formulario] → Submissions. Cada envío muestra:

• Todos los valores de los campos
• Estado (pending, processed, spam, archived)
• Dirección IP, user agent, referrer
• Marca de tiempo
• Estado de entrega de email/webhook

Ciclo de vida de un envío

1. El usuario envía el formulario en tu sitio publicado
2. El servidor valida los campos y comprueba los límites de frecuencia
3. El envío se guarda con estado pending
4. Se manda la notificación por email a los destinatarios (si está activada)
5. Se llama al webhook (si está configurado)
6. El estado se actualiza a processed

Protección antispam

Los formularios incluyen limitación de frecuencia integrada:

• Límite por IP y por formulario
• Soporte opcional de captcha
• Los campos honeypot se pueden añadir con el tipo de campo hidden

Referencia de tipos de acción

contact

Guarda el envío + manda un email a los destinatarios configurados. El valor por defecto para la mayoría de formularios.

newsletter

Suscribe el campo de email a la lista de newsletter del workspace.

login / register

Gestiona la autenticación. Son tipos de acción especiales usados por los bloques de formulario de autenticación que construyes (consulta Autenticación de miembros).

custom

Envía los datos del envío como JSON por POST a tu URL de webhook. Útil para integrarte con servicios externos (Zapier, Slack, CRMs, etc.).

Consejos

• Publica siempre tu formulario antes de referenciarlo — los formularios en borrador no se pueden resolver
• Usa los anchos half y third para crear diseños de varias columnas (p. ej. nombre + apellidos lado a lado)
• Etiquetas multilingües — los campos de formulario admiten etiquetas y placeholders por idioma, en línea con el sistema de idiomas del sitio
• Los envíos de prueba se guardan como los reales — bórralos de la pestaña Submissions cuando termines
• Depuración de webhooks — revisa el campo webhookResponse del envío para ver los detalles de la respuesta de tu endpoint