Formularze i Form Builder — Dokumentacja Cmssy

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:

Form Builder (Dashboard > Formularze) — definiowanie pól, walidacji i akcji
Pole typu form — podłączenie formularza do custom bloku przez schema

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:

Właściwość	Opis
name	Unikalny klucz pola (np. `email`, `wiadomosc`)
type	`text`, `email`, `textarea`, `number`, `phone`, `url`, `date`, `select`, `multiselect`, `checkbox`, `radio`, `file`, `hidden`
label	Etykieta wyświetlana (wielojęzyczna)
placeholder	Tekst zastępczy (wielojęzyczny)
validation	`required`, `minLength`, `maxLength`, `minValue`, `maxValue`, `pattern`, `customMessage`
width	`full`, `half` lub `third` — kontroluje szerokość pola w siatce
options	Dla `select`, `multiselect`, `radio` — tablica `{ value, label }`
order	Kolejność wyświetlania

3. Skonfiguruj ustawienia

Ustawienie	Opis
Typ akcji	`contact` (email + zapis), `newsletter` (subskrypcja), `login`, `register`, `custom` (webhook)
Odbiorcy email	Lista emaili otrzymujących powiadomienia
Webhook URL	Dla akcji `custom` — POST danych na zewnętrzny endpoint
Wiadomość sukcesu	Wyświetlana po udanym wysłaniu (wielojęzyczna)
Wiadomość błędu	Wyświetlana przy niepowodzeniu (wielojęzyczna)
Tekst przycisku	Tekst na przycisku submit (wielojęzyczny)
Zapisuj zgłoszenia	Przechowuj zgłoszenia w bazie (domyślnie: `true`)
Wysyłaj powiadomienia	Email do odbiorców przy każdym zgłoszeniu (domyślnie: `true`)
Włącz Captcha	Ochrona przed spamem
Wymagaj logowania	Tylko zalogowani użytkownicy mogą wysłać

4. Opublikuj

Ustaw status na Opublikowany. Tylko opublikowane formularze mogą być wybrane w blokach.

Używanie formularzy w custom blokach

Pole typu `form`

Aby podłączyć formularz do bloku, dodaj pole z type: "form" w schema bloku:

import { field } from "@cmssy/types";

export const schema = [
  field("formId", "form", {
    label: "Formularz",
    helperText: "Wybierz formularz z Form Buildera",
  }),
  field("submitLoadingText", "singleLine", {
    label: "Tekst ładowania",
    defaultValue: "Wysyłanie...",
  }),
  field("successHeading", "singleLine", {
    label: "Nagłówek sukcesu",
    defaultValue: "Wiadomość wysłana!",
  }),
];

W edytorze pole form renderuje dropdown z listą opublikowanych formularzy. Wybrane ID formularza jest zapisywane w content bloku.

Renderowanie formularza

W runtime użyj ID formularza aby pobrać dane przez query publicForm i wyrenderuj pola:

// W komponencie React bloku
const { data } = useQuery(PUBLIC_FORM_QUERY, {
  variables: { workspaceSlug, formSlug },
});

const form = data?.publicForm;
// form.fields - tablica definicji pól
// form.settings - tekst przycisku, wiadomości, typ akcji

Wysyłanie formularza obsługuje mutacja submitForm, która:

Waliduje pola po stronie serwera
Zapisuje zgłoszenie (jeśli włączone)
Wysyła powiadomienia email (jeśli skonfigurowane)
Wywołuje webhook (jeśli skonfigurowany)
Zwraca odpowiedź sukces/błąd

Wbudowane bloki z formularzami

Blok	Typ akcji	Opis
Contact	`contact`	Formularz kontaktowy z kartami info i cytatem
Newsletter Form	`newsletter`	Formularz zapisu do newslettera
Login Form	`login`	Formularz logowania
Register Form	`register`	Formularz rejestracji
Forgot Password Form	`login`	Formularz resetowania hasła

Te bloki używają formId w swoim schema — możesz je sprawdzić jako implementacje referencyjne.

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

Użytkownik wysyła formularz na opublikowanej stronie
Serwer waliduje pola i sprawdza limity częstotliwości
Zgłoszenie zapisane ze statusem pending
Powiadomienie email wysłane do odbiorców (jeśli włączone)
Webhook wywołany (jeśli skonfigurowany)
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 wbudowane bloki auth.

`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 przed wyborem w bloku — formularze draft nie pojawią się w dropdown
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