Introduction

Manage dynamic forms with real-time submissions and data collection.

🎯 What does this module do?

The Forms module lets you retrieve forms - contact forms, surveys, registrations, feedback forms - and collect user submissions with validation, file uploads, and automated notifications.

Think of it as your form builder - you create forms in OneEntry admin panel, display them in your app, and collect responses automatically.

📖 Simple Explanation

Imagine you need to collect information from users:

• 📞 Contact Form - name, email, message, phone
• 📋 Survey - multiple choice questions, ratings
• 👤 Registration Form - user details, preferences
• 💼 Job Application - resume upload, cover letter
• 📝 Feedback Form - ratings, comments, suggestions
• 🎟️ Event Registration - attendee info, ticket selection

Instead of building forms from scratch:

• ✅ Create forms in OneEntry admin panel (drag & drop fields)
• ✅ Fetch form structure dynamically
• ✅ Submit data to OneEntry (automatic storage)
• ✅ Validate fields (required, email format, file types)
• ✅ Get notifications when forms are submitted
• ✅ View responses in admin dashboard

Real-world example:

Without Forms Module (manual):
- Build form HTML/validation manually ❌
- Set up backend to store submissions ❌
- Create database tables ❌
- Build admin panel to view responses ❌
- Write email notification code ❌

With Forms Module (automated):
- Create form in admin panel ✅
- Fetch form structure via API ✅
- Submit data → Auto-stored ✅
- View responses in dashboard ✅
- Auto email notifications ✅

✨ Key Concepts

What is a Form?

A form is a structured way to collect information from users:

• Fields - Input elements (text, email, checkboxes, file upload)
• Validation - Rules (required, format, min/max length)
• Submissions - User responses stored in database
• Structure - Form layout defined in OneEntry
• Dynamic - Fetch form structure from API, render in your app

Form Lifecycle

1. Create form in OneEntry admin
   ↓
2. Define fields (name, email, message, etc.)
   ↓
3. Set validation rules
   ↓
4. Fetch form structure via SDK
   ↓
5. Render form in your app
   ↓
6. User fills form
   ↓
7. Submit data to OneEntry
   ↓
8. Validation happens
   ↓
9. Data stored in database
   ↓
10. Notifications sent (email, webhook)

Form Field Types

Common field types you can use:

Field Type	Description	Example Use
text	Short text input	Name, Title, City
email	Email address with validation	Contact email
textarea	Multi-line text	Message, Comments, Bio
number	Numeric input	Age, Quantity, Phone
checkbox	Single checkbox or multiple	Terms agreement, Preferences
radio	Single choice from options	Gender, Size, Plan
select	Dropdown menu	Country, Category, Status
file	File upload	Resume, Photo, Document
date	Date picker	Birth date, Event date

📋 What You Need to Know

1. Form Structure

Every form has these key fields:

{
  id: 123,
  marker: "contact_form",   // Unique identifier
  localizeInfos: {
    title: "Contact Us",    // Form title
    description: "Get in touch" // Form description
  },
  fields: [   // Form fields
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Name" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
    {
      marker: "email",
      type: "email",
      localizeInfos: { title: "Email" },
      isRequired: true,
      validation: { format: "email" }
    },
    {
      marker: "message",
      type: "textarea",
      localizeInfos: { title: "Message" },
      isRequired: true,
      validation: { minLength: 10 }
    }
  ],
  statusId: 1,                 // 1 = active, 0 = draft
  isActive: true,              // Is form enabled
  successMessage: "Thank you!" // Message after submission
}

2. Field Validation

Each field can have validation rules:

{
  marker: "email",
  type: "email",
  isRequired: true, // Must be filled
  validation: {
    format: "email",  // Must be valid email
    minLength: 5,     // Min 5 characters
    maxLength: 100,   // Max 100 characters
    pattern: "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Custom regex
  }
}

Common validation rules:

• isRequired - Field must be filled
• minLength - Minimum text length
• maxLength - Maximum text length
• format - Email, phone, URL format
• pattern - Custom regex pattern
• min / max - Number range
• fileTypes - Allowed file extensions
• maxFileSize - Maximum file size

3. Form Identification

Two ways to identify forms:

Method	When to Use	Example
By Marker	Reference in code (best practice)	contact_form, survey_2024
List All	Show all available forms	getForms()

Best practice: Always use markers in your code (they never change).

📊 Quick Reference Table - Methods

Method	What It Does	When to Use
getAllForms()	Get all forms (paginated)	List all available forms
getFormByMarker()	Get form by marker	Fetch specific form in code

Note: To create/edit forms, use OneEntry admin panel. The SDK is for fetching forms and submitting data.

❓ Common Questions (FAQ)

Q: How do I create or edit forms?

A: Forms are created in OneEntry admin panel:

1. Log in to OneEntry admin
2. Go to Forms section
3. Create new form or edit existing
4. Add fields (drag & drop)
5. Configure validation rules
6. Activate the form

The SDK is for fetching forms and submitting data, not creating forms.

Q: How do I validate form data before submitting?

A: Use browser validation + manual checks:

Q: Can I upload files with forms?

A: Yes! Use FileUploading or file objects:

Learn more: FormsData Module

Q: Can I send custom notifications when form is submitted?

A: Yes, configure in OneEntry admin panel:

• Email notifications to admin/user
• Webhook notifications to your server
• Integration with Events module

Q: How do I handle form submission errors?

A: Always use try/catch

Q: Can forms have conditional fields (show/hide based on other fields)?

A: Not directly in SDK, but you can implement in your UI

💡 Important Notes

Forms are Created in Admin Panel

Remember: The SDK is for fetching forms and submitting data, not creating forms.

To create/edit forms: Use OneEntry admin panel or Admin API.

Always Validate Data

Client-side validation is not enough:

• ✅ Validate on client (better UX)
• ✅ Validate on server (OneEntry does this automatically)

Handle File Uploads Carefully

Best practices for file uploads:

• ✅ Validate file type before upload
• ✅ Check file size limits
• ✅ Show upload progress
• ✅ Handle upload errors

🎓 Best Practices

Do's:

• ✅ Use markers to reference forms (not IDs)
• ✅ Validate data on client and server
• ✅ Show loading states during submission
• ✅ Provide clear error messages
• ✅ Disable submit button after successful submission
• ✅ Clear form after successful submission
• ✅ Handle file upload errors gracefully
• ✅ Use try/catch for error handling

Don'ts:

• ❌ Hardcode form IDs in code
• ❌ Submit forms without validation
• ❌ Ignore error handling
• ❌ Allow duplicate submissions
• ❌ Upload files without size/type validation
• ❌ Show technical errors to users
• ❌ Forget to provide user feedback
• ❌ Skip loading states

More information about the module's user interface https://doc.oneentry.cloud/docs/forms/introduction

Definition of the Forms module

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

Advanced usage examples can be found in the Forms Introduction.

---

🔗 Related Documentation

• FormsData Module - View and manage form submissions
• Events Module - Set up automated notifications on form submit
• FileUploading Module - Handle file uploads in forms
• Users Module - Manage users who submit forms

---