What is a Token?

A Token is a specially formatted chunk of text that serves as a placeholder for a dynamically generated value.
Here is a really simple example: You want to display a welcome message to the users of your website, and you want it to be customized. You could add their name and instead of just saying "Welcome", you can say "Welcome, Joe".

In order to avoid having to hard-code a welcome string for every single user of the website, it would be nice to dynamically generate the string. You could use one similar to the following, "Welcome, [user:display_name?Anonymous]". A string of static text that can be located and replaced with a dynamic value.

The mandatory square bracket means that it is a token and is composed of different parts.

  1. The first part user: in this case, will be the token type. Token types are used to group things together into a namespace. For example, users can have a name, email, and last-login properties. Posts can have a title, ID, and author properties. This Token also plays an important role in determining what tokens are available and in what context.

  2. The second part, after the : is the token itself. This means what value will be substituted into the string containing the token. :display_name in this case, it indicates that we want the current username.

Generic Placeholder Substitution

In many cases, patterns or large chunks of text that contain derived values can be defined by users.
For example, from email messages addressed to a given user, or URL path aliases containing the title of a given post.

Both examples require bits of data that vary each time the text is generated -- post titles, user ids, and so on. Rather than forcing users to embed ugly snippets of PHP, shortcodes, or creating elaborate and bizarre UIs for configuring the patterns via the browser, it's most useful to give users a set of 'placeholder' tokens to place in their text.

Accessing Data Through Tokens

DCE provides access to all basilar object of WP like:

  • Post;

  • User;

  • Term;

  • Option;

  • WP_Query;

  • Query;

  • System;

  • Date;

  • ACF;

  • Specific variable.

Token Shortcode Composition

  • [ (required, open tag);

  • post (required, or user or option or term or wp_query or special variable);

  • : field name (required, native fields, and meta are supported);

  • : subfield key (optional and multiple, if the field is Array or Object);

  • | ID (optional, INT, if omitted will use the current by page);

  • | filter (optional and multiple, you can manipulate text result with PHP and WordPress functions);

  • ? fallback text (optional, shown if field value is empty or null);

  • ] (required, close tag);

Examples

Post

  • [post:title] - print current Post Title, the native field of this object (you can also write it without the repetitive post_)

  • [post:_yoast_wpseo_metadesc] - print current Post Meta Description, a post meta field created by 3rd party plugin

  • [post:_thumbnail_id|wp_get_attachment_url] - print the Feature Image URL

  • [post:_thumbnail_id|wp_get_attachment_image_src(thumbnail)|reset] - print the Featured Image thumbnail URL of the current Post

  • [post:ID|get_the_post_thumbnail(full)?] - print current Post Featured Image through a core WP function with parameters or a placeholder image if the post hasn't got the Featured Image

  • [post:date|strtotime|date_i18n("j F Y")] - print the current Post Date in a custom format

  • [post:date|strtotime|sum(86400)|date_i18n("Y-m-d H:i:s")] - print the Post Date plus one day in default time format

  • [post:ID|get_the_terms("category")|wp_list_pluck("name")] - print the name of the category (or categories) of Current Post

  • [post:type:labels:singular_name] - print the Type Singular Label of current Post

  • [post:permalink] - print the unique URL of Current Post, use [post:guid] may be an alternative

WooCommerce Product

All WooCommerce tokens are available only if the Wocommerce plugin is enabled. All the previous Post Tokens are also compatible with Products.

  • [product:_price] - print current Product base Price;

  • [product:_sku] - print current Product SKU;

  • [product:_price|Woo-tshirt-logo] - print Product base Price of Product with a specific SKU.

ACF

  • [acf:my_acf_field] - print the value of ACF Field, where "my_acf_field" is the name of the field in ACF settings, it works also for subfield in rows of ACF Repeater;

  • [acf:my_acf_field|123] - print the value of ACF Field of the Post with ID 123;

  • [acf:my_file:filesize|size_format(2)] - print the Human readable size (with 2 optional decimal) of an ACF File Field;

  • [acf:my_acf_field:title] - print the label of ACF Fieldset in his configuration;

  • [acf:my_select_field:settings:choices:red] - print the label of an ACF Field Option set in his configuration;

  • [acf:my_acf_field:settings:choices|options] - use the choices of ACF Field Select set in his configuration as options in a Select Field of Elementor PRO Form.

User

  • [user:first_name] - print logged User first name, or nothing if the page is viewed from a non authenticated visitor;

  • [user:last_name|concat('Mr ',true)] - print logged User last name with a prefix;

  • [user:email|explode(@)|reset] - print only username of current User Email (for example support@dynamic.ooo);

  • [user:nicename|23|trim?Anonimous] - print trimmed User Nicename from a user with ID 23, otherwise, if the user has no nicename or user does not exist will print "Anonymous";

  • [user:roles] - print logged in User Role, separated by a comma if multiple Roles.

Author (alias for User)

  • [author:display_name] - print the name of the author of the Current Post.

  • [author:ID:count_user_posts] - print the number of Posts written by the current Author, it accepts as a parameter the CPT name

