Formularze i Form Builder

Przegląd

Cmssy posiada wbudowany Form Builder, który pozwala tworzyć formularze wizualnie i podłączać je do dowolnego custom bloku. Formularze obsługują walidację, zgłoszenia, powiadomienia email i webhooki — bloki muszą tylko renderować UI.

System składa się z dwóch części:

1. Form Builder (Dashboard > Formularze) — definiowanie pól, walidacji i akcji
2. Pole formId na bloku — przechowuje, który formularz blok ma renderować

Tworzenie formularza

1. Otwórz Form Builder

Przejdź do Dashboard → Formularze → Utwórz formularz. Nadaj nazwę i slug (np. formularz-kontaktowy).

2. Dodaj pola

Każde pole posiada:

3. Skonfiguruj ustawienia

4. Opublikuj

Ustaw status na Opublikowany. Skopiuj jego ID formularza — będziesz się do niego odwoływać z bloku.

Używanie formularzy w custom blokach

Odwołanie do formularza

Dodaj pole formId do schema bloku i wklej w nie ID opublikowanego formularza z edytora:

// 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: "Formularz", helperText: "Wklej ID formularza z Form Buildera" }),
    submitLoadingText: fields.singleLine({ label: "Tekst ładowania", defaultValue: "Wysyłanie..." }),
    successHeading: fields.singleLine({ label: "Nagłówek sukcesu", defaultValue: "Wiadomość wysłana!" }),
  },
});

Renderowanie formularza

SDK automatycznie pobiera każdy formularz wskazany przez formId bloku i wstrzykuje jego definicję do context bloku jako context.forms[formId] — bez ręcznego pobierania:

// blocks/contact/src/Contact.tsx
export default function Contact({ content, context }) {
  const { formId } = content;
  const formDef = formId ? context?.forms?.[formId] ?? null : null;
  // formDef.fields   - tablica definicji pól
  // formDef.settings - tekst przycisku, wiadomości, typ akcji
  // ...wyrenderuj pola
}

Wysyłanie formularza

Wyślij z server action używając client.queryScoped z eksportowaną SUBMIT_FORM_MUTATION. Waliduje pola, zapisuje zgłoszenie, wysyła powiadomienia email, wywołuje webhook i zwraca odpowiedź sukces/błąd:

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

Referencyjne bloki formularzy

Cmssy nie dostarcza bloków — w modelu headless bloki budujesz w swoim repozytorium za pomocą SDK. To typowe bloki formularzy, które możesz zaimplementować jako wzorce referencyjne, każdy podłącza formularz z Form Buildera (jego actionType) do bloku renderowanego przez Ciebie:

Każdy definiuje formularz po stronie serwera w Form Builderze i renderuje go w bloku przez pole formId — markup należy do dewelopera. Zobacz Uwierzytelnianie członków po flow auth.

Zgłoszenia formularzy

Przeglądanie zgłoszeń

Przejdź do Dashboard → Formularze → [Twój formularz] → Zgłoszenia. Każde zgłoszenie pokazuje:

• Wszystkie wartości pól
• Status (pending, processed, spam, archived)
• Adres IP, user agent, referrer
• Znacznik czasu
• Status dostarczenia email/webhook

Cykl życia zgłoszenia

1. Użytkownik wysyła formularz na Twojej opublikowanej stronie
2. Serwer waliduje pola i sprawdza limity częstotliwości
3. Zgłoszenie zapisane ze statusem pending
4. Powiadomienie email wysłane do odbiorców (jeśli włączone)
5. Webhook wywołany (jeśli skonfigurowany)
6. Status zaktualizowany na processed

Ochrona przed spamem

• Limit per-IP na formularz
• Opcjonalna obsługa captcha
• Pola honeypot można dodać jako pole typu hidden

Typy akcji - referencja

contact

Zapisuje zgłoszenie + wysyła email do skonfigurowanych odbiorców. Domyślny dla większości formularzy.

newsletter

Subskrybuje pole email do listy newslettera workspace.

login / register

Obsługuje uwierzytelnianie. Specjalne typy akcji używane przez bloki formularzy auth, które budujesz (zobacz Uwierzytelnianie członków).

custom

Wysyła dane zgłoszenia jako JSON POST na URL webhooka. Przydatne do integracji z zewnętrznymi serwisami (Zapier, Slack, CRM, itp.).

Wskazówki

• Zawsze opublikuj formularz zanim się do niego odwołasz — formularze draft nie mogą być pobrane
• Używaj szerokości half i third aby tworzyć wielokolumnowe układy (np. imię + nazwisko obok siebie)
• Wielojęzyczne etykiety — pola formularza wspierają etykiety i placeholdery per-język
• Testowe zgłoszenia są zapisywane jak prawdziwe — usuń je z zakładki Zgłoszenia po zakończeniu
• Debugowanie webhooków — sprawdź pole webhookResponse zgłoszenia