Forms
Fetch the forms you build in the admin panel: their fields, validators and localized labels.
More information about the module's user interface https://doc.oneentry.cloud/docs/category/forms (opens in a new tab)
The Forms module retrieves forms (contact forms, surveys, registrations, feedback forms) so you can render them in your app. You build forms in the OneEntry admin panel, and the SDK fetches their structure dynamically: fields, validators and localized labels. Submissions are handled by the FormData module.
Quickstart
Initialize the module from defineOneEntry:
const { } = defineOneEntry( , { });
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");
if ('statusCode' in form) {
console.error(form.message); // IError, e.g. 404 for an unknown marker
} else {
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 all forms with pagination, use getAllForms(langCode, offset, limit). It returns a { total, items } object.
What a form contains
A form (IFormsEntity) is a structured way to collect information from users. It consists of:
- fields (
attributes): input elements, each an attribute with atype(string,text,file,list, …); - validators (
validators): per-field rules such as required, string length and email format; - structure: the layout and localized labels defined in the OneEntry admin panel.
User responses (submissions) are submitted and retrieved through the FormData module.
Reference forms by their identifier (marker), not by numeric ID.
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 |
There is no separate email field type: an email field is a string field with emailInspectionValidator enabled.
Form structure
Every form (IFormsEntity) has an id, an identifier (marker), an optional type ('order' | 'sign_in_up' | 'collection' | 'data' | 'rating' | null), localizeInfos (title, success message, …) and an attributes array of fields. Each field has a marker, a 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 }
}
}
Validators
requiredValidator:{ strict: boolean }. The field must be filled in.stringInspectionValidator:{ stringMin, stringMax, stringLength }. Text length constraints.emailInspectionValidator:trueor an object such as{ strict: true }. Enforces the email format.defaultValueValidator: a default value plus optional custom error text.
The set of validators is extensible, and the API may return other validator types. Render fields and their required state from each field's validators, so your UI matches server-side validation.
What the SDK doesn't do
The SDK fetches forms and, through the FormData module, submits data. It can't create or edit forms. To build or change a form, open the Forms section of the OneEntry admin panel, add fields, configure validation rules and activate the form.
The SDK has no built-in support for conditional fields (showing or hiding fields based on other fields). Implement that logic in your own UI, based on the values the user enters.
File uploads
Add a file, image or groupOfImages field to your form. Submissions with files are handled by FormData.postFormsData(), which uploads the files through the FileUploading module automatically. See the FormData module.
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 is required. With the default errors.isShell: true, they resolve to an IError instead of throwing, so check the result (for example, 'statusCode' in result). With errors.isShell: false they throw. See Errors.
Related
- FormData: submit and manage form submissions
- Events: automated notifications on form submit
- FileUploading: file uploads in forms
- Users: users who submit forms