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 it is composed of different parts.
- 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 name, email, and last-login properties. Posts can have title, ID and author properties. This Token also plays an important role in determining what tokens are available and in what context.
- The second part, after the
:is the token itself. This means what value will be substituted into the string containing the token.
:display_namein 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:
- 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);
:sub field key (optional and multiple, if 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 e wp functions);
?fallback text (optional, shown if field value is empty or null);
](required, close tag);
Some Complete Example:
[post:title]- print current Post Title, 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 part 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 current Post
[post:ID|get_the_post_thumbnail(full)?<img src="/img/placeholder.png" />]- print current Post Featured Image trough a core WP function with parameters or a placeholder image if post hasn't got the Featured Image
[post:date|strtotime|date_i18n("j F Y")]- print the current Post Date in 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
[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: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 a ACF File Field;
[acf:my_acf_field:title]- print the label of ACF Field set in his configuration;
[acf:my_select_field:settings:choices:red]- print the label of a 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: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 firstname.lastname@example.org);
[user:nicename|23|trim?Anonimous]- print trimmed User Nicename from user with ID 23, otherwise if user has no nicename or user not exist will print "Anonymous";
[user:roles]- print logged in User Role, separated by a comma if multiple Roles.
[author:display_name]- print the name of Author of Current Post.
[author:ID:count_user_posts]- print the number of Posts written by current Author, it accept as parameter the CPT name
[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 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 last published Post in same Taxonomy (Category);
[term:term_id|123|posts|options]- return all Posts related to Term 123 as Options for Elementor PRO Form;
[term:thumbnail_id|wp_get_attachment_url(full)]- return the url of the Media in Term Meta field which contain his ID.
[option:elementor_version]- print current version of the installed Elementor's plugin from WP system options;
[option:www_user_roles:editor:name|strtoupper]- print uppercased name of Editor Role;
[option:home|wp_logout_url]- return to the direct Logout url and return to the Homepage.
[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 first page).
[query:user]- print the list of all Users (Display Names);
[query:user:email]- print the list of all Users email;
[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:user:administrator:email]- generate the list of all administrator emails, could be useful to fill the To recipient of a Dynamic Email;
[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 option 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: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:+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 Loop
[ROW:var1|trim]- print the variable ROW inside widgets with your own html structure.
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: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 Action for Elementor PRO;
[form:pdf:url]- print the url of PDF generated by PDF Action for Elementor PRO;
[form:pdf:title]- print the Title of PDF generated by PDF Action 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 a initial empty value;
[post:category|value]- prepare a multiple field (like the Post Categories) separating their values (term_id) by a comma, compatible with Elementor PRO field "Default Value".
- 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.
It has a unique parameter which contain the Token result, it may be a string, an array, an Object or null.
// do whatever you want
- substr(0,3) - gets the first 3 character ot the returned string;
- get_the_post_thumbnail('full') - gets the full image, not the thumb.
You can add multiple filters, which will be execute in concatenation based on their order.
Write them separated by the "|" pipe: