# Help4 Dynamic Data and Fields

Help4 Builder Suite 1.3.272 introduces one structured data contract for WordPress content and the Help4 Commerce catalog. Builder widgets, shortcodes, REST editors, custom integrations, and calculated fields use the same resolver and validation rules.

## Data sources

`[h4_dynamic]` and `[h4_field]` support these sources:

| Source | Purpose |
| --- | --- |
| `field` | A Help4 field stored on a post or page |
| `post` | Title, content, excerpt, dates, author, permalink, and featured image |
| `post_meta` | Approved metadata keys; only Help4 field metadata is public by default |
| `product` | Public Help4 Commerce catalog properties and approved payload data |
| `product_field` | A Help4 field stored in a product's isolated `_h4_fields` payload namespace |
| `variant` | SKU, price, stock, image, and variation attributes |
| `term` | Taxonomy term identity, description, count, and permalink |
| `user` | Public author identity, biography, URL, archive, and avatar |
| `site` | Site name, description, URL, language, year, and timezone |
| `option` | A small public allowlist of non-secret WordPress options |
| `request` | A small allowlist of public query values; cookies are never exposed |

## Builder examples

```text
[h4_dynamic source="post" key="title"]
[h4_dynamic source="post" key="featured_image_url" format="image"]
[h4_dynamic source="field" key="hero_subtitle" fallback="A better website starts here."]
[h4_dynamic source="field" key="features" path="0.label"]
[h4_dynamic source="product" product_id="42" key="price" transform="currency:USD"]
[h4_dynamic source="product_field" product_id="42" key="badge"]
[h4_dynamic source="variant" product_id="42" variant_id="7" path="attributes.color"]
[h4_dynamic source="term" taxonomy="category" key="name"]
[h4_dynamic source="user" key="display_name"]
```

The Builder widget inspector exposes source, object IDs, key, nested path, output format, fallback, media size, and transform controls. Leaving an object ID at zero uses the current post, author, or queried term when the selected source supports context.

## Transform pipeline

Transform steps are separated by `|` and run from left to right. The resolver caps a request at eight transforms.

```text
trim|strip_tags|words:24
upper
date:F j, Y
number:2
currency:USD
join:%20/%20
first
count
json
```

Use URL encoding when a transform argument needs leading or trailing spaces. For example, `%20/%20` becomes ` / `.

## Field schema 2.0

Field groups support text, rich text, number, range, email, URL, link, select, multi-select, radio, button group, checkbox, toggle, image, file, gallery, date/time, color, repeater, group, relationship, post object, taxonomy, user, embed URL, map, icon, JSON, code, and computed fields.

Definitions can set:

- required, read-only, public, REST-editable, multiple, and unique behavior;
- default and return format;
- edit capability;
- taxonomy and allowed post types;
- number minimum, maximum, and step;
- text minimum/maximum length and a validation pattern;
- maximum structured rows;
- a safe calculated-field formula;
- nested sub-fields and namespaced extension data.

Calculated fields use bounded arithmetic formulas such as `{quantity} * {unit_price}`. They are evaluated on the server, cannot use `eval`, and cannot be overwritten by REST input.

## Product fields

Set a field group's location to `product` to use it with Help4 Commerce products. Product values are available at:

```text
GET  /wp-json/h4bs/v1/fields/product/42
POST /wp-json/h4bs/v1/fields/product/42
```

Product field writes require `manage_options`, validate against the field group, preserve the rest of the product payload, and use a revision hash to reject stale saves.

## Post field REST editing

```text
GET  /wp-json/h4bs/v1/fields/post/123
POST /wp-json/h4bs/v1/fields/post/123
POST /wp-json/h4bs/v1/fields/resolve
```

The GET response includes definitions, decoded values, schema version, and a revision hash. Send that hash with a POST. If another editor saved first, the API returns HTTP 409 with current values instead of silently overwriting them. Validation failures return HTTP 422 with errors keyed by field name.

## Extension contracts

The following filters and actions are intentionally public:

- `h4bs_dynamic_data_sources`
- `h4bs_dynamic_data_value`
- `h4bs_dynamic_data_transform`
- `h4bs_dynamic_data_post_meta_allowed`
- `h4bs_dynamic_data_allowed_options`
- `h4bs_dynamic_data_allowed_request_keys`
- `h4bs_dynamic_data_product_payload_keys`
- `h4bs_dynamic_data_product_payload`
- `h4bs_dynamic_data_product_permalink`
- `h4bs_dynamic_data_user`
- `h4bs_field_definition_sanitized`
- `h4bs_field_value_validated`
- `h4bs_field_value_saved`
- `h4bs_field_values_saved`
- `h4bs_product_field_values_saved`

## Security defaults

Dynamic output is deliberately not an arbitrary database reader. Private user email and roles are not public data sources. Arbitrary options, request parameters, cookies, and private post metadata are denied. Product payloads use a public allowlist and recursively remove secret, token, password, authentication, credential, private-key, and webhook keys. HTML output passes through WordPress KSES, and private fields return the configured fallback.
