Introduction

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

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

---

🎯 What does this module do?

The Forms module lets you retrieve forms - contact forms, surveys, registrations, feedback forms - so you can render them in your app. You build forms in the OneEntry admin panel; the SDK fetches their structure (fields, validators, localized labels) dynamically. Collecting the actual submissions is handled by the FormsData module.

🚀 Quickstart

Initialize the module from defineOneEntry:

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

Fetch a single form by its marker and read its fields:

// Fetch the "contact_form" form structure.
const form = await Forms.getFormByMarker("contact_form", "en_US");

console.log(form.identifier, form.localizeInfos.title);

// Render each field from the form's attributes.
form.attributes.forEach((field) => {
  console.log(field.marker, field.type, field.localizeInfos.title);
});

To list every form (paginated) use getAllForms(langCode, offset, limit), which returns a { total, items } object.

✨ Key Concepts

What is a Form?

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

• Fields (attributes) - input elements, each an attribute with a type (string, text, file, list, …)
• Validators (validators) - per-field rules (required, string length, email format)
• Structure - layout and localized labels defined in the OneEntry admin
• Submissions - user responses, submitted and retrieved via the FormsData module

Form Field Types

Each field's type is an AttributeType. Common values:

Type (AttributeType)	Description	Example Use
string	Short single-line text	Name, Title, City
text / textWithHeader	Multi-line text	Message, Comments, Bio
integer / real / float	Numeric input	Age, Quantity, Price
date / dateTime / time	Date & time pickers	Birth date, Event date
list	Dropdown / multi-select from options	Country, Category
radioButton	Single choice from options	Size, Plan
file / image	File / image upload	Resume, Photo, Document
groupOfImages	Multiple images	Gallery
entity	Reference to another entity	Linked product or page

Note: Email is a string field with the emailInspectionValidator enabled — there is no separate email field type.

📋 What You Need to Know

Form Structure

Every form (IFormsEntity) carries an id, an identifier (marker), an optional type ('order' | 'sing_in_up' | 'collection' | 'data' | 'rating' | null), localizeInfos (title, success message, …) and an attributes array of fields. Each field has a marker, type, localizeInfos, and a validators object:

{
  "marker": "email",
  "type": "string",
  "localizeInfos": { "title": "Email" },
  "validators": {
    "requiredValidator": { "strict": true },
    "emailInspectionValidator": true,
    "stringInspectionValidator": { "stringMin": 5, "stringMax": 100, "stringLength": 0 }
  }
}

Common validators:

• requiredValidator — { strict: boolean }, field must be filled
• stringInspectionValidator — { stringMin, stringMax, stringLength }, text length constraints
• emailInspectionValidator — boolean, enforce email format
• defaultValueValidator — default value plus optional custom error text

The validator set is extensible — additional validator types may be returned by the API.

Forms are created in the admin panel

The SDK is for fetching forms (and, via the FormsData module, submitting data) — not for creating or editing forms. To build or change a form, use the OneEntry admin panel: open the Forms section, add fields, configure validation rules, and activate the form.

---

📊 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

Both methods are public — no user authorization required.

---

❓ Common Questions (FAQ)

How do I create or edit forms?

Forms are created and edited in the OneEntry admin panel (Forms section), not via the SDK. The SDK only fetches form structures and submits data.

---

Can I upload files with forms?

Yes. Add a file / image / groupOfImages field to your form; submissions with files are handled by FormData.postFormsData(), which uploads them through the FileUploading module automatically. See the FormsData module.

---

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

Not directly in the SDK — implement show/hide logic in your own UI based on the fetched form's field values.

---

🎓 Best Practices

• Reference forms by their identifier (marker), not by numeric ID.
• Render fields and required state from each field's validators so your UI matches server-side validation.
• Use try/catch around fetches and handle the IError return shape.

---

🔗 Related Documentation

• FormsData Module - Submit 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

---