Introduction

Handle form submissions and retrieve form data.

🎯 What does this module do?

The FormData module allows you to submit user-filled forms (contact forms, surveys, registrations) to OneEntry and retrieve submitted data for analysis, reporting, and management.

Think of it as your form submission manager - users submit forms, you store them in OneEntry, and retrieve them whenever you need to view responses, generate reports, or analyze data.

---

📖 Simple Explanation

Imagine you have a contact form on your website. When users fill it out:

1. Submit - User clicks "Send" → Form data goes to OneEntry
2. Store - OneEntry saves the submission (name, email, message)
3. Retrieve - You fetch submissions to view, export, or analyze
4. Manage - Filter, search, and organize form responses

Real-world workflow:

User fills contact form
↓
postFormsData() → Saved in OneEntry
↓
getFormsDataByMarker() → OneEntry returns data
↓
Admin views submissions 

What you can do:

• 📤 Submit forms - Send user-filled data to OneEntry
• 📥 View submissions - Get all form responses with pagination
• 🔍 Search submissions - Find specific submissions by marker or filter
• 📊 Export data - Retrieve submissions for reports and analysis
• 📧 Manage responses - Track form submissions in one place

Example scenarios:

Scenario	What Happens
Contact Form	User submits → You receive email notification → View in dashboard
Survey	Collect responses → Export to CSV → Analyze results
Registration	User signs up → Data stored → Send confirmation email
Feedback	Customer leaves feedback → Team reviews → Reply to customer

---

✨ Key Concepts

What is Form Data?

Form data is the information users submit through forms.

Form Submission Structure

Each submission in OneEntry has:

  const body: IBodyPostFormData = {
    formIdentifier: 'contact_form', // Form marker
    formModuleConfigId: 9,          // Module config ID
    moduleEntityIdentifier: 'blog', // Module entity identifier
    replayTo: null,                 // Email address to reply to
    status: 'sent',                 // Submission status
    formData: [                     // Form fields
      {
        marker: 'string',           // Field marker
        type: 'string',             // Field type
        value: 'Test',              // Field value
      },
    ]
  };

Form Data Lifecycle

1. User fills form in browser
   ↓
2. Frontend validates input
   ↓
3. postFormsData() sends to OneEntry
   ↓
4. OneEntry validates & stores form data submission
   ↓
5. Notifications sent (email, webhook)
   ↓
6. Admin retrieves with getFormsDataByMarker()
   ↓
7. Review, export, or respond

Common Use Cases

Use Case	Description	Example
Contact Forms	Customers reach out with questions	Support team reviews and responds
Lead Generation	Collect potential customer info	Sales team follows up
Surveys	Gather feedback and opinions	Marketing analyzes results
Registrations	Sign up for events, newsletters	Track attendees/subscribers
Job Applications	Collect resumes and cover letters	HR reviews candidates
Feedback Forms	Customer satisfaction and reviews	Improve products/services

---

📋 What You Need to Know

Submitting Forms Requires Configuration

Before submitting, you need:

1. Form marker - Unique form text identifier
2. Form module config ID - From form settings
3. Module entity identifier - From form config

How to get these:

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

// Extract required IDs
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Now you can submit

Why needed? OneEntry needs to know:

• Which form template to use
• Where to store the data
• What validation rules to apply

Form Data Structure

The formData array contains field objects:

formData: [
  {
    marker: "field_name", // Field identifier
    type: "text"          // Field type
    value: "user_input",  // User's input
  }
]

Important:

• marker must match field markers from form definition
• type helpful for validation
• value contains user input

Submission Status

Use status to track submission state:

Status	Meaning	When to Use
"sent"	Successfully submitted	Default for new submissions
"pending"	Awaiting review	Moderation required
"processed"	Handled by admin	Marked as reviewed
"archived"	Old/closed submission	Keep for records

Pagination

Retrieve submissions in batches.

Form Marker

One way to identify submissions:

Identifier	What It Is	When to Use
Form Marker	Form template identifier	Get all submissions for a specific form

---

📊 Quick Reference Table

Method	Description	Use Case
postFormsData()	Submit new form data	User submits contact form
getFormsDataByMarker()	Get submissions for specific form	View all contact form submissions

❓ Frequently Asked Questions (FAQ)

How do I submit a form?

You need three things:

1. Form configuration from Forms.getFormByMarker()
2. User input data
3. Call FormData.postFormsData()

---

Can I update submitted form data?

Not directly. Form submissions are typically immutable to maintain data integrity.

Workarounds:

• Submit a new version with updated data
• Use status field to mark old submissions as obsolete
• Implement custom update logic in your frontend

---

How do I handle file uploads in forms?

Simply use File or FileList with FormData.postFormsData() or Upload files separately using FileUploading module, then include file URLs in form data.

---

How do I filter submissions by date?

Use body parameters dateFrom and dateTo.

---

Can I search submissions by field value?

Yes, fetch submissions and search client-side.

---

How do I paginate through all submissions?

Use offset and limit.

---

How do I handle validation errors?

Use try/catch and check error messages.

---

💡 Important Notes

⚠️ Form Configuration Required

You cannot submit forms without configuration:

• formModuleConfigId and moduleEntityIdentifier are required
• Get these from Forms.getFormByMarker() before submitting
• Store them in your app to avoid repeated API calls

---

🔒 Security Considerations

Never expose sensitive data:

• Don't submit passwords in plain text
• Validate input on both client and server
• Sanitize user input before displaying

---

📦 Large Data Sets

Pagination is important:

• Don't fetch thousands of submissions at once
• Use limit and offset for pagination
• Consider caching for frequently accessed data

---

🔄 Read-Only After Submission

Form data is immutable:

• Cannot update submissions via SDK
• Submit new version if changes needed
• Use status field to track submission state

---

🎓 Best Practices

• Cache form configuration - Avoid fetching on every submission
• Validate before submitting - Check required fields client-side
• Use pagination - Fetch submissions in batches
• Handle errors gracefully - Always use try/catch
• Use markers consistently - Reference forms by marker, not ID
• Track submission status - Use status field to organize submissions
• Export data regularly - Backup submissions to CSV/database
• Monitor new submissions - Implement polling or webhooks

---

Definition of the FormData module

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

Form settings:

1. Get the form by marker using Forms.getFormByMarker('your-form-marker').
2. Use the moduleFormConfigs field from the retrieved form for the configuration used when submitting the form data.
3. Create the body using moduleFormConfig and post form data.

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);

---

🔗 Related Documentation

• Forms Module - Create and manage form structures
• FileUploading Module - Handle file uploads in forms
• Events Module - Set up event-driven notifications
• Users Module - Manage users who submit forms

---