Term

  • [term:name] - print Term name of Current Term or First Term of Current Post;

  • [term:description|wpautop] - print Term description with automatic paragraph;

  • [term:description|123] - print Term description of the Term with ID 123;

  • [term:count|123] - print Post count related to Term with ID 123;

  • [term:link|last] - print the URL to Term Archive of the last term of the current post;

  • [term:txtarea|artist] - print the value of an ACF field (like a Textarea) stored in Term of custom "artist" Taxonomy related to current Post;

  • [term:term_id|category|posts|reset|get_the_title] - print the Title of the last published Post in the same Taxonomy (Category);

  • [term:thumbnail_id|wp_get_attachment_url(full)] - return the URL of the Media in the Term Meta field which contains his ID.

Option

  • [option:elementor_version] - print current version of the installed Elementor's plugin from WP system options;

  • [option:www_user_roles:editor:name|strtoupper] - print the uppercased name of Editor Role;

  • [option:home|wp_logout_url] - return to the direct Logout URL and return to the Homepage.

WP Query

  • [wp_query:posts] - print the id (or ids) of posts in the displayed page (like in archive);

  • [wp_query:query_vars:paged] - print the current pagination page number (return 0 on the first page).

Query

  • [query:user] - print the list of all Users (Display Names);

  • [query:user:email] - print the list of all Users emails;

  • [query:user:editor] - print the list of Editor Users (or any other Role);

  • [query:user:customer|options("Guest")] - create a Customer list in the Options setting of a Select Form Field with also an empty value "Guest";

  • [query:term] - print the list of Terms (by default the Categories);

  • [query:term:post_tag] - print the list of Tags Terms (or any other Taxonomy);

  • [query:post] - print the list of the Posts (Titles);

  • [query:post|count] - print the number of published Posts;

  • [query:post:uncategorized] - print the list of the Posts without Category (or related to any other Term);

  • [query:page] - print the list of the Page (or any other Custom Post Type);

  • [query:product|options] - create the options list of all Products of your shop in a Select Form Field;

  • [query:post:_thumbnail_id] - print the list of the Featured Image Media ID of the Posts (or any other Meta Field);

  • [query:attachment:guid|rand] - print a random Media URL.

System

  • [system:get:my_query_var] - print the variable stored inside $_GET, also compatible with POST, SESSION, COOKIE, and SERVER systems vars;

  • [system:cookie:my_favorite] - print the value stored inside a Cookie, also used for Add to Favorite Widget;

  • [system:server:REMOTE_ADDR] - print the IP of the current visitor;

  • [system:MY_CONSTANT] - print the value of a constant previously declared in code.

Date

  • [date:+1 month] - print the date of a month from today in WordPress default format;

  • [date|Y m d] - print the date of today in custom format;

  • [date:user:registered] - print the current User registration date in default WordPress format;

  • [date:post:date:+2 days|Y-m-d H:i:s] - print the current Post publish date + 2 days (optional) in standard DateTime format.

Custom var in a Loop

  • [ROW:var1|trim] - print the variable ROW inside widgets with your own HTML structure.

Expression

It supports nested Tokens

  • [expr:5+(8*2)/3] - execute a mathematic expression;

  • [expr:[post:my_num_val]*2] - execute a mathematic expression with Dynamic values (nested Tokens);

  • [expr:[post:my_num_val]+[post:my_num_val]*[acf:coeff|123]] - execute a mathematic expression with multiple Dynamic values.

Form

  • [form:my_field_id] - print the field value with ID "my_field_id" after form submission;

  • [form:all-fields] - print a list of all submitted fields;

  • [form:all-fields|!empty] - print a list of all submitted valued fields;

  • [form:pdf] - attach to Dynamic Email the PDF generated by PDF Generator for Elementor PRO;

  • [form:pdf:url] - print the URL of PDF generated by PDF Generator for Elementor PRO;

  • [form:pdf:title] - print the Title of PDF generated by PDF Generator for Elementor PRO;

  • [query:user|options] - return a formatted list compatible with Elementor PRO field options;

  • [query:term|options("Select a category")] - return a formatted list compatible with Elementor PRO field "Options" with an initial empty value;

  • [post:category|value] - prepare multiple fields (like the Post Categories) separating their values (term_id) by a comma, compatible with Elementor PRO field "Default Value".


Filters

As a filter, you can use all WP, PHP, and custom functions.

Some examples:

  • if the Token returns the string "Hello", with the filter strtoupper the final result will be "HELLO";

  • if the Token returns the Post ID, with the filter get_the_post_thumbnail will be printed his Feature Image.

How to add your own Custom filter

Add your function in your file functions.php, where the function name will be the filter name.
It has a unique parameter that contains the Token result, it may be a string, an array, an object, or null.

function my_custom_token_filter($data) {  
// do whatever you want
return $data;
}

Parameters

The Filters may accept also parameters, the Token's value is automatically passed to the function as the first parameter (or last for some function, like explode).

For example,

  • substr(0,3) gets the first 3 characters of the returned string;

  • get_the_post_thumbnail('full') gets the full image, not the thumb.

Multiple Filters

You can add multiple filters, which will be executed in concatenation based on their order. Type them separated by the "|" pipe:
[post:title|sanitize_title|strtoupper|trim]

Did this answer your question?