createFormField
Add a new field to any form by specifying its name, label, type, display order, and parent form. Supports validation rules, default values, and visibility flags for admin or public views.
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`. |