When you are creating a form or working with the information submitted to a form, for example when setting up an auto-responder message from a form, you often need to use dynamic information from that form. For example, if you wanted your auto-responder message to start with “Hi Roy” when the value of the form field with the slug “first_name” was Roy and start with “Hi Rachel” when the value of the form field with the slug “first_name” was Rachel, you would write “Hi %first_name%” in the beginning of your auto-responder message.
In Caldera Forms, we use the term “Magic Tag” to refer to the placeholders that you use while setting up your forms, which are then dynamically replaced by Caldera Forms. While we use the term “Magic Tag”, this feature is very similar to what MailChimp calls a “Merge Tag”. They are also much like WordPress shortcodes.
Caldera Forms magic tags come in two forms:
- Field Slug Magic Tags Example
%primary_email%.- These magic tags substitute for the value of a field. They identify fields by their slugs.
- “Bracket” Magic Tags – Example
{current_url}.- These magic tags are used for all other cases besides field values.
Caldera Forms has a large set of magic tags that can be used as placeholders for field defaults, creating emails, or setting the values of variables. Magic tags are replaced on form submission using form entry data, or data from other sources. These other sources include the current page URL, the current user and the current post.
There are a wide variety of magic tags that are available by default, and many add-ons add magic tags. This document covers the default magic tags.
Where Magic Tags Can Be Used
Magic tags can be used as the default value of a form field or the value of a hidden field. They can also be used as the values of variables, or to create emails, or to populate processor settings.
Important Types of Magic Tags
There are many types of magic tags you can use. Here is a short summary of the most important types of magic tags you may need. More detailed information is provided as this document goes on.
- Field Values Values of a field from the current entry.
- Summary Magic Tag a magic tag useful for emails that makes a list of all field entries.
- User Information about the current logged in user.
- GET and POST Variables Values of the PHP super globals, GET – aka the query parameters.
- Embedded Post The current post object for the post or page that the form is embedded in.
- Date The current date.
Field Values
Every field in the current form has a magic tag formed with the field’s slug with a percentage sign before and after. For example, if you have a field in your form with the slug “hats” and wanted to show its value in the email, you would use the magic tag “%hats%”.
For select fields, the magic tag will show the value, not the label. You can use a magic tag in the form of “%slug:label% to show a dropdown, radio, checkbox or other types of select field’s label in the email. For example, if you have a select field with the slug “plan” and wanted to show the label in the email, you would use “%plan:label%.
Field value magic tags can be used in HTML fields to show the value of an input field, which will live update. When using a calculation field in manual mode, field value magic tags are used along with JavaScript arithmetic operators to form the calculation.
The Summary Magic Tag
In the form mailer settings, the default value for an email’s body its the {summary} magic tag. This makes a list of all form field’s in order. This is a simple default which is a useful timesaver, but it doesn’t work in all situations.
The summary magic tag is designed to be all you need for your email message, most of the time. If it’s not what you need, there are two major options available to you: customize how the summary magic tag works or use other magic tags instead.
User Magic Tags
User magic tags are in the form of {user:*} where the * is a standard user field. For example
- {user:first_name} Current user’s first name.
- {user:last_name} Current user’s last name.
- {user:user_email} Current user’s email.
- {user:user_login} Current user’s login/ username.
- {user:ID} Current user’s ID.
GET Variable
GET Variables are also referred to as “query string parameters” as they are passed in the URL. Any GET variable can be used with a magic tag in the form of a {get*}. For example, if you had wanted to record UTM tracking tags from an advertising campaign, you can create a hidden field with the value “{get:utm_campaign}” to track the UTM tag for the campaign.
These tags are also useful when connecting two forms using a redirect processor. Any passback variable will be added as a query parameter to the URL that is used for the redirection. If you had one form that had a field with the slug “first_name” and wanted to set that in the second form, you could create a pass back variable in the first form with the slug first_name and the value %first_name%. In the second form you would set a field’s default value as “{get:first_name}”
The Embedded Post
Data about the post or page that the form is embedded in are available using the {embed_post:*} magic tags. These magic tags are available:
- {embed_post:ID} The current post’s ID.
- {embed_post:post_title} The current post’s title.
- {embed_post:permalink} Link to the current post
- {embed_post:post_date} Date current post was published
WordPress Query Var
In Caldera Forms 1.5.3 a new magic tag is {query_var:*} was added. This tag is a wrapper for get_query_var(). WordPress query vars must be registered and are not the same as GET variables, which sometimes are referred to as query vars.
Other Magic Tags
- {ip} — The IP of the user requesting the page.
The IP magic tag is a very useful tag if you are tracking the IP address of user that submits the form. It can be used for user tracking, and geolocation purposes.
- {entry_id} — ID of current form entry
This tag can be used to show the entry ID in the email. For example, if you wanted to send an edit link for a form, you could create a link with “{embed_post:permalink}?cf_ee={entry_id}”.
- {current_url} — The URL of the current page.
- This magic tag should only be used for field values, not processor values. It is best to add a hidden field, whose value is this magic tag and then use that hidden field’s magic tag in processors.
- See this page for more information on various ways to use magic tags with the redirect processor to refresh the same page after submission.
- This magic tag was added in Caldera Forms 1.5.2
- {referer_url} — The referer URL returned by wp_get_referer()
- This magic tag was added in Caldera Forms 1.8.9
Many Caldera Forms processors provide magic tags. These magic tags are prefixed with the processor’s slug. They can be used to add data retrieved by the processor from a remote API, or similar to the emails sent by Caldera Forms.
Please note that these magic tags can not be used in form settings or the settings of other processors because their values are determined too late in the submission process.