> For the complete documentation index, see [llms.txt](https://docs.acpt.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acpt.io/integrations/etch.md).

# Etch

Learn how to use Etch with ACPT dynamic data

ACPT offers a native integration with [Etch](https://etchwp.com/). All your ACPT fields are automatically available as dynamic data inside any Etch template — no additional setup or file patching is required.

The integration hooks into Etch's `etch/dynamic_data/*` filters and injects all ACPT field values under the `acpt` key of the relevant data object.

***

## General usage

For the full Etch dynamic-data syntax, refer to the [Etch custom fields documentation](https://docs.etchwp.com/integrations/custom-fields).

ACPT fields follow the same convention, namespaced under `acpt`:

| Context     | Syntax                                                |
| ----------- | ----------------------------------------------------- |
| Post / Page | `{meta.acpt.boxName_fieldName}`                       |
| Taxonomy    | `{category.acpt.boxName_fieldName}`                   |
| User        | `{user.acpt.boxName_fieldName}`                       |
| Option page | `{options.acpt.{option_page_slug}_boxName_fieldName}` |

***

## Field value structure

Every ACPT field value is wrapped in a context object with three keys:

```
{
  before: string | null,
  value:  <the field value>,
  after:  string | null
}
```

To read just the value, chain `.value`:

```
{meta.acpt.info_email.value}
```

`before` and `after` contain any prefix/suffix configured in the field's advanced options.

***

## Text-based fields

The following field types return a plain string in `.value`:

* **Text** / **Textarea** / **Password**
* **Editor** (returns HTML with paragraph tags)
* **HTML**
* **Email**
* **Color** (returns a hex string, e.g. `#ff5733`)
* **Embed** (returns the raw embed URL or HTML)
* **Icon** (returns the icon identifier string)
* **Toggle** (returns `"1"` when on, `"0"` or empty when off)

```
{meta.acpt.box_text_field.value}
{meta.acpt.box_editor_field.value}
{meta.acpt.box_color_field.value}
```

***

## URL field

The URL field returns an object with both the raw URL and an optional label:

```
{
  url:   "https://example.com",
  label: "Visit website"
}
```

Usage:

```
<a href="{meta.acpt.box_link.value.url}">{meta.acpt.box_link.value.label}</a>
```

***

## Number, Rating, and Range fields

These fields return a numeric value in `.value`:

```
{meta.acpt.box_price.value}
{meta.acpt.box_rating.value}
{meta.acpt.box_range.value}
```

***

## Currency field

Returns an object with the amount and the currency unit:

```
{
  amount: "1600.00",
  unit:   "USD"
}
```

Usage:

```
{meta.acpt.box_price.value.amount} {meta.acpt.box_price.value.unit}
```

***

## Length field

Returns an object with the measurement value and its unit:

```
{
  length: "12.5",
  unit:   "cm"
}
```

Usage:

```
{meta.acpt.box_height.value.length} {meta.acpt.box_height.value.unit}
```

***

## Weight field

Returns an object with the weight value and its unit:

```
{
  weight: "70",
  unit:   "kg"
}
```

Usage:

```
{meta.acpt.box_weight.value.weight} {meta.acpt.box_weight.value.unit}
```

***

## Phone field

Returns an object with the dial prefix and the raw number:

```
{
  dial:  "+1",
  value: "5551234567"
}
```

Usage:

```
{meta.acpt.box_phone.value.dial}{meta.acpt.box_phone.value.value}
```

***

## Date field

Returns an object with the formatted date string and the format used:

```
{
  format: "d/m/Y",
  value:  "22/06/2026"
}
```

Usage:

```
{meta.acpt.box_date.value.value}
```

***

## Datetime field

Returns the same structure as the Date field, but the value includes both date and time:

```
{
  format: "d/m/Y H:i",
  value:  "22/06/2026 14:30"
}
```

***

## Time field

Returns the formatted time string:

```
{
  format: "H:i",
  value:  "14:30"
}
```

Usage:

```
{meta.acpt.box_time.value.value}
```

***

## Date Range field

Returns an object with the `from` and `to` dates as an array:

```
{
  format: "d/m/Y",
  value:  ["22/06/2026", "29/06/2026"]
}
```

Usage:

```
From {meta.acpt.box_range.value.value.0} to {meta.acpt.box_range.value.value.1}
```

***

## Address field

Stores the full address text along with four additional properties automatically extracted by ACPT:

```
{
  address: "1 Infinite Loop, Cupertino",
  city:    "Cupertino",
  country: "US",
  lat:     "37.3318",
  lng:     "-122.0312"
}
```

Usage:

```
{meta.acpt.box_location.value.address}
{meta.acpt.box_location.value.lat}
{meta.acpt.box_location.value.lng}
{meta.acpt.box_location.value.city}
{meta.acpt.box_location.value.country}
```

{% hint style="info" %}
An **Address Multiple** variant is also available. Its `.value` will be an array of the above objects — iterate it with a `{#loop}`.
{% endhint %}

***

## Country field

Returns an object with the raw ISO code and a human-readable label:

```
{
  value:   "IT",
  country: "Italian (Italy)"
}
```

Usage:

```
{meta.acpt.box_country.value.value}    <!-- "IT" -->
{meta.acpt.box_country.value.country}  <!-- "Italian (Italy)" -->
```

***

## Select and Radio fields

Single-choice fields return the selected option value as a plain string in `.value`:

```
{meta.acpt.box_status.value}
```

***

## Select Multi and Checkbox fields

Multi-choice fields return an **array** of selected option values. Iterate with a loop:

```
{#loop this.acpt.box_tags.value as tag}
  <span>{tag}</span>
{/loop}
```

***

## List field

Returns an **array** of string items. Iterate with a loop:

```
{#loop this.acpt.box_features.value as feature}
  <li>{feature}</li>
{/loop}
```

***

## Toggle field

Returns `"1"` when enabled, empty / `"0"` when disabled:

```
{#if meta.acpt.box_featured.value == "1"}
  <span>Featured</span>
{/if}
```

***

## Repeater field

Returns an **array of rows**. Each row is an object whose keys are the sub-field names.

```
{#loop this.acpt.box_repeater.value as item}
  {item.sub_field_name.value}
{/loop}
```

Nested sub-fields follow the same structure as top-level fields. For example, if a repeater row contains an image sub-field:

```
{#loop this.acpt.box_team.value as member}
  <img src="{member.photo.value.src}" alt="{member.photo.value.alt}">
  <p>{member.name.value}</p>
{/loop}
```

***

## Media fields

Media fields return a **plain object** with the following properties:

| Property      | Type             | Description                             |
| ------------- | ---------------- | --------------------------------------- |
| `id`          | `int`            | Attachment post ID                      |
| `src`         | `string`         | File URL                                |
| `title`       | `string`         | Attachment title                        |
| `alt`         | `string`         | Alternative text                        |
| `caption`     | `string`         | Caption                                 |
| `description` | `string`         | Description                             |
| `href`        | `string`         | Permalink                               |
| `type`        | `string`         | MIME type (e.g. `image/jpeg`)           |
| `thumbnailId` | `int \| null`    | ID of the thumbnail attachment          |
| `thumbnail`   | `object \| null` | Thumbnail as a nested attachment object |
| `metadata`    | `array`          | WordPress attachment metadata           |
| `sizes`       | `array`          | Available image sizes                   |
| `path`        | `string \| null` | Full server path to the file            |
| `pathinfo`    | `array`          | PHP `pathinfo()` result                 |

### Image, Audio, and Video fields

The attachment object sits directly in `.value`:

```
<img src="{meta.acpt.box_photo.value.src}" alt="{meta.acpt.box_photo.value.alt}">
```

```
<audio controls>
  <source src="{meta.acpt.box_audio.value.src}" type="{meta.acpt.box_audio.value.type}">
</audio>
```

### Gallery, Image Slider, Audio Multi, and Video Multi fields

`.value` is an **array** of attachment objects — iterate it with a loop:

```
{#loop this.acpt.box_gallery.value as image}
  <img src="{image.src}" alt="{image.alt}">
{/loop}
```

### File field

The File field has a different structure. The attachment is nested under a `file` key, alongside an optional `label`:

```
{
  file:  { ...attachment object... },
  label: "Download brochure"
}
```

Usage:

```
<a href="{meta.acpt.box_brochure.value.file.src}">
  {meta.acpt.box_brochure.value.label}
</a>
```

{% hint style="warning" %}
Always use `.value.file.src` for File fields — not `.value.src`.
{% endhint %}

***

## Barcode field

Returns an object with the source text and the generated barcode data:

```
{
  text:  "ABC-123",
  value: {
    svg:    "<svg>...</svg>",
    format: "CODE128"
  }
}
```

Usage:

```
{meta.acpt.box_barcode.value.text}
{meta.acpt.box_barcode.value.value.svg}
```

***

## QR Code field

Returns an object with the source URL and the generated QR code image:

```
{
  url:   "https://example.com",
  value: {
    img:        "data:image/png;base64,...",
    resolution: 300
  }
}
```

Usage:

```
<img src="{meta.acpt.box_qr.value.value.img}" alt="QR Code">
```

***

## Relational fields (Post, Term, User)

Relational fields return the corresponding WordPress object serialized as a plain object. All standard WordPress properties are available.

**Post field** (single):

```
{meta.acpt.box_related_post.value.post_title}
{meta.acpt.box_related_post.value.ID}
{meta.acpt.box_related_post.value.post_excerpt}
```

**Post field** (many — returns an array, use a loop):

```
{#loop this.acpt.box_related_posts.value as post}
  <a href="{post.guid}">{post.post_title}</a>
{/loop}
```

**Term field** (single):

```
{meta.acpt.box_category.value.name}
{meta.acpt.box_category.value.slug}
{meta.acpt.box_category.value.description}
```

**User field** (single):

```
{meta.acpt.box_author.value.display_name}
{meta.acpt.box_author.value.user_email}
```

{% hint style="info" %}
Multi variants (**Post Object Multi**, **Term Object Multi**, **User Multi**) return an array of the above objects. Use a `{#loop}` to iterate.
{% endhint %}

***

## Option pages

Fields registered on an option page are available under the `options` context. Replace `{option_page_slug}` with the menu slug of your option page:

```
{options.acpt.{option_page_slug}_boxName_fieldName.value}
```

All the same field-type rules apply — a text field returns a string, a gallery returns an array of attachment objects, and so on.

***

## Shortcodes and third-party plugin output

An **Editor** (or **Text**) field can store a raw WordPress shortcode — for example a TablePress `[table id="1"]` or a form-plugin shortcode such as `[fluentform id="3"]`. You do not need a separate Gutenberg Shortcode block to render it: Etch's own Text and Raw HTML elements process WordPress shortcodes automatically, after resolving the dynamic data.

### HTML-producing shortcodes (e.g. TablePress)

Pass the field's value straight into Etch's **Raw HTML** element:

```
<etch:html content={item.section_body.value} />
```

If `section_body` is an Editor field whose saved content is the `[table id="1"]` shortcode, Etch expands it and renders the resulting table markup in place.

### Text/form shortcodes (e.g. Fluent Forms, `[acpt_form]`)

Bind the field directly. Because ACPT wraps an Editor field's value in a paragraph tag, strip it with Etch's built-in `stripTags` modifier so the shortcode isn't split across a `<p>`:

```
{this.acpt.contact_single_meta_form_id.value.stripTags()}
```

{% hint style="info" %}
Shortcode processing here is a feature of Etch itself, not ACPT: both the Text and Raw HTML elements call WordPress's `do_shortcode()` on the resolved dynamic content before output. ACPT only needs to supply the raw, unprocessed field value.
{% endhint %}