03 – Substitution in Kazoo

Now that we have learned how to Get Started with Kazoo and to Use Kazoo Template tags let’s examine how to get data from WordPress into our templates.

There are two template tags that substitute data into the template:

<!--{replace|value_name/}-->
<!--{subst}--> ... {{value_name1}} .. {{value_name2}} ... <!--{/subst}-->

The first way is to use the “replace” tag. This tag is used to replace the entire tag with a single value from the template engine. The tag accepts only one parameter – the name of the value that will replace the tag and any inner content it contains. You can see there is little value to including any inner content with the replace tag.

The second way is to use the “subst” tag. Unlike “replace” this tag is designed to perform a search and replace operation on ALL the value tags within it’s content AFTER all the inner content has been evaluated to allow processing of any tags within its inner content. A value tag is the name of a value surrounded by double curly braces. Let’s look at an example:

[kazoo]
<!--{subst}-->
<!--{IfTrue|user_id}-->
<!--{GetUserData/}-->
User ID: {{user_id}}
User Name: {{user_display_name}}
User Role: {{user_role}}
User IP: <!--{replace|user_ip}-->172.0.0.1<!--{/replace}-->
<!--{subst}-->
<!--{/IfTrue}-->
<!--{IfFalse|user_id}-->You are viewing this site as a guest.
Your IP address is: <!--{replace|user_ip/}-->
<!--{/IfFalse}-->
[/kazoo]

And here is the live output of the example from above:

You are viewing this site as a guest. Your IP address is: 184.73.74.47

There are a couple of interesting things going on with this template as I’ve managed to slip in some extra topics. You can see the “subst” tag surrounding a large portion of the content and the value tags that it operates on are fairly obvious with their “{{value_name}}” format. Then I also threw in a couple of conditional tags and an invocation of the “GetUserData” tag as well. What’s that all about?

Well, I didn’t want to post an example that people would see as broken simply because they were not logged in – hence the conditionals. If you are logged in you get some of your user information printed out for you. If not then you get a brief message telling you as much and informing you of your current IP address. But the main topic here is still substitution.

Notice that the “subst” command did in fact evaluate ALL its inner content prior to performaing substitution. That means that other tags like conditionals, interation and even substitution can take place prior to that tags intended substitution operation. You can pretty much run any other tag in there including other plugin short codes if you use the “shortcodes” tag.

The “replace” tag on the other hand simply replace itself with the value we specified. I included some inner content on the replace tag to show that even if you include place holder content in the replace tag that you’ll only see the requested value.

There’s one other important thing we should discuss and that is the “GetUserData” tag that I used. Kazoo includes a number of tags that call into the WordPress API but it respects that somethines you just want to make a decision and that you may not want ALL of the data ALL of the time. Some values such as “user_id” and “is_user” are generally necessary and hence always available to you but others are not. The GetUserData tag exists to let you move user data to the template engine if and when you need it. If you’re wondering about the conditionals don’t worry – we’ll get to those in the next tutorial.