Introduction

Handle form submissions and retrieve form data.

🎯 What does this module do?

The FormData module lets you 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
                                                              ↓
Admin views submissions ← getFormsData() ← OneEntry returns data

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',
    formModuleConfigId: 9,
    moduleEntityIdentifier: 'blog',
    replayTo: null,
    status: 'sent',
    formData: [
      {
        marker: 'string',
        type: 'string',
        value: 'Test',
      },
      {
        marker: 'number',
        type: 'integer',
        value: 1,
      },
    ]
  };

Form Data Lifecycle

1. User fills form in browser
   ↓
2. Frontend validates input
   ↓
3. postFormsData() sends to OneEntry
   ↓
4. OneEntry validates & stores submission
   ↓
5. Notifications sent (email, webhook)
   ↓
6. Admin retrieves with getFormsData()
   ↓
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

1. Submitting Forms Requires Configuration

Before submitting, you need:

1. Form marker - Unique form 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

2. Form Data Structure

The formData array contains field objects:

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

Important:

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

3. 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

4. Pagination

Retrieve submissions in batches:

5. 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	Returns	Use Case
postFormsData()	Submit new form data	Promise<Submission>	User submits contact form
getFormsData()	Get all submissions (paginated)	Promise<{ items: [], total }>	Admin dashboard showing all forms
getFormsDataByMarker()	Get submissions for specific form	Promise<{ items: [], total }>	View all contact form submissions

---

❓ Frequently Asked Questions (FAQ)

1. How do I submit a form?

You need three things:

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

---

2. 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 backend

---

3. How do I handle file uploads in forms?

Upload files separately using FileUploading module, then include file URLs in form data:

---

4. How do I filter submissions by date?

Fetch all submissions and filter client-side

---

5. Can I search submissions by field value?

Yes, fetch submissions and search client-side

---

6. How do I paginate through all submissions?

Use offset and limit

---

7. What's the difference between getFormsData() and getFormsDataByMarker()?

Method	What It Returns	When to Use
getFormsData()	All submissions from all forms	Admin dashboard showing everything
getFormsDataByMarker()	Submissions for one specific form	View only contact form submissions

---

8. 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

✅ DO:

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

---

❌ DON'T:

1. Don't submit without configuration - Will fail
2. Don't fetch all at once - Use pagination
3. Don't ignore errors - Handle failures
4. Don't expose sensitive data - Validate and sanitize
5. Don't submit duplicate data - Check before submitting
6. Don't hardcode form IDs - Use markers
7. Don't forget validation - Validate all fields
8. Don't mix form types - Keep submissions organized

---

Define 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

---