Giriş

Form gönderimlerini yönetin ve form verilerini alın.

🎯 Bu modül ne yapar?

FormData modülü, kullanıcı tarafından doldurulan formları (iletişim formları, anketler, kayıtlar) OneEntry'ye göndermenizi ve gönderilen verileri analiz, raporlama ve yönetim için almanızı sağlar.

Bunu form gönderim yöneticiniz olarak düşünün - kullanıcılar formları gönderir, siz bunları OneEntry'de saklarsınız ve yanıtları görüntülemek, raporlar oluşturmak veya verileri analiz etmek istediğinizde geri alırsınız.

---

📖 Basit Açıklama

Web sitenizde bir iletişim formunuz olduğunu hayal edin. Kullanıcılar bunu doldurduğunda:

1. Gönder - Kullanıcı "Gönder" butonuna tıklar → Form verileri OneEntry'ye gider
2. Sakla - OneEntry gönderimi kaydeder (isim, e-posta, mesaj)
3. Al - Gönderimleri görüntülemek, dışa aktarmak veya analiz etmek için alırsınız
4. Yönet - Form yanıtlarını filtreleyin, arayın ve düzenleyin

Gerçek dünya iş akışı:

Kullanıcı iletişim formunu doldurur
↓
postFormsData() → OneEntry'de kaydedildi
↓
getFormsDataByMarker() → OneEntry verileri döner
↓
Admin gönderimleri görüntüler 

Yapabilecekleriniz:

• 📤 Formları gönderin - Kullanıcı tarafından doldurulan verileri OneEntry'ye gönderin
• 📥 Gönderimleri görüntüleyin - Tüm form yanıtlarını sayfalandırma ile alın
• 🔍 Gönderimleri arayın - Belirli gönderimleri işaretleyici veya filtre ile bulun
• 📊 Verileri dışa aktarın - Raporlar ve analiz için gönderimleri alın
• 📧 Yanıtları yönetin - Form gönderimlerini tek bir yerde takip edin

Örnek senaryolar:

Senaryo	Ne Olur
İletişim Formu	Kullanıcı gönderir → E-posta bildirimi alırsınız → Gösterge panelinde görüntüleyin
Anket	Yanıtları toplayın → CSV'ye dışa aktarın → Sonuçları analiz edin
Kayıt	Kullanıcı kaydolur → Veri saklanır → Onay e-postası gönderin
Geri Bildirim	Müşteri geri bildirim bırakır → Ekip inceler → Müşteriye yanıt verin

---

✨ Temel Kavramlar

Form Verisi Nedir?

Form verisi, kullanıcıların formlar aracılığıyla gönderdiği bilgilerdir.

Form Gönderim Yapısı

OneEntry'deki her gönderim şunları içerir:

  const body: IBodyPostFormData = {
    formIdentifier: 'contact_form', // Form işaretleyici
    formModuleConfigId: 9,          // Modül yapılandırma ID'si
    moduleEntityIdentifier: 'blog', // Modül varlık işaretleyici
    replayTo: null,                 // Yanıt verilecek e-posta adresi
    status: 'sent',                 // Gönderim durumu
    formData: [                     // Form alanları
      {
        marker: 'string',           // Alan işaretleyici
        type: 'string',             // Alan türü
        value: 'Test',              // Alan değeri
      },
    ]
  };

Form Verisi Yaşam Döngüsü

1. Kullanıcı tarayıcıda formu doldurur
   ↓
2. Ön uç girişi doğrular
   ↓
3. postFormsData() OneEntry'ye gönderir
   ↓
4. OneEntry form verisi gönderimini doğrular ve saklar
   ↓
5. Bildirimler gönderilir (e-posta, webhook)
   ↓
6. Admin getFormsDataByMarker() ile alır
   ↓
7. İnceleme, dışa aktarma veya yanıt verme

Yaygın Kullanım Durumları

Kullanım Durumu	Açıklama	Örnek
İletişim Formları	Müşteriler sorularla ulaşır	Destek ekibi inceler ve yanıt verir
Potansiyel Müşteri	Potansiyel müşteri bilgilerini toplar	Satış ekibi takip eder
Anketler	Geri bildirim ve görüş toplar	Pazarlama sonuçları analiz eder
Kayıtlar	Etkinlikler, bültenler için kaydolur	Katılımcıları/aboneleri takip eder
İş Başvuruları	Özgeçmiş ve ön yazıları toplar	İK adayları inceler
Geri Bildirim Formları	Müşteri memnuniyeti ve incelemeleri	Ürün/hizmetleri geliştirin

---

📋 Bilmeniz Gerekenler

Form Gönderimi Yapılandırma Gerektirir

Göndermeden önce şunlara ihtiyacınız var:

1. Form işaretleyici - Benzersiz form metin tanımlayıcı
2. Form modül yapılandırma ID'si - Form ayarlarından
3. Modül varlık işaretleyici - Form yapılandırmasından

Bunları nasıl alırsınız:

// Formu al
const form = await Forms.getFormByMarker('contact_form');

// Gerekli ID'leri çıkar
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Artık gönderebilirsiniz

Neden gerekli? OneEntry'nin bilmesi gerekenler:

• Hangi form şablonunun kullanılacağı
• Verilerin nerede saklanacağı
• Hangi doğrulama kurallarının uygulanacağı

Form Verisi Yapısı

formData dizisi alan nesnelerini içerir:

formData: [
  {
    marker: "field_name", // Alan tanımlayıcı
    type: "text"          // Alan türü
    value: "user_input",  // Kullanıcının girişi
  }
]

Önemli:

• marker, form tanımındaki alan işaretleyicileri ile eşleşmelidir
• type, doğrulama için faydalıdır
• value, kullanıcı girişini içerir

Gönderim Durumu

