createForm
Create a form record with required fields to collect submissions, send notifications, or redirect users on a Brilliant Directories site.
Instructions
Create a form - Create a new form record. Writes live data. Add fields afterward via createFormField.
Required: form_name, form_title, form_action, form_layout, form_table, form_url, form_class, table_index, form_action_div, form_email_on, form_success_message.
Class selection — see Rule: Forms § Form classes before picking form_table. Follow § Form-level recipe for the canonical creation recipe.
Mandatory form_name pre-check per Rule: Pre-check natural keys — BD does NOT enforce uniqueness; duplicate form_name produces ambiguous [form=…] shortcode resolution.
Wrapper-enforced refusal: form_action_type=redirect AND empty form_target → call refused (see Rule: Forms § Wrapper-enforced invariants).
See also: updateForm, createFormField, listFormFields.
Returns: { status: "success", message: {...createdRecord} }.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| form_name | Yes | System slug (lowercase alphanumerics + hyphens + underscores; NO spaces). Hyphens and underscores are NOT interchangeable — the stored value is the lookup key, byte-exact, in `[form=<form_name>]` shortcodes and on `createFormField` parent references. Immutable post-create. Must be unique per site. For the human-readable nickname use `form_title`. Example: `form_name=strength_blueprint_ebook`. | |
| form_title | Yes | Human-friendly nickname (free text — spaces and any characters allowed). Surfaced in admin UI and form-listing screens. Example: `form_title="Strength Blueprint Ebook"`. NOT the same as `form_name` (the system slug). | |
| form_action | Yes | **post** = form submits via POST body (default, most forms). **get** = form submits as URL query string (use for bookmarkable search/filter forms). | post |
| form_layout | Yes | **bootstrapvertical** = Labels Above Inputs (canonical default). **bootstrap** = Labels Left of Inputs (canonical default for Member-dashboard class — `form_action_type=default`). User override wins in either case. | bootstrapvertical |
| form_table | Yes | Database table the form submissions post into. `website_contacts` = Standard public class (default for ALL public capture; free-create with this tool). `leads` = Lead-saving class (BD's Get-Matched member-routing ONLY) — never free-create from scratch; clone `bootstrap_get_match` per **Rule: Forms** § Lead-match special case. `users_data` = Member-dashboard class — never free-create from scratch; clone-and-assign one of the 3 canonical dashboard forms per § Member-dashboard special case. See § Form classes for the picking rule. Once set on create, treat as immutable. | website_contacts |
| form_class | Yes | CSS class applied to every field — UI consistency insurance. Canonical: `form-control`. Per-field `input_class` layers extra CSS on top. | form-control |
| form_email_on | Yes | Send admin notification email on each submission. `0` = OFF (default when an agent creates a form - safer: spammy forms won't flood the admin inbox). `1` = ON. Admin UI defaults this to ON; agents default it to OFF unless user explicitly requests notifications. | |
| form_email_recipient | No | Comma-separated email list to receive submission notifications. Used only when `form_email_on=1`. Empty = site default admin recipient. | |
| form_action_type | No | Post-submit behavior: - `widget` = Success Pop-Up (agent default). - `notification` = Inline Success Alert Banner. - `redirect` = Redirect to URL (wrapper-enforced: `form_target` required, see `form_target` field). - `default` = Member-dashboard class (admin-clone-only; do not create from scratch). - `""` (empty) = no post-submit behavior (valid only for internal/programmatic forms, NOT public-facing). For public-facing values (`widget` / `notification` / `redirect`), Button-last is the agent-side tail-pattern responsibility (NOT wrapper-enforced). See **Rule: Forms** § Form-level recipe. | widget |
| form_target | No | Destination URL. **Required when `form_action_type=redirect`** — wrapper refuses the call without it. Full URL with `https://`, e.g. `https://mysite.com/thanks`. | |
| form_url | Yes | Save Action URL - overrides default `action=` on the rendered form. **Required exact value for every form an agent creates:** `/api/widget/json/post/Bootstrap%20Theme%20-%20Function%20-%20Save%20Form`. This is the BD Save Form widget endpoint; without it, submit wiring breaks. Do NOT decode the `%20` - BD needs the URL-encoded form verbatim. | /api/widget/json/post/Bootstrap%20Theme%20-%20Function%20-%20Save%20Form |
| table_index | Yes | Primary key column matching `form_table`: `website_contacts` → `ID`, `leads` → `lead_id`, `users_data` → `user_id`. Required exact match — BD uses this to look up individual submissions. | ID |
| form_action_div | Yes | Target element ID (CSS selector including `#`) swapped in the DOM on form submit by the `widget` (Success Pop-Up) action type; harmlessly ignored on `notification` / `redirect`. **Always send `#main-content`** unless the user explicitly names a different target — it's the canonical default for every `form_action_type`. Must include leading `#`. | #main-content |
| form_success_message | Yes | Post-submit success copy. Canonical default for Standard public AND Lead-saving classes: `Your Message has been Received`. Override only on explicit user request. Applies to `form_action_type` ∈ {`widget`, `notification`, `redirect`}; not used by `default` (member-dashboard) class. | Your Message has been Received |
| label_to_placeholder | No | Form-level toggle. When `"1"`, BD collapses each field's `field_text` (label) into placeholder text inside the input — saves vertical space, removes the explicit `<label>` element above each field. Per-field `field_placeholder` is overridden when this is on. Default `"0"`. | 0 |