Submission

In Formitiva, following operations are performed to make a sucess submission

• Field validation when fieldValidationMode is onSubmission
• Form validation
• Form submit handler process
• Errors reports

Handle Field Validation

When fieldValidationMode is onSubmission, all field validation will be performed

• Field type built-in validation
  Inlcude the registered correspodent type validation for custom component
• Filed Custom validation

Field Validation Reference

• Field Validation mode
• Field Level Validation

---

Handle Form Validation

Form validation performs cross-fields check and time consuming checks, include asynchronous checks.

• Form Level Validation

Handle submission

Formitiva supports two common approaches:

1. Pass an onSubmit function directly to Formitiva (simplest).
2. Use the submission registration system so each definition can reference a handler by name.

Handler signature

export type FormSubmissionHandler = (
  definition: FormitivaDefinition,
  instanceName: string | null,
  valuesMap: Record<string, FieldValueType | unknown>,
  t: TranslationFunction,
) => string[] | undefined | Promise<string[] | undefined>;

• Parameters
  • definition : definition data
  • instanceName : the name of instance which is in editing
  • valuesMap : the property name to value map
  • t : translation function for localized error messages

  const alertSubmission: FormSubmissionHandler = (
    definition, instanceName, valuesMap, t
  ): string[] | undefined => {
    const instance = {
      name: instanceName || "Unnamed Instance",
      version: (definition as any)?.version || "",
      definition: (definition as any)?.name || "",
      values: valuesMap as Record<string, FieldValueType | unknown>,
    };
    const instanceStr = JSON.stringify(instance, null, 2);
    alert(instanceStr);
    return undefined;
  };

Option A — submit via onSubmit

Registration

export function registerSubmissionHandler(
  submitterName: string,
  fn: FormSubmissionHandler) : void

• Parameters
  • submitterName : submission registered handler name
  • fn : submission handler

Example

import * as React from 'react';
import { Formitiva } from '@formitiva/react';

const definition = {
  name: 'contactForm',
  version: '1.0.0',
  displayName: 'Contact Form',
  properties: [
    { name: 'name', type: 'text', displayName: 'Name', required: true },
    { name: 'email', type: 'email', displayName: 'Email', required: true },
    { name: 'message', type: 'multiline', displayName: 'Message', minHeight: '80px' },
  ],
};

export function App() {
  return (
    <Formitiva
      definitionData={definition}
      onSubmit={alertSubmission}  // See alertSubmission defined above
    />
  );
}

Option B — register a submission handler

This option is very useful when you have multiple forms and each form has different submission process. The submission handlers can be registered and reference in form defintion without passing specific submission by onSubmit.

Reference a handler in your definition using submitHandlerName.

const definition = {
  name: 'contactForm',
  version: '1.0.0',
  displayName: 'Contact Form',
  submitHandlerName: 'exampleSubmitHandler',
  properties: [
    { name: 'name', type: 'text', displayName: 'Name', required: true },
    { name: 'email', type: 'email', displayName: 'Email', required: true },
    { name: 'message', type: 'multiline', displayName: 'Message', minHeight: '80px' },
  ],
};

Register a handler with the same name.

export function registerSubmissionHandler(
  submitterName: string,
  fn: FormSubmissionHandler) : void

• Parameters
  • submitterName : submission registered handler name
  • fn : submission handler

Examples

import * as React from 'react';
import { Formitiva, registerSubmissionHandler } from '@formitiva/react';

export function App() {
  React.useEffect(() => {
    registerSubmissionHandler('exampleSubmitHandler', alertSubmission); // see alertSubmission defined above
  }, []);

  // Formitiva will get submission handler by submitHandlerName and invoke it automatically
  return <Formitiva definitionData={definition} />;
}

Priority of Option A and Option B

onSubmit callback has higher priority than registration submission handler. When onSubmit is specified, registrated submission handler will be skipped.

Value Types (valuesMap)

The table below shows common definition field types and the runtime value type you'll receive in the valuesMap inside submission handlers.

name / definition type	definition type string(s)	submission type	example
Text / Multiline / Email / URL	text, multiline, email, url	string	name: "Alice"
Integer	int	number (integer)	count: 5
Float / Number	float, number	number (float)	price: 12.5
Checkbox / Switch	boolean	boolean	subscribe: true
Dropdown / Radio	dropdown, enum	string (selected value)	country: "US"
Multi-select	select-selection (multi)	string[]	tags: ["react","forms"]
Integer array	int-array	number[]	scores: [10,20]
Float array	float-array	number[]	ratios: [0.1,0.2]
Unit / Tuple	unit, (custom)	[number, string]	dimension: [100, "px"]
Date / Time	date, time	string (ISO date/time) or Date (component-dependent)	birthday: "2023-05-01"
File	file	File (browser File object)	avatar: File
Files (multiple)	file with multiple: true	File[]	attachments: File[]
Button / Description	Image	button, description, image	undefined