Template Tags, Categories and Tag Clouds

Template tags are functions defined in the core WordPress files and are globally available for use in your templates. There are a lot of tags available for different aspects of your template files. To get a complete list of what’s available see the Template Tags on the WordPress Codex.

Some accept many parameters (information passed to the function enclosed in the brackets/parentheses), others do not accept any parameters. To use a template tag you need to ensure it’s within opening and closing PHP tags e.g.

<?php template_tag_name('parameter_name=value&parameter2=value'); ?>

If the tag is going into an already defined set of PHP code then the opening and closing PHP tags are not needed. For those that do not require or accept parameters then you can omit the content within the brackets/parentheses i.e.

<?php template_tag_name(); ?>

Understanding the tags and parameters, and how they can work for you means you can gain control of your own theme, without having to resort to hardcoding your pages, categories or anything else. Often what you want to do can usually be accomplished with a combination of template tags along with conditional tags.

I plan to cover the more popular / important tags used among bloggers, which should give you more of an understanding of what’s going on in your existing theme and how you can change a few parameters to get your desired output.

Categories

The tag for the category listing is wp_list_categories(). Without any parameters, this will create the following:

<li class="categories">Categories
 <ul>
  <li class="cat-item cat-item-1">
   <a href="http://www.yourdomain.com/category/category-name/" title="Category Description here if set">Category Name</a>
  </li>
 </ul>
</li>

While the default listing is fine, you may want to gain a little control over what is output. The more popular parameters are:

show_count

This allows you to display the number of posts within each category in brackets after the category name. By default this is not shown, but add the parameter as show_count=1 to turn the option on.

hide_empty

Controls whether empty categories are displayed in your list. hide_empty=1 will display the empty categories, remove this parameter if you do not want empty categories displayed.

exclude

This allows you to exclude certain categories from the list. Handy if you want to have a hidden category for other reasons (I’ll give an example another time). Usage is exclude=1,2,3, listing the category IDs as a comma separated list.

title_li

This allows you to change the heading of the list, the default being ‘Categories’. Usage is either title_li=My Categories to change the title or title_li= where the value is simply nothing, to remove both the title and the surrounding list tags, producing just the unordered list of categories.

So, if you wanted to display the post count after each category, exclude a particular category (ID of 4) and remove the title and list tags, as you going to style the list in a definition list, you’d use:

<dl>
 <dt>Categories</dt>
  <dd><?php wp_list_catgories('show_count=1&exclude=4&title_li='); ?></dd>
</dl>

Which would result in output as

<dl>
 <dt>Categories</dt>
  <dd><ul>
   <li class="cat-item cat-item-1">
    <a href="http://www.yourdomain.com/category/category-name/" title="Category Description here if set">Category Name</a>
   </li>
  </ul></dd>
</dl>

Tag Clouds

You may wish to show a tag cloud instead of your category list (or as well as). A lot of the older themes out there will not contain this function as it’s only been available since WordPress 2.3, however it’s relatively simple to add into your sidebar.

The template tag to get a tag cloud is wp_tag_cloud().

The default of this will print out a string of your tags alphabetically, in varying sizes (controlled by the pt unit), separated by a space (so no markup involved). There are a number of parameters you can set to control how your tags are displayed.

smallest

This takes an integer as a value and defines the size of the smallest tag in your cloud, ie. the least popular one. The default is 8, to change this use smallest=1 where 1 is the value you want to specify.

largest

Similar to the smallest parameter, except it defines the size of the largest tag, ie. the most popular.

unit

The sets the unit of measure for your size of text. It accepts px, em, % and pt (which is the default).

number

This controls the number of tags displayed. The default is 45. If you want to display all of your tags specify the value as 0 (zero). Usage is number=1 where 1 is the number of tags to display.

format

This controls the format in which your tag cloud is output in the markup. The default is a string of tags separated by a space, however you can specify it as a list which will have a class of wp-tag-cloud on the ul. There is also a format value of array, this is for use with PHP. Usage for this is format=list.

orderby

Controls the order in which the tags are output. The default is by name, or you can choose by count - orderby=count.

order

Controls the direction of your output order. Default is ascending, you can also use DESC for descending or (since WordPress 2.5) RAND for a random order. Note the value for this parameter must be in uppercase. order=RAND.

exclude/include

As with the categories template tag, you can use include or exclude to control which tags to display or not display. Use the tag ID to control this.

So, if you wanted to insert your tag cloud in your sidebar, display up to 30 tags, change the text size to use px, adjust the font size and display the tags randomly, then you would use:

<p><?php wp_tag_cloud('smallest=7&largest=14&unit=px&number=30&order=RAND'); ?></p>