02 – Using Kazoo Template Tags

Ok, we started out of the gate a little slowly with the “Getting Started” tutorial but we’ll be making up ground very quickly so if you haven’t read that one go back and do so now. All right then – load up your Kazoo tutorial page in the WordPress editor. I hope you’re not in the visual editor! Add a new line beneath the line that reads “Hello World” and add the following text.

It is a beautiful day!

Your content should now look like this:

This is my Kazoo Tutorial:
[kazoo]
Hello World!
<!--{ignore}-->It is a beautiful day!<!--{/ignore}-->
[/kazoo]

Go ahead and view the page. Do you see that the text you entered is not showing up? Given the name of the tag we used “ignore” that’s kinda what we expected. The ignore tag does exactly that – it ignores everything that falls between the begin tag and the end tag. This brings up the topic of this tutorial – tag structure.

There are only two basic tag structures:

<!--{TagName}--> ... inner content ... <!--{/TagName}-->
<!--{TagName/}-->

The first structure has a beginning tag and and end tag and the tag operates on EVERYTHING within – known as the inner content. Notice how the end tag has the same name but also has the terminator “/” before the name of the tag? That tells the template engine that this tag is a terminal tag to a tag that began earlier on in the content.

The second structure is called a self-terminal. It is a begin tag that also has a terminal marker but this time the terminal marker follows the tag name. This type of tag has no content whatsoever and is usually used for special directives. So in the example above we can very effectively instruct the template engine to ignore nothing at all by using a self terminal version of ignore like this: <!–{ignore/}–>

In general tag names are case insensitive. The template engine will successfully match a begin tag with the appropriate end tag even if the case of the tags doesn’t match. So this works: <!–{Tag}–> … <!–{/tag}–> Another place where case is not important is on values stored within the template engine that are used for substitution.

Passing Parameters to Tags:

Some tags require that parameters are passed to them. This is done by adding the parameters after the tag name and in the case of self terminals before the terminal marker. Terminal tags do not accept parameters. While parameters may be added to tags that do not expect them doing so will only make your template less readable. Lets looks at some examples of parameterized tags:

<!--{TagName|Param1|Param2}--> ... <!--{/TagName}-->
<!--{TagName|Param1/}-->
<!--{TagName|Param1||Param3/}-->
<!--{TagName|Param1||Param3|Param4/}-->

As you can see the parameters are passed positionally and each parameter added is preceeded by the vertical bar character “|”. An empty parameter can be passed by leaving it’s position empty but there are few if any cases where this actually applies. You can see from the example that begin tags and self terminal tags can have parameters but that terminals should not. Note that ALMOST ALL self terminals take one or more parameters.

Embedding Tags:

The template engine understands that the template may contain a hierarchy of tags. That is to say that like HTML it expects that template tags may be embedded within the content of other template tags. Almost all tags handlers respect the hierarchy and will correctly evaluate any tags it contains. Not all tags evaluate their content the same way – for example the “ignore” tag. In fact many specialized tags ignore the normal tag structure and enforce their own. This is true of structured tags such as the “If”, “Case”, and the “GetPosts” tags. – these enforce a child structure of their own.

Let’s examine a typical tag structure:

<!--{Subst}-->
  <!--{If|ValName}-->
    <!--{Then}-->
      ... then content ...
    <!--{/Then}-->
    <!--{Else}-->
      ... else content ...
    <!--{/Else}-->
  <!--{/If}-->
<!--{/Subst}-->

In the case above we have included indentation for clarity (and for a first version). We could just as easily have written the template without it and in most cases we would want our final template to be more compact as in the following example.

<!--{Subst}--><!--{If|ValName}--><!--{Then}-->
... then content ...
<!--{/Then}--><!--{Else}-->
... else content ...<!--{/Else}-->
<!--{/If}--><!--{/Subst}-->

IMPORTANT:

Never forget terminals – you will not get any output if you do.
Never add terminals without the appropriate start tag.
Never terminate a start tag with a self terminal – this will not work
Tag content may contain other tags.
Not every tag respects content or tags found within its content.
Some tags (especially custom tags) enforce a hierarchy of thier own.