createFormField
Add a new field to any existing form, specifying its type, label, internal name, display order, and validation settings. Live data is written immediately.
Instructions
Create a form field - Create a new formfield record. Writes live data.
Required: form_name, field_name, field_text, field_type, field_order.
Canonical field_name for form_table=website_contacts: yourname / inquiry_email / phone / comments (NOT name / email / message — those persist but don't surface in the admin inbox columns). Anything else = custom field_name. Full table at Rule: Forms § Form classes.
See Rule: Forms § Field anatomy for field shape, view-flag defaults, validators, and the canonical json_meta skeleton. § Form-level recipe covers the tail pattern. § Lead-match / § Member-dashboard cover special-case forms.
Wrapper-enforced refusals: (1) field_required=1 with field_type ∈ {HoneyPot, HTML, Tip, Button} — Hidden is allowed. (2) field_type not in the canonical enum (strict case match; textarea is the lone lowercase value). (3) field_type=Hidden with empty field_name or empty field_text. (4) Non-binary value on any of field_required / field_input_view / field_display_view / field_email_view / field_search_view / field_grid_view / field_input_view_admin_only (empty / omitted accepted — BD applies per-field defaults).
Agent pre-checks (NOT wrapper-enforced): field_name uniqueness within form, single submit element per form. See Rule: Forms § Wrapper-enforced invariants → Agent-side responsibilities.
See also: updateFormField, listFormFields.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| form_name | Yes | Parent form slug | |
| json_meta | No | JSON-stringified per-field metadata blob (UI rendering + validator config). See **Rule: Forms** § Field anatomy → `json_meta` for the canonical skeleton. Pass the full skeleton even when unused; BD's admin form-builder writes all keys. Validators in `field_validate.validators` only fire when `field_validator_enabled` is `"1"`. | |
| field_name | Yes | Internal system key for this field. **Underscores only, no spaces** - e.g. `first_name`, `company_email`. Used as the HTML `name` attribute. | |
| field_text | Yes | Public-facing display label shown to the user. Free-form text - e.g. "First Name", "Your Email Address". | |
| field_type | Yes | Form field type. Copy spelling exactly — most are TitleCase but `textarea` is lowercase. Grouping + use cases at **Rule: Forms** § Field anatomy → Valid field_type values. | |
| field_ldesc | No | Helper text rendered under the input field. Use for instructions / format hints (e.g. "Use international format"). | |
| field_order | Yes | Display position (lower = earlier). New forms: multiples of 10 (10, 20, 30…), security tail included. Adding to an existing form: continue its pattern — don't renumber unrelated fields. | |
| input_class | No | HTML `class=` attribute on the rendered input. **Required for `field_type=Button`** - without it, submit button renders unstyled. Canonical Button pattern: `btn btn-lg btn-block <variant>` where `<variant>` is a Bootstrap button class (`btn-primary`/`btn-secondary`/`btn-danger`/`btn-success`/`btn-warning`/`btn-info`/`btn-dark`) or a custom site class. Example: `btn btn-lg btn-block btn-secondary`. Optional on non-Button fields. | |
| default_value | No | Prefilled value the field loads with on render. Accepts a static value OR PHP (e.g. `<?php echo date('Y-m-d'); ?>`) — BD evaluates at render time on any field_type. | |
| field_options | No | For `field_type` ∈ {`Radio`, `Checkbox`, `Select`}: `system_name=>label,system_name=>label,...`. LHS submitted value, RHS displayed text. Comma and `=>` are reserved separators. `%%%token%%%` translations supported. Silently ignored on other field types. | |
| field_required | No | `0` or `1`. Forbidden when `field_type` ∈ {`HoneyPot`, `HTML`, `Tip`, `Button`} — wrapper refuses these combinations because the requirement can't be satisfied at submit. `Hidden` is allowed (its value comes from `field_text`). | |
| field_grid_view | No | Table View flag — value renders in admin-dashboard / front-end data tables. Schema default `1`; send `0` to hide. | |
| field_email_view | No | Include value in notification emails. Binary `0`/`1`. | |
| field_input_view | No | Binary `0`/`1`. For readonly behavior, add the `readonly` CSS class to `input_class` (e.g. `form-control readonly`); do NOT use `field_input_view=2`. | |
| field_placeholder | No | ||
| field_search_view | No | Lead Previews flag — value visible in lead-preview cards before purchase. Applies to forms with `form_table=leads`. Schema default empty (treat as `0`); send explicitly when overriding. | |
| field_display_view | No | Show submitted value on front-end record-detail pages. Binary `0`/`1`. | |
| field_input_view_admin_only | No | Admin-only render flag. When `1`, field renders only when an admin is logged-in on the front end with admin-view enabled; members never see it. Use on `form_action_type=default` member-account forms. Default `0`. |