Formlar
Panelde oluşturulan formların sitede nasıl çizildiği, doğrulandığı ve gönderildiği.
Bu sayfada CMS formlarının sitede nasıl render edildiğini, alan tiplerinin widget'lara nasıl eşlendiğini ve gönderimin hangi yoldan CMS'e ulaştığını öğreneceksin.
Ağaçta form
Panelde bir form bir sayfaya yerleştirildiğinde bileşen ağacında form slug'lı bir kapsayıcı görünür. Kapsayıcının çocukları FormItem yapraklarıdır. Her yaprağın data alanı alan tanımını taşıyan bir JSON'dur.
{
"id": 42, // gönderimde kullanılan form bileşeni kimliği
"uniqueId": 9001,
"slug": "form",
"componentType": "Form",
"children": [
{
"title": "E-posta", // gönderimdeki alan adı
"componentType": "FormItem",
"data": "{\"type\":\"email\",\"label\":\"E-posta\",\"required\":true}"
}
]
}FormContainer bu düğümü registry üzerinden alır, çocukları okur, alanları üretir ve react-hook-form ile zod kullanarak doğrular.
Alan tanımı
FormItem.data içindeki tüm anahtarlar isteğe bağlıdır. CMS her alanı göndermeyebilir.
| Anahtar | Açıklama |
|---|---|
type | Alan tipi. Aşağıdaki tabloya bak. |
label, placeholder | Etiket ve yer tutucu metin. |
description | Alanın altındaki açıklama. Markdown olabilir, örneğin bağlantılı bir onay metni. |
required | Zorunlu alan. |
options | Seçim alanlarının seçenekleri. |
defaultValue, defaultChecked | Varsayılan değer. |
min, max, step | Sayı ve kaydırıcı sınırları. |
rows | Uzun metin yüksekliği. |
accept | Dosya alanının kabul ettiği türler. |
width | "half" ise orta ve geniş ekranlarda yarım sütun kaplar. |
i18n | Dile göre üstteki değerleri ezen kısmi kopyalar. |
Gönderimdeki alan adı, FormItem düğümünün title değeridir.
Alan registry'si
Alan tipleri src/components/cms/form/field-registry.ts içinde widget'lara eşlenir.
| Tip | Widget |
|---|---|
text, email, tel, url, password, time | TextField |
number | NumberField |
textarea | TextareaField |
select | SelectField |
multiselect, checkbox-group | CheckboxGroupField |
radio | RadioField |
checkbox | CheckboxField |
switch | SwitchField |
slider | SliderField |
date, datetime | DateField |
file | FileField |
hidden | HiddenField |
Şablon bazı eş adları da tanır, örneğin dropdown → select, phone → tel, toggle → switch. Registry'de olmayan bir tip TextField'a düşer. Böylece eksik bir widget sayfayı çökertmez, görünür olur.
Yeni bir alan tipi eklemek
Registry'ye bir satır ve fields/ altına bir dosya eklemek yeterlidir.
import RatingField from "./fields/RatingField";
const FIELD_REGISTRY = {
// …
rating: RatingField,
};Yeni tipi src/lib/forms/parse.ts içindeki FIELD_TYPES listesine de eklemeyi unutma. Registry bu listeye göre tiplenir.
Gönderim akışı
Tarayıcı sitenin kendi ucuna gönderir
useFormSubmit doğrulanmış değerleri POST /api/form/{componentId} adresine yollar. Date değerleri ISO metnine çevrilir, boş değerler düşürülür. Gövdeye sayfanın yolu (pagePath) ve sayfa kimliği (pageId) eklenir.
Site rotası isteği CMS'e iletir
src/app/api/form/[componentId]/route.ts başka sitelerden gelen istekleri reddeder ve gövdeyi CMS'in POST /api/v1/form/submit/{componentId} ucuna iletir. Ziyaretçinin IP'si SITE_PROXY_SECRET ile CMS'e iletilir, böylece kayıtlar doğru ziyaretçiyi görür.
CMS doğrular ve kaydeder
Formun var olup olmadığını ve alanları CMS doğrular. Gönderim sonrası e-posta veya webhook gibi eylemler panelde form başına tanımlanır. Site bunları tetiklemez.
Sonuç kullanıcıya gösterilir
Başarılı yanıtta FORM_MESSAGES.submitSuccess, hatada CMS'in errorMessage değeri ya da FORM_MESSAGES.submitError gösterilir.
CMS'e giden gövde şöyledir:
{
"formData": { "E-posta": "[email protected]" },
"languageId": "tr",
"pagePath": "iletisim",
"pageId": 123
}pageId gönderimin dilini ve sayfasını belirler. languageId yoldan çıkarılan yedektir.
Form metinleri
Kullanıcıya gösterilen tüm form metinleri src/lib/template-config.ts içindeki FORM_MESSAGES nesnesindedir: doğrulama mesajları, düğme etiketleri, başarı ve hata metinleri. Metinleri bileşenlere gömme, burada düzenle.
Captcha ve dosya yükleme
API iki ek uç sunar:
GET /api/v1/form/captcha-configcaptcha sağlayıcısını ve site anahtarını döner.providerboşsa captcha kapalıdır.POST /api/v1/form/upload/{componentId}ziyaretçinin seçtiği dosyayı yükler. Yanıttaki dosya yolu gönderimde alanın değeri olarak yollanır.
CMS, captcha sağlayıcısı olarak Google reCAPTCHA v2, reCAPTCHA v3 ve Cloudflare Turnstile'ı destekler. Sağlayıcı ve anahtarlar panelde Ayarlar ekranının Form Güvenliği kategorisinde ayarlanır; captcha bir form alanı değildir. Gizli anahtar tanımlı değilse gönderimde captcha doğrulaması atlanır. Bkz. Ayarlar.
Dosya yükleme ucu captcha doğrulaması ister. Varsayılan boyut sınırı 5 MB'dir. İzin verilen uzantılar: .pdf, .doc, .docx, .xls, .xlsx, .txt, .csv, .jpg, .jpeg, .png. Yüklenen görseller webp biçimine dönüştürülür.
Site şablonunda henüz desteklenmiyor
Site şablonunun güncel sürümünde captcha widget'ı yoktur; gönderim captcha anahtarı göndermez. Panelde captcha sağlayıcısı ve anahtarı tanımlıysa bu şablondan yapılan gönderimler doğrulamadan geçemeyebilir. Şablondaki file alanı dosyanın kendisini yüklemez, gövdeye yalnızca dosya adını yazar. Panelde de dosya türündeki form alanları şimdilik kapalıdır.