Gönderim durumunu takip etmek için status kullanın:

Durum	Anlamı	Ne Zaman Kullanılır
"sent"	Başarıyla gönderildi	Yeni gönderimler için varsayılan
"pending"	İnceleme bekliyor	Moderasyon gerektiriyor
"processed"	Admin tarafından işlendi	İncelendi olarak işaretlendi
"archived"	Eski/kapatılmış gönderim	Kayıtlar için saklayın

Sayfalandırma

Gönderimleri gruplar halinde alın.

Form İşaretleyici

Gönderimleri tanımlamanın bir yolu:

Tanımlayıcı	Ne Olduğu	Ne Zaman Kullanılır
Form İşaretleyici	Form şablonu tanımlayıcı	Belirli bir form için tüm gönderimleri alın

---

📊 Hızlı Referans Tablosu

Yöntem	Açıklama	Kullanım Durumu
postFormsData()	Yeni form verisi gönderin	Kullanıcı iletişim formunu gönderir
getFormsDataByMarker()	Belirli form için gönderimleri alın	Tüm iletişim formu gönderimlerini görüntüleyin

❓ Sıkça Sorulan Sorular (SSS)

Bir formu nasıl gönderirim?

Üç şeye ihtiyacınız var:

1. Forms.getFormByMarker()'dan form yapılandırması
2. Kullanıcı girişi verileri
3. FormData.postFormsData() çağrısı

---

Gönderilen form verilerini güncelleyebilir miyim?

Doğrudan hayır. Form gönderimleri genellikle veri bütünlüğünü korumak için değiştirilemez.

Alternatifler:

• Güncellenmiş verilerle yeni bir versiyon gönderin
• Eski gönderimleri geçersiz olarak işaretlemek için status alanını kullanın
• Ön uçta özel güncelleme mantığı uygulayın

---

Formlarda dosya yüklemelerini nasıl yönetirim?

Basitçe File veya FileList kullanarak FormData.postFormsData() ile veya Dosyaları ayrı olarak FileUploading modülünü kullanarak yükleyin, ardından form verilerinde dosya URL'lerini dahil edin.

---

Gönderimleri tarihe göre nasıl filtrelerim?

Gövde parametrelerini dateFrom ve dateTo kullanın.

---

Gönderimleri alan değeriyle arayabilir miyim?

Evet, gönderimleri alın ve istemci tarafında arayın.

---

Tüm gönderimlerde nasıl sayfalandırırım?

Offset ve limit kullanın.

---

Doğrulama hatalarını nasıl yönetirim?

Try/catch kullanın ve hata mesajlarını kontrol edin.

---

💡 Önemli Notlar

⚠️ Form Yapılandırması Gereklidir

Yapılandırma olmadan formları gönderemezsiniz:

• formModuleConfigId ve moduleEntityIdentifier zorunludur
• Göndermeden önce bunları Forms.getFormByMarker()'dan alın
• Tekrar eden API çağrılarını önlemek için uygulamanızda saklayın

---

🔒 Güvenlik Hususları

Hassas verileri asla açığa çıkarmayın:

• Parolaları düz metin olarak göndermeyin
• Girişi hem istemci hem de sunucu tarafında doğrulayın
• Kullanıcı girişini görüntülemeden önce temizleyin

---

📦 Büyük Veri Setleri

Sayfalandırma önemlidir:

• Binlerce gönderimi bir anda almayın
• Sayfalandırma için limit ve offset kullanın
• Sık erişilen veriler için önbellekleme düşünün

---

🔄 Gönderimden Sonra Salt Okunur

Form verisi değiştirilemez:

• SDK aracılığıyla gönderimleri güncelleyemezsiniz
• Değişiklik gerekiyorsa yeni bir versiyon gönderin
• Gönderim durumunu takip etmek için status alanını kullanın

---

🎓 En İyi Uygulamalar

• Form yapılandırmasını önbelleğe alın - Her gönderimde almak için önlem alın
• Göndermeden önce doğrulayın - Gerekli alanları istemci tarafında kontrol edin
• Sayfalandırmayı kullanın - Gönderimleri gruplar halinde alın
• Hataları nazikçe yönetin - Her zaman try/catch kullanın
• İşaretleyicileri tutarlı kullanın - Formları işaretleyici ile referans alın, ID ile değil
• Gönderim durumunu takip edin - Gönderimleri düzenlemek için durum alanını kullanın
• Verileri düzenli olarak dışa aktarın - Gönderimleri CSV/veritabanına yedekleyin
• Yeni gönderimleri izleyin - Anket veya webhook uygulayın

---

FormData modülünün tanımı

const { FormData } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Form ayarları:

1. Forms.getFormByMarker('your-form-marker') kullanarak formu işaretleyici ile alın.
2. Form verilerini gönderirken kullanılan yapılandırma için alınan formdan moduleFormConfigs alanını kullanın.
3. Gövdeyi moduleFormConfig kullanarak oluşturun ve form verilerini gönderin.

const formModuleConfigId = moduleFormConfigs[0].id;
const moduleEntityIdentifier = moduleFormConfigs[0].entityIdentifiers[0].id;
const body = {
  "formIdentifier": "your-form-marker",
  "formModuleConfigId": formModuleConfigId,
  "moduleEntityIdentifier": moduleEntityIdentifier,
  "replayTo": null,
  "status": "sent",
  "formData": [...]
};
const response = await FormData.postFormsData(body);

---

🔗 İlgili Belgeler

• Formlar Modülü - Form yapılarını oluşturun ve yönetin
• FileUploading Modülü - Formlarda dosya yüklemelerini yönetin
• Etkinlikler Modülü - Olay odaklı bildirimleri ayarlayın
• Kullanıcılar Modülü - Form gönderen kullanıcıları yönetin

---