# Dynamic data

Dynamic data is what makes one design produce a different image for every
post. An element reads it in one of two ways:

- **From the dynamic data list** in the element's inspector, which binds the
  whole text, or an image's source, to one value.
- **As a placeholder** in a text or in an image's source URL: a key in braces,
  such as `{post.title}`, replaced by its value when the image renders. A text
  can mix several placeholders with ordinary words.

The values come from the post the image is rendered for, and from the page it
is rendered on. In the editor they come from the post chosen as preview data.

## The groups

| Group   | Keys                                                                                                                                                                                                                     |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Post    | `post.id`, `post.title`, `post.content`, `post.postType`, `post.type`, `post.link`, `post.date`, `post.modifiedDate`, `post.time`, `post.commentsCount`, `post.excerpt`, `post.featuredImage`, `post.terms`, `post.meta` |
| Author  | `author.name`, `author.bio`, `author.email`, `author.website`, `author.archiveUrl`, `author.avatar`                                                                                                                      |
| Site    | `site.title`, `site.tagline`, `site.url`, `site.icon`                                                                                                                                                                    |
| Archive | `archive.title`, `archive.description`                                                                                                                                                                                   |
| Query   | `query.resultsCount`, `query.searchTerm`                                                                                                                                                                                 |
| Object  | `object.title`, `object.id`                                                                                                                                                                                              |
| Custom  | the entries a site adds; see [Custom data](/docs/pixel/custom-data.md)                                                                                                                                                      |

- Dates and times use the site's date and time formats.
- `post.content` is the post's content with its blocks rendered and its HTML
  removed.
- `post.type` is the same value as `post.postType`, the post type's name such
  as `post`; the **Post type** entry of the dynamic data list binds
  `post.type`.
- `post.meta` holds every custom field of the post, those WordPress keeps with
  a leading underscore such as `_thumbnail_id` included. Each field is the
  list of its stored values, so a placeholder names a value by its position:
  `{post.meta.<key>.0}` gives the first value and `{post.meta.<key>.1}` the
  second, while `{post.meta.<key>}` names the whole list and renders as empty
  text. A value is used as WordPress stores it, so an array saved in a single
  field appears as its serialized text.
- `post.featuredImage` and `site.icon` are images, each with an `id` and its
  URL in `data`. Bound to an image element they supply the file itself; as a
  placeholder, `{post.featuredImage.data}` gives the URL.
- The Archive, Query and Object groups describe the page being viewed. Only
  the values a design uses give it a file per page: a design that shows
  `{archive.title}` keeps one per archive, while the search term changes
  nothing for a design that does not show it. A background render uses the
  values of the page that queued it.
- `query.searchTerm` keeps its first 100 characters with runs of whitespace
  made one space. A design that shows it renders a file per search term, one
  new term at a time, and keeps the 50 newest; a page whose term has no file
  yet keeps its own tags until the term's file is rendered.

## Fields from ACF and Meta Box

When Advanced Custom Fields is active, a post's ACF fields are available as
`{post.acf.<field>}`; with Meta Box, its fields are `{post.mb.<field>}`. A
placeholder that names something that is not a plain value, or that does not
exist, renders as empty text.

## Changing the data in PHP

The `sleekPixel/data` filter changes any value before an image uses it, and
the `sleekPixel/data/custom` filter adds entries to the Custom group. Both are
described in [PHP hooks](/docs/pixel/hooks/php.md).