Skip to main content

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 a type (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)DescriptionExample Use
stringShort single-line textName, Title, City
text / textWithHeaderMulti-line textMessage, Comments, Bio
integer / real / floatNumeric inputAge, Quantity, Price
date / dateTime / timeDate & time pickersBirth date, Event date
listDropdown / multi-select from optionsCountry, Category
radioButtonSingle choice from optionsSize, Plan
file / imageFile / image uploadResume, Photo, Document
groupOfImagesMultiple imagesGallery
entityReference to another entityLinked 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: true or 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​

MethodWhat It DoesWhen to Use
getAllForms()Get all forms (paginated)List all available forms
getFormByMarker()Get form by markerFetch 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.


  • FormData: submit and manage form submissions
  • Events: automated notifications on form submit
  • FileUploading: file uploads in forms
  • Users: users who submit forms