Form Submission

Complete guide to form submission flow: pre-submission, action configuration, and post-submission handling.

Pre Submission

Once a form is created, the system automatically looks for any nested component with type button and btnType: "submit".

Submit Button Configuration

{
  "type": "button",
  "class": [
    "btn",
    "btn-sm", 
    "btn-secondary"
  ],
  "btnType": "submit",
  "text": "Submit"
}

Automatic Binding

This submit button is automatically bound with form submission and triggers the form's onSubmit action when clicked.

Action

Form Submission Properties

Property Type Required Description
"method" string Required POST sends values in request body; GET sends values as query parameters. Supports: GET, POST, PUT, PATCH, DELETE
"action" string Required API endpoint URL for form submission
"target" string Optional Where to handle the response. Always use "_self" (default). Supports: "_self", "_parent", "_blank"
"container" number Optional Global containerId for loading responses. Defaults to 0. Supports: 0, 1, 2, 3 (no multi-region yet)

Target Behaviors

_self (Default - Recommended)

{
  "onSubmit": {
    "method": "POST",
    "action": "https://api.example.com/contact",
    "target": "_self"
  }
}

_parent

{
  "onSubmit": {
    "method": "POST",
    "action": "https://api.example.com/login",
    "target": "_parent"
  }
}

_blank

{
  "onSubmit": {
    "method": "POST",
    "action": "https://api.example.com/generate-report",
    "target": "_blank"
  }
}

HTTP Methods & Serialization

POST/DELETE/PUT

Automatically serialize form controls in payload:

{
  "name": "Dev",
  "phone": "+11111111"
}

GET

Serialize form and convert to query string:

?name=Dev&phone=+11111111

Sample JSON Configuration

"onSubmit": {
  "method": "POST",
  "action": "https://api.example.com/contact",
  "target": "_self"
}

Note: Always use _self as target (it's the default).

Post Submission

Form submission responses are handled in two main scenarios: successful submissions and failed submissions.

✅ Success Response Handling

Success Response Structure

When a form submission is successful, the API returns a response with code: "000" and component data to render.

Key Success Points

  • Response Code: Always returns "000" for successful submissions
  • Component Rendering: Response data contains components to render in specified container
  • Container Targeting: Uses container property to determine render location
  • Default Behavior: Falls back to container 0 when no container specified
  • Data Structure: Response includes type and components array
  • Modal Auto-Close: Form modals automatically close when successfully submitted
  • Immediate Rendering: JSON response data renders immediately in the specified container

Success Response Example

{
  "code": "000",
  "message": "Success",
  "data": {
    "type": "group",
    "components": [
      {
        "type": "text",
        "text": "Form submitted successfully!"
      }
    ]
  }
}

Container Rendering

The system checks for a container property in the onSubmit configuration:

With Container Specified
"onSubmit": {
  "method": "POST",
  "action": "https://api.example.com/contact",
  "target": "_self",
  "container": 1
}

Response renders in container 1

Without Container (Default)
"onSubmit": {
  "method": "POST",
  "action": "https://api.example.com/contact",
  "target": "_self"
}

Response renders in container 0 (default)

Response Component Rendering

The system renders the response data components in the specified container:

{
  "type": "group",
  "components": [
    {
      "type": "text",
      "text": "Thank you! Your form has been submitted successfully."
    }
  ]
}

❌ Error Response Handling

Error Response Structure

When a form submission fails, the API returns an error response with a non-zero code and descriptive codeDescription.

Key Error Points

  • Error Codes: Non-zero codes indicate different types of failures
  • Toast Notifications: Errors automatically display as toast messages
  • Message Display: codeDescription shows user-friendly error text
  • Container Targeting: Error toasts render in container 3 by default
  • Validation Errors: Field-level errors show inline with form controls
  • Server Errors: API failures are gracefully handled and displayed

Error Response Example

{
  "code": "001",
  "codeDescription": "Email address is already registered"
}

Automatic Error Display

Error responses automatically render as toast notifications. The codeDescription message ("Email address is already registered") is displayed to the user in a toast notification.