The values that you query by in a Caldera Easy Pod queries are built using either static values, or using magic tags, such as parts of the URL, or information about the current post. When the free Caldera Forms plugin is activated you can use a Caldera Form to generate a search form for your Easy Pod, which is explained elsewhere in our documentation.
In this document, I will explain how to use “magic tags” to populate the values for your query. These allow you to have one Easy Pod setup, and have it return different results based on context. A good example is the “Documentation” widget in use on this site. It creates links to docs based on the value of a directional relationship field that links product pages to documentation pages. Another example is our main documentation page. I will detail how this works later on in this document.
Types Of Magic Tags
There are many types of magic tags you can use. You can see a list of available magic tags when typing in the value field of the Easy Pods query editor, if you type “{“.
There are five types of magic tags you can use:
- User — Information about the current logged in user.
- Super Globals — Values of the PHP super globals, GET, POST and REQUEST.
- Post — The current post object.
- Date — The current date.
- IP — The IP of the user requesting the page.
Using PHP Super Globals
One very useful way to build queries is basing them off of URL strings. You will notice if you go to https://calderaforms.com/documentation that you will see all of our docs, but if you go to https://calderaforms.com/documentation/?product-slug=caldera-easy-pods, you will see only docs for Caldera Easy Pods.
This system is thanks to some conditional logic in our theme, and an Easy Pods query, called “auto_docs_list”, that uses the GET super global to read the “product-slug” section of the URL. You can see the conditional logic, that switches between that Easy Pod, and a fall back Easy Pod, which shows all docs, here.
The “auto_docs_list” Easy Pods query uses {_GET:product-slug} to dynamically populate the query from the URL string:
In the same way that {_GET:product-slug} is used in the above example, you can use the REQUEST and POST super variables as well. They are addressed as {_REQUEST:key} and {_POST:key} respectively.
Using Current User Data
The user magic tags allow you to use information about a specific user in the query. This is especially useful when your Pod has a relationship to the WordPress users object.
For example, if you had a Pod called “teams” that had a field related to users called “team_captain”, you could build a query, whose value was {user:ID}. This would allow you to generate a list of teams whose captain was the current logged in user.
Using The Post Object In A Query
The documentation widget makes use of the current WP_Post object to determine which documentation links to show. Doing so allowed me to avoid creating a separate Easy Pod for each product. Instead the correct product to look for documentation in is dynamically generated using the post magic tag.
Here is a screenshot of the query:
Please exercise care to ensure that you are using the WP_Post object, not the POST super global. While {post:ID} would return the ID of the current post, the similar {_POST:ID} would return the ID key of the current request’s post data.
Using The Date Magic Tag
The date magic tag will populate a query value with the current date. This is useful for comparing a Pods date field to the current date. For example, if you have an events Pod, with a field called “event_date” and wanted to show only future events. In this case, you could create a greater than comparison of the date field versus the current date.
Using The IP Magic Tag
The IP magic tag is a very useful tag if you are tracking the IP address of uses on your site, and storing it in Pods field. That is not something that we are currently doing on this site, so I do not have a practical example. It could be an interesting way to build a recommend products or posts box.