FormData

Handle form submissions and retrieve form data.

More information about forms in the OneEntry admin panel: https://doc.oneentry.cloud/docs/category/forms (opens in a new tab)

---

The FormData module submits user-filled forms (contact forms, surveys, registrations) to OneEntry. It also retrieves, updates and deletes submitted data, so you can view responses, build reports and analyze the data.

Quickstart

Initialize the module from defineOneEntry:

const {  } = defineOneEntry(
  , {
    
  }
);

Build the body from the form's config and submit it:

// 1. Fetch the form to read its module config.
const form = await Forms.getFormByMarker("contact_form");
if ('statusCode' in form) throw new Error(form.message);

const config = form.moduleFormConfigs?.[0];
if (!config) throw new Error('The form is not attached to a module');
const formModuleConfigId = config.id;
const moduleEntityIdentifier = config.entityIdentifiers[0].id;

// 2. Submit the user's input.
const response = await FormData.postFormsData({
  formIdentifier: "contact_form",
  formModuleConfigId,
  moduleEntityIdentifier,
  replayTo: null,
  status: "sent",
  formData: [
    { marker: "name", type: "string", value: "John" },
  ],
});

if ('statusCode' in response) {
  console.error(response.message); // IError: the submission was rejected
} else {
  console.log(response.formData.id); // ID of the new form data record
}

To read submissions later, call getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

Submitting a form

Form data is the information users submit through a form. Each submission consists of a formData array of field objects (marker, type, value) plus the form's configuration identifiers.

postFormsData accepts an IBodyPostFormData:

const body = {
  formIdentifier: 'contact_form', // Form marker
  formModuleConfigId: 9,          // Module config ID (from the form)
  moduleEntityIdentifier: 'blog', // Module entity identifier (from the form)
  replayTo: null,                 // Parent record ID for threaded replies; null for a top-level record
  status: 'sent',                 // Submission status, usually 'sent'
  formData: [                     // Form fields
    { marker: 'name', type: 'string', value: 'John' },
  ],
};

Values from the form's config

Before submitting, you need three values, all read from the form itself:

1. the form marker (formIdentifier): the form's text identifier;
2. formModuleConfigId: from the form's moduleFormConfigs;
3. moduleEntityIdentifier: from the form's moduleFormConfigs.

const form = await Forms.getFormByMarker('contact_form');
if ('statusCode' in form) throw new Error(form.message);
const config = form.moduleFormConfigs?.[0];
if (!config) throw new Error('The form is not attached to a module');
const formModuleConfigId = config.id;
const moduleEntityIdentifier = config.entityIdentifiers[0].id;

So the full flow is: fetch the form with Forms.getFormByMarker(), read formModuleConfigId and moduleEntityIdentifier from its moduleFormConfigs, build the body, then call FormData.postFormsData(body). Cache these values so you don't refetch the form on every submission. Reference forms by marker, not by numeric ID.

formData fields

Each entry in the formData array describes one field:

• marker: must match a field marker from the form definition.
• type: the field type (used for validation and file handling).
• value: the user's input.

Validate required fields on the client before submitting; OneEntry also validates them on the server.

Files

For fields of type file / image / groupOfImages, pass a File, FileList or Blob as the value: postFormsData() uploads it automatically through the FileUploading module. Alternatively, upload the file first with FileUploading.upload() and pass the returned object, in an array, as the value; see postFormsData().

Submission status

status tracks a submission's state: sent (the usual value for a new submission), moderation, approved, banned or deleted. Change it later with updateFormsDataStatusByid().

Updating and deleting submissions

Authenticated users can edit, change the status of, or delete their own submissions. For anyone else's record, the API returns 403:

• updateFormsDataByid(id, body): edit a stored submission by id 🔐
• updateFormsDataStatusByid(id, body): change only a submission's status by id 🔐
• deleteFormsDataByid(id): delete a submission by id 🔐

Reading submissions

getFormsDataByMarker returns the submissions for a form. Page through the results with the offset / limit arguments instead of fetching everything at once. Narrow them down with the request body: status (an array), dateFrom / dateTo (YYYY-MM-DD), userIdentifier, entityIdentifier or parentId.

Searching submissions by meaning

getFormsDataByVectorSearch(body, langCode, offset, limit) runs a semantic (vector) search over submissions. You pass a natural-language queryText and get back the records that match it in meaning, not by literal keyword.

Its records are IFormDataSearchEntity objects. Like the records from getFormsDataByMarker, they carry id, formIdentifier, time and formData. They also always carry the moderation and sender fields, which getFormsDataByMarker returns only with isExtended = 1 (fields the record doesn't have are omitted):

Field	Type	Meaning
status	'sent' | 'banned' | 'deleted' | 'moderation' | 'approved'	Moderation status of the record
isUserAdmin	boolean	Whether an admin submitted the record
userIdentifier	string | null	Who submitted the form
entityIdentifier	string	The entity the record belongs to
parentId	number | null	Parent form data record
formModuleId	number	ID of the form module the record belongs to

---

Methods

Method	Description	Use Case
postFormsData()	Submit new form data	User submits contact form
getFormsDataByMarker()	Get submissions for specific form	Show submissions of a public form (for example, reviews)
updateFormsDataByid() 🔐	Update a form submission by id	Edit a stored submission
updateFormsDataStatusByid() 🔐	Update a submission's status by id	Change the status of your own submission
deleteFormsDataByid() 🔐	Delete a form submission by id	Remove a submission
getFormsDataByVectorSearch()	Semantic (vector) search for form data	Find submissions by meaning, not keywords

🔐 Requires user authorization; see AuthProvider. postFormsData(), getFormsDataByMarker() and getFormsDataByVectorSearch() don't need a user token, but getFormsDataByMarker() reads only forms an admin has marked as public. Forms are private by default; for a private form the API responds with 403 ("This form's submissions are not publicly readable"). An unknown marker returns an empty list.

With the default errors.isShell: true, the methods 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

• Forms: fetch form structures to submit against
• FileUploading: file uploads in forms
• Events: event-driven notifications
• Users: users who submit forms

---