Building a Custom Form

Building a Custom Form involves three main steps: configuring the form's metadata (name, target, behaviour), composing the HTML layout, and testing the end-to-end submission flow.

1. Name and target

From the Architect Panel → Forms → Custom Forms, click New.

• Name — internal name. Pick something descriptive ("Public Contact Form", "Customer Profile Self-Edit", "New Product Wizard").
• Target Type — pick what the form does on submit:
  • Insert into datastore — creates a new row.
  • Update specific row — edits an existing row (the row ID is passed via URL or context).
  • Custom URL — POSTs the form data to a URL of your choice.
  • Custom PHP function — calls a named PHP function with the form data.
• Target Datastore / URL / Function — the specific destination.
• Visibility — which security groups can see and submit this form.

2. Compose the layout

The layout is HTML with placeholders for each field. Use ##FIELD_rowname## to insert the input for a specific datastore field. Wrap inputs in your own divs, columns, and headings for full control of the visual structure.

Example layout snippet for a contact form:

<div class="row">
  <div class="col-md-6">
    <label>Your Name</label>
    ##FIELD_name##
  </div>
  <div class="col-md-6">
    <label>Email</label>
    ##FIELD_email##
  </div>
</div>
<div class="row mt-3">
  <div class="col-12">
    <label>Your Message</label>
    ##FIELD_message##
  </div>
</div>
<button type="submit" class="btn btn-primary mt-3">Send Message</button>

The platform replaces each ##FIELD_*## placeholder with the appropriate input HTML for that field type — text input for Text Box fields, select for Dropdown fields, etc. Validation rules attached to the underlying datastore fields still apply.

3. Field list

List every datastore field your form uses. Fields not in this list aren't included in the submission, even if you reference them in the layout. This is the gatekeeper against accidentally exposing fields you didn't mean to.

4. Validation

Validation rules attached to the underlying datastore's fields still apply automatically — Custom Forms don't bypass them. If you need additional client-side rules specific to this form, add JavaScript in the layout that hooks into the form's submit event.

5. Embedding

Custom Forms can be embedded in:

• Page Builder pages via a form block — pick the Custom Form from a dropdown.
• Friendly URLs — configure a Friendly URL that targets the Custom Form directly.
• Any HTML — Custom Forms can also be included via their URL inside an iframe, or rendered by code that calls the platform's form-rendering helper.

6. Test before going live

End-to-end test:

1. Open the Custom Form via its embedded location.
2. Fill in valid values; verify it submits successfully.
3. Try invalid values; verify validation messages appear correctly.
4. Check the resulting row appears in the target datastore with the right values.
5. Verify any post-submit behaviour (redirect, thank-you message, notification email).

Tip: Keep your Custom Form's field list in sync with the underlying datastore. If you add a field to the datastore and want it on the Custom Form, you need to add it to the field list and reference it in the layout — the auto-generation that happens for standard forms doesn't apply here.