--- title: Dynamic Values audience: content source: us-core 8.46 generated: 2026-05-27 by scripts/llms/build.php (hybrid: prose from manual overlay, per-shortcode matrix auto-extracted) --- # Dynamic Values > Dynamic values are placeholders the renderer replaces with **per-page, per-post, per-user, or per-site data** at output time — so a shortcode written once in a Page Template (`us_content_template`) can produce a different result on every post the template is assigned to. > > Two unrelated subsystems share the name. Knowing which one a parameter belongs to is everything: > > | Subsystem | Used in | Replacement syntax | Resolved by | > |---|---|---|---| > | **Text tokens** | text / textarea / number / image-id / icon params marked `dynamic_values=TRUE` (or with a `for_text`/`for_image`/`for_textarea` family in `config/dynamic-values.php`) | `{{token}}` substrings inside the attribute value | `us_replace_dynamic_value()` in `plugins/us-core/functions/helpers.php` — runs on the rendered output, substring-replacing every `{{…}}` it recognises | > | **Link enums** | every parameter of `type=link` whose config sets `dynamic_values`. The value is a URL-encoded JSON document (`{"type":"post","url":"","target":"_self",…}`), and the agent picks `type` from a per-param enum | the JSON's `type` key — the link builder swaps it for the resolved URL at render time | `us_link_to_dynamic_value()` and the link picker UI | > > The two subsystems do **not** mix. You cannot put `{{the_title}}` inside a `link` JSON's `url` field expecting it to resolve to the current post — for that you use `"type":"post"` (the link-enum form). Conversely, the link-enum keys like `homepage`, `post`, `author_page` are **not** valid `{{token}}` substitutions in a text field — they only mean something inside a `link` JSON's `type`. ## Text tokens These work inside any param marked `dynamic_values=TRUE` or assigned to the `for_text` / `for_textarea` family. The renderer replaces each `{{…}}` substring with the resolved value; non-token text passes through unchanged, so they freely mix with literal copy (`Welcome to {{site_title}}!`). ### Global tokens | Token | Resolves to | |---|---| | `{{site_title}}` | The WordPress "Site Title" option (`get_bloginfo('name')`). | | `{{site_icon}}` | The Site Icon's media ID (suitable for image-ID params). | | `{{post_count}}` | Total number of published posts (`wp_count_posts()->publish`). | | `{{user_count}}` | Total registered users (`count_users()['total_users']`). | | `{{favs_count}}` | How many posts the current visitor has marked as favourites (works with the `us_add_to_favs` flow). | | `{{current_id}}` | The current object's ID (post, term, or user — whichever `us_get_current_id()` resolves to). | ### Current-post tokens Resolve against the post in the current loop iteration — usually meaningful only inside a Page Template / Reusable Block / Grid Layout card. | Token | Resolves to | |---|---| | `{{the_title}}` | The current post's title (same value `us_post_title` renders). | | `{{the_thumbnail}}` | The current post's featured-image media ID (suitable for image-ID params). | | `{{post_type_singular}}` | The post type's singular label (e.g. "Post", "Product"). | | `{{post_type_plural}}` | The post type's plural label (e.g. "Posts", "Products"). | | `{{comment_count}}` | Approved comment count for the current post. | | `{{us_tile_additional_image}}` | The post's "Additional Images" gallery (theme-provided meta — used as image source). | | `{{_product_image_gallery}}` | WooCommerce product-gallery image IDs (only when WooCommerce is active). | ### Current-term tokens | Token | Resolves to | |---|---| | `{{taxonomy_label_singular}}` | Singular label of the term's taxonomy ("Category", "Tag"). | | `{{taxonomy_label_plural}}` | Plural label of the term's taxonomy. | | `{{tax\|}}` | Comma-separated names of the terms the current post has in the given taxonomy. Separator is filterable via `us_replace_dynamic_value_term_separator`. Example: `{{tax|category}}`, `{{tax|product_cat}}`. | ### Date tokens | Token | Resolves to | |---|---| | `{{today}}` | Current date as `Ymd` (e.g. `20260526`) — for comparing with ACF date-pickers. | | `{{today_now}}` | Current date-time as `YmdHis`. | | `{{now}}` | Current time as `His`. | | `{{date\|}}` | Current date / time formatted with a PHP `date()` format string. Example: `{{date|F j, Y}}` → "May 26, 2026". The format string accepts letters, digits, `|`, `/`, `\`, `-`, `_`, `:`, `.`, `,` and spaces. | ### Current-user tokens `{{user|}}` reads a single value from the currently logged-in user's profile via `get_user_option()`. Returns an empty string for guests. The keys `user_pass` and `user_activation_key` are blocked. Common keys: `first_name`, `last_name`, `display_name`, `nickname`, `user_email`, `description`. Example: `Hello, {{user|first_name}}!`. ### Custom-field tokens `{{}}` falls through to `us_get_custom_field()`, which reads the current post's meta. Use this for raw `wp_postmeta` keys *and* for ACF field names (the resolver handles ACF formatting via the `$acf_format` flag). - **ACF group sub-fields**: address with `{{parent_group_field/sub_field}}` (slash-separated path). - **ACF gallery / multi-value fields**: the resolver flattens an array of scalars into a comma-separated string (so `{{gallery_field}}` yields `12,34,675` — usable directly as an image-IDs list). - **ACF image / file fields**: the resolver returns the attachment ID (suitable for image-ID params). - **Empty / non-scalar values**: resolved to an empty string — the token disappears from the output. ### Filter hooks Two filters let plugins extend the system without forking us-core: - `us_replace_dynamic_value` — `apply_filters('us_replace_dynamic_value', $match, $current_id)`. Return a non-default string to short-circuit the built-in handlers. Use this to register custom `{{my_thing}}` tokens. - `us_replace_dynamic_value_thumbnail` — filters the resolved `{{the_thumbnail}}` ID. - `us_replace_dynamic_value_term_separator` — filters the separator used by `{{tax|}}` (default `', '`). ## Link enums Inside any `type=link` parameter the agent stores a URL-encoded JSON object. The `type` key picks from a **per-param enum** declared in the shortcode's config under `dynamic_values`. The link builder resolves `type` to a real URL at render time. The base JSON shape is `{"type":"","url":"","target":"_self|_blank","rel":"…","title":"…"}` — when `type` is set the resolver ignores `url`; when `type` is unset (or `"url"`), the literal `url` field is used. ### Universal enum keys The four "always available" enum keys (no per-shortcode config needed): | Key | Resolves to | |---|---| | `url` (or unset `type`) | The literal `url` field of the JSON. The default for a hand-typed link. | | `popup_post` | Opens the current item's full page in a modal popup (used by list / carousel `overriding_link` to preview entries without a hard navigation). | | `popup_image` | Opens the current item's featured image in a lightbox. | | `custom_field|` | Uses the value of the named custom field as the URL. Common variants: `custom_field|us_tile_link` (theme's "Additional Settings → Custom Link"), `custom_field|us_testimonial_link`, any ACF URL / page-link / post-object field. | ### Predefined family keys (from `config/dynamic-values.php`) These are offered by params whose `dynamic_values` is one of the predefined family arrays (`global` / `post` / `user`): | Family | Keys | |---|---| | `global` | `homepage` — the site's front page (`home_url()`). | | `post` | `post` — the current post's permalink. `custom_field|us_tile_link`, `custom_field|us_testimonial_link` — convenience entries. | | `user` | `author_page` — the WP author-archive URL. `author_website` — the URL the author entered in their profile (empty when not set). | | `term` | `archive` — the term-archive page URL. | ### Per-param enums Most `link` params layer additional keys on top of the base set. Common per-element extensions: - `us_post_title.link` — adds `elm_value` (turn a title that *looks* like an email / phone / URL into a `mailto:` / `tel:` / external link). - `us_post_comments.link` — adds `post_comments` (jump-anchor to the post's comments section). - `us_post_taxonomy.link` — restricts to the term family (`archive`). - `us_image.link` / `us_post_image.link` — adds `popup_image`. - `us_post_list.overriding_link` / `us_post_carousel.overriding_link` / `us_product_*` — adds `popup_post` and (for posts) `popup_image`; **all inner card links become non-clickable**. The per-shortcode matrix below lists every `link` param with its full enum. ## Param-type → subsystem cheat sheet | Param type | Subsystem | Notes | |---|---|---| | `text` / `textarea` / `text_html` | Text tokens | `{{…}}` substitution; mix freely with literal copy. | | `link` | Link enums | URL-encoded JSON; pick `type` from the enum below. | | `upload` / `image` / `images` | Text tokens (image flavour) | Accepts a media ID, comma-separated IDs, or an image-yielding token like `{{the_thumbnail}}` / `{{site_icon}}` / `{{us_tile_additional_image}}` / `{{_product_image_gallery}}` / `{{}}`. | | `icon` | Text tokens (rare) | Most icon params take a static `