updateFormField
Update an existing form field by ID. Fields omitted remain unchanged; writes live data. Requires field_id.
Instructions
Update a form field - Update an existing formfield record by ID. Fields omitted are untouched. Writes live data.
Required: field_id.
When renaming field_name on a form_table=website_contacts form, use canonical names (yourname / inquiry_email / phone / comments) — see createFormField and Rule: Forms § Form classes.
See Rule: Forms § Field anatomy for field shape, view-flag defaults, validators, and the canonical json_meta skeleton.
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: createFormField, deleteFormField, listFormFields.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| field_id | Yes | ||
| field_text | No | ||
| field_type | No | 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_order | No | 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. | |
| 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_placeholder | No | ||
| field_ldesc | No | Helper text rendered under the input field. Use for instructions / format hints (e.g. "Use international format"). | |
| 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_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_display_view | No | Show submitted value on front-end record-detail pages. Binary `0`/`1`. | |
| field_email_view | No | Include value in notification emails. Binary `0`/`1`. | |
| field_search_view | No | Lead Previews flag — value visible in lead-preview cards before purchase. Applies to forms with `form_table=leads`. | |
| field_grid_view | No | Table View flag — value renders in admin-dashboard / front-end data tables. | |
| 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`. | |
| json_meta | No | JSON-stringified per-field metadata blob (UI rendering + validator config). See **Rule: Forms** § Field anatomy → `json_meta` for the canonical skeleton. | |
| input_class | No | HTML `class=` attribute. On `field_type=Button`, must be `btn btn-lg btn-block <variant>` - e.g. `btn btn-lg btn-block btn-secondary`. Variant is one of `btn-primary`/`btn-secondary`/`btn-danger`/`btn-success`/`btn-warning`/`btn-info`/`btn-dark`, OR a custom class targeted by site CSS. See `createFormField`. | |
| _clear_fields | No | Column names to clear to empty string. Available on every `update*` operation. Works on base columns AND EAV/`users_meta` rows (rows preserved with `value=""`). To actually clear a field you MUST use this parameter — sending the field with `""` alone is a no-op (BD drops empty values). To remove a `users_meta` row entirely, use `deleteUserMeta`. See **Rule: Clearing fields**. Example: `_clear_fields: ["h2", "hero_link_url"]`. |