Contents
Overview
Magic Tags are simple tags that let you display custom fields, taxonomies, relationships, and more in your Pods Templates. When your Pod Template is processed, the magic tags are replaced with the actual values in those fields each time the template runs through the loop. You can do more specific things with Special Magic Tags and Template Tags.
Simple example
When working with magic tags, you have the ability to specify the field name and a potential callback function to pass your value through if needed. Pods will automatically render the field value safely, based on the field type settings.
This is the value of my field: {@my_field}
Traversal notation
You can use our field notations for relationship / file field traversals.
This is the value of my relationship's field: {@my_relationship.my_field}
Safe output examples
If you are working with links or attributes, you should definitely be using the handy esc_url() and esc_attr() WordPress functions to avoid breaking HTML when it displays your field values onto the page. If you don’t trust the value at all, you can use the PHP function strip_tags() to prevent HTML tags from appearing even if you allow them to be input in your field type options.
<a href="{@permalink,esc_url}">We used esc_url()</a> to make sure the permalink in the "href" attribute will not break the "a" tag when displaying it. <a href="{@permalink,esc_url}" title="{@post_title,esc_attr}">We used esc_attr()</a> to make sure the magic tag in the "title" attribute will not break the "a" tag when displaying it. <p>Here is my content but I want to always remove all of the HTML tags: {@post_content,strip_tags}.</p> <p>Here is my content but I want to always encode the HTML so it won't display like HTML: {@post_content,esc_html}.</p>
Passing values through callbacks and filters
In Pods, we sometimes refer to callbacks as “helpers”, which was a leftover term from Pods 1.x.
If the callback exists and is allowed, it will pass the value directly into that callback function. If the function does not exist then it will treat the callback as a filter and run it through apply_filters( $params['helper'], $value );
Please note: Some filters in WordPress or other plugins may also be functions. For instance, if you hope to use the_content filter, that won’t work because the_content() function will be seen and used instead.
Here is an example of using custom a callback or a filter.
<p>Here is my value that will run through my own custom callback: {@my_field,my_custom_callback_function}</p> <p>Here is my value that will run through my own custom filter: {@my_field,my_custom_filter}</p>
Limitations
You will not be able to use every PHP function available, the following functions have been disallowed:
- system()
- exec()
- popen()
- eval()
- preg_replace()
- preg_replace_array()
- preg_replace_callback()
- preg_replace_callback_array()
- preg_match()
- create_function()
- include()
- include_once()
- require()
- require_once()
You can customize which functions are disallowed by filtering the array in the pods_helper_disallowed_callbacks
filter.
You can also specify which functions you only want to allow by filtering the array in the pods_helper_allowed_callbacks
filter. This filter will override any disallowed callbacks.
If you want to turn off callbacks entirely, just use the following code:
add_filter( 'pods_helper_allow_callbacks', '__return_false' );