Theme Integration

Table of Contents

  • Adding UTW Tags to Themes
  • Custom Formatting

    • To add Ultimate Tag Warrior into your WordPress Theme, you will need to edit the appropriate template files. Use a text only editor for editing your WordPress Theme template files.

    Ultimate Tag Warrior template tags are divided into two basic kinds. One is used for displaying tags for the post below the post content in a single post view. The other is used to display all the tags for your site, which may be seen on every page on your site. Each have their own distinct formatting and customization options.

    The core layout for the UTW template tags is as follows:

    <?php UTW_FunctionTitle ("$formattype", "$format", "$limit")

    All UTW template tags require at least one parameter, $formattype. The $formattype values are shorthand ways of describing how to format items in a list of tags. Different formats can be used with different functions. For more information on the format types, see one of the core views below for the Ultimate Tag Warrior tag lists.

    If $formattype is either the empty string, or "custom", $format is not used at all. The default for $limit varies for each of the formatting functions.

    The tags are generated in various ways, but they are all displayed as links. Click on a tag link and the user will be taken to a multi-post view web page listing all the posts associated with that tag, or, if you using the Technorati parameters, to the search page results on the Technorati web site.

    There are five core views of Ultimate Tag Warrior tag list:

    Formatting single.php and index.php

    If you are going to manually include tags in your themes, go to Options > Tags and disable the automatically include tags options. This will prevent multiple sets of tags from displaying.

    The template tags in this section should go inside the wordpress loop.

    Tags for the current post

    For a post, you can include the current tags for the post. the related tags for the post and a list of related posts for the post. The post tag templates must be within the WordPress Loop. Clicking on a local tag link displays a list of the posts within that tag; displayed using the tag.php template file, if one is present (index.php will be used if tag.php is absent.).

    To customize the tags' look, you can manually add the tags to the index.php, single.php, or whichever template you use to generate the single post view in your Theme.

    To include a list of tags, use the UTW_ShowTagsForCurrentPost() function, with either one of the predefined format types, or a custom format if there's something different that you'd rather do.

    Example: Include a simple comma list of tags for the current post
    1. In the appropriate template file, add the following example:
      <div class="utwtags"><?php UTW_ShowTagsForCurrentPost("commalist") ?></div>
    2. Save the file to your site.
    3. Open the style.css style sheet file and add a class to utwtags to format the list, such as:
      .utwtags {border-top: 1px solid blue;
      padding: 10px 5px 0px;
      font-size: 80%; font-variant:small-caps;}
    4. Produces
      Apple, Banana, Orange
    Related tags for the current post

    Including related tags is pretty much the same as including tags. Related tags are found by getting the posts that match all of the tags assigned to the current post; and listing any tags assigned to those posts that aren't already assigned to the current post.

    Related links are displayed with the UTW_ShowRelatedTagsForCurrentPost function.

    Example: Include a simple list of related tags for the current post
    1. In the appropriate template file, add the following example:
      <div class="utwreltags"><?php UTW_ShowRelatedTagsForCurrentPost("simplelist") ?></div>
    2. Save the file to your site.
    3. Open the style.css style sheet file and add a class to utwreltags to format the list, such as:
      .utwreltags a {font-size: 70%; color:grey; text-decoration:none}
    4. Produces
      Apple Banana Orange
    Related posts for the current post

    The predefined formats for posts are different to the ones available for lists of tags. At the moment, there are just three predefined formats - postsimplelist, posthtmllist and postcommalist.

    Related posts are displayed with the UTW_ShowRelatedPostsForCurrentPost function.

    Example: Include an HTML list of related posts for the current post
    1. In the appropriate template file, add the following example:
      <ul class="utwrelposts"><?php UTW_ShowRelatedPostsForCurrentPost("posthtmllist") ?></ul>
    2. Save the file to your site.
    3. Open the style.css style sheet file and add a class to utwrelposts to format the list, such as:
      .utwrelposts a {text-decoration:none}
    4. Produces
    An inline tag-adder

    The inline tag-adder allows putting a magical box on entries that allows adding tags without going to the post editing page. It uses AJAX. That's how magic it is. At the moment, you need to have a user level of 3 or greater to add tags. Later, I'm going to add the option of any logged in user, or indeed anyone at all to add tags... but not yet - I have to figure out some tag-spammy countermeasures first.

    The function to use for this is UTW_AddTagToCurrentPost; which has a slightly different set of parameters to the other UTW_ functions.

    UTW_AddTagToCurrentPost($format="") is the extent of its parameters for now. If the name of a predefined format is passed in, and the moon is in the right position (There needs to be an HTML element with an ID of tags-50, where 50 is the ID of the current post. If the element doesn't exist, then you'll see a javascript error instead of the tags being updated.); the tag list will be updated dynamically. Until I think of a convenient way to serialize and deserialze custom formats, this is going to be restricted to using predefined formats for the tag updates. Of course, if you had a custom format; you probably know enough to add it to the set of predefined formats making this point moot (;

    Example: Include the magical inline tag-adder
    1. In the appropriate template file, add the following example:
      <?php UTW_AddTagToCurrentPost("simplelist") ?>
    2. Set up a place to put the tags:
      <span id="tags-<?php the_ID(); ?>"><?php UTW_ShowTagsForCurrentPost("simplelist") ?></span>
    3. Save the file to your site.
    4. Produces
      Apple Banana Orange
    5. Entering a new tag (like "Junk Food"), and clicking the + button will add the tag to the post, then update the display to this
      Apple Banana Junk Food Orange
    6. Magic, eh?
    The deprecated one

    There's a predefined format called superajax that is kicking around.. I'm not that happy with what it does, and how it works; so I'm pretending that it doesn't exist (:

    Formatting tag.php

    Usually, your tag.php file will include a wordpress loop. The wordpress loop can contain the same things as in the index.php and single.php section. There are a few additional functions that are useful for the tag.php template that will be outlined here.

    A Tag Set is the set of tags being displayed on the page. For /tag/sometag, the tag set is just "sometag". For /tag/sometag+anothertag or /tag/sometag|anothertag the tag set is "sometag" and "anothertag".

    The template function is_tag() (or is_utwtag()) returns true if the current page is a tag page. This is useful for conditionally including items in the sidebar.

    Display the current tag set

    The UTW_ShowCurrentTagSet function is useful for creating titles on a tag page. There are two predefined formats designed for this task: tagsetsimplelist and tagsetcommalist.

    Example: Include an HTML list of related posts for the current post
    1. In the appropriate template file, add the following example:
      <div class="tagheader"><?php UTW_ShowCurrentTagSet("tagsetcommalist") ?></div>
    2. Save the file to your site.
    3. Open the style.css style sheet file and add a class to utwrelposts to format the list, such as:
      .tagheader {font-size:120%; font-weight:bolder}
    4. On the page /tags/Apple+Banana+Orange Produces
      Apple, Banana and Orange
    5. On the page /tags/Apple|Banana|Orange Produces
      Apple, Banana or Orange
    6. On the page /tags/Apple Produces
      Apple
    Display the tags related to the current tag set

    Related tags are found by getting the posts that match all of the tags assigned to the current tag set; and listing any tags assigned to those posts that aren't already part of the current tag set.

    Related links are displayed with the UTW_ShowRelatedTagsForCurrentTagSet function.

    Example: Include a simple list of related tags for the current tag set
    1. In the appropriate template file, add the following example:
      <div class="utwreltags"><?php UTW_ShowRelatedTagsForCurrentTagSet("simplelist") ?></div>
    2. Save the file to your site.
    3. Open the style.css style sheet file and add a class to utwreltags to format the list, such as:
      .utwreltags a {font-size: 70%; color:grey; text-decoration:none}
    4. Produces
      Peach Pear Pumpkin

    Formatting tags.php

    The tags.php file is intended for providing an overview of all tags; as opposed to tag.php which shows the posts related to a tag. The tags.php file also differs from the tag.php file in that it's created as a page template; rather than being a magic file that UTW looks for.
    Create a tag archive page.

    This is surprisingly easy (:

    1. Create a file named tags.php in your theme folder.
    2. At the top of it, include this text: <?php /* Template Name: Tag Archive */ ?>
    3. Tag Archive will now display in the list of page templates on the 'edit page' page.
    4. Next, go to Write > Write Page, give the new page a title; then select 'Tag Archive' from the list of page templates, in the Page Options section. Click the 'Create New Page' button.
    5. Marvel at your greatness
    6. Add some stuff to the tags.php file, so that it does something useful
    Display a tag cloud

    There are predefined formats that allow changing the size, colour, or both; and there are functions for displaying tags in alphabetical order and popularity order. To display tags most popular first use the UTW_ShowWeightedTagSet function. To display tags in alphabetical order use UTW_ShowWeightedTagSetAlphabetical

    The font sizes and colours are set from the Options > Tags page; and are used for all tag clouds in your site.

    Example: Include a tag cloud, differentiated by size; most popular first
    1. In the appropriate template file, add the following example:
      <?php UTW_ShowWeightedTagSet("sizedtagcloud") ?>
    2. Save the file to your site.
    3. Produces
      Grapes Mango Blueberry Strawberry Apple Tamarillo Pear Papaya Banana Pineapple Lemon Cherries Plum Orange

    By default, tag clouds are limited to the top 150 tags. In order to display all of the tags in the tag cloud, the $limit parameter needs to be set to 0.

    Example: Include a tag cloud with colours and sizes, in alphabetical order with all of the tags
    1. In the appropriate template file, add the following example:
      <?php UTW_ShowWeightedTagSetAlphabetical("coloredsizedtagcloud","",0) ?>
    2. Save the file to your site.
    3. Produces
      Apple Banana Blueberry Cherries Grapes Lemon Mango Orange Papaya Pear Pineapple Plum Strawberry Tamarillo
    Display a long-tail graph

    Beware: the HTML used to generate the long-tail graph isn't XHTML compliant. (Although, if you know of a way of rendering it so that it is, let me know! (: )

    For now, the formatting of the long-tail graph isn't configurable - it's a finicky little beast at the best of times.

    In general, the UTW_ShowWeightedTagSet function is used for generating a long-tail. Of course, there's nothing stopping you from using the UTW_ShowWeightedTagSetAlphabetical function... it just wouldn't produce a long-tail curve.

    Each bar of the long-tail graph is 5px wide; so choose the maximum number of items carefully to avoid weird layout issues caused by a super-wide long-tail graph.

    Example: Display a long-tail graph
    1. In the appropriate template file, add the following example:
      <?php UTW_ShowWeightedTagSet("weightedlongtail","",10) ?>
    2. Save the file to your site.
    3. Produces
      1.  
      2.  
      3.  
      4.  
      5.  
      6.  
      7.  
      8.  
      9.  
      10.  
    Display a weighted bar.. thing

    This isn't XHTML compliant either. (And if you know a way I can do it, so that it is; you should tell me)

    The weighted bar thing is something I made up. Which is why it has a stupid non-name. It displays a bar with more popular tags in wider chunks, using the same colours as the tag cloud. This is another one where using the UTW_ShowWeightedTagSet function makes sense; and UTW_ShowWeightedTagSetAlphabetical looks a bit freakish.

    This suits displaying tag sets up to about 50 tags. Much more than that and it's too compressed to look like much of anything interesting.

    Example: Display a weighted bar thing
    1. In the appropriate template file, add the following example:
      <?php UTW_ShowWeightedTagSet("weightedlinearbar") ?>
    2. Save the file to your site.
    3. Produces
       
       
       
       
       
       
       
       
       
       
       
       
       
       

    Special Functionality for date.php/archive.php

    This functionality looks at the date range of the current query, and displays the tags for posts that were published during that daterange.

    For example, on the /archive/2005/ page, only the tags from posts in 2005 would display. Or from /archive/2004/07 tags from posts in July 2004 would display.

    Nifty, eh?

    There are two template functions available for this purpose: UTW_ShowTimeSensitiveWeightedTagSet and UTW_ShowTimeSensitiveWeightedTagSetAlphabetical. Both of these functions are used in the same manner as their non-date-sensitive counterparts (Except for limiting by date, of course (: ).

    Predefined Formats

    Format NameDescriptionExampleWordpress looptag.phptags.php
    simplelistList of tags separated with spaces ++ 
    iconlistList of tags separated with spaces, displayed with icons ++ 
    htmllistList of tags in <li> html tags. Wrap in <ul> or <ol> as your whims dictate.
    		• ++ 
    htmllistandorList of tags in <li> html tags, with + and/or | links as appropriate
  • +
  • +
  • +
    		• ++ 
    htmllisticonsAs for htmllist, displayed with icons.
    		• ++ 
    commalistList of tags separated with commas, , ++ 
    commalisticonsList of tags separated with commas, displayed with icons. , , ++ 
    commalistwithtaglabelComma list, but with a "Tags: " labelTags: , , ++ 
    technoraticommalistList of links to Technorati, separated with commas., , ++ 
    technoraticommalistwithlabelAs above, but includes a "Technorati Tags: " label at the start of the list.Technorati Tags: , , ++ 
    technoraticommalistwithiconlabelAs above, but includes the Technorati icon at the start of the list.Technorati , , ++ 
    gadabecommalistList of links to gada.be, separated with commas., , ++ 
    andcommalistComma separated list of tags, with union and intersection links when appropriate*. |, |, | + 
    invisiblecommalistComma separated list, in a hidden span, ,  ++ 
    tagsetsimplelistList of tags belonging to the current tag set, separated by the current operator (and or or, depending on if it's an "and tag set" or an "or tag set"). Just the tag displays for a single tag.Apple and Banana and Orange + 
    tagsetcommalistLike tagsetsimplelist, but with commas separating all but the last two items, with the name of the operator between the final two tags.Apple, Banana and Orange + 
    tagsettextonlyLike tagsetcommalist, but without the tags linking to tag pages. This is handy for placing in the headerApple, Banana and Orange + 
    weightedlinearbarA stripey table that displays wider bars for more popular tags. The colours used are the same as for tag clouds.
     
     
     
     
     
     
     
     
     
     
     
     
     
     
    		  +
    weightedlongtailA long-tail graph of tags. Beware: not XHTML compliant.
    1.  
    2.  
    3.  
    4.  
    5.  
    6.  
    7.  
    8.  
    9.  
    10.  
    11.  
    12.  
    13.  
    14.  
    		  +
    weightedlongtailverticalA long-tail graph of tags, going down the page. This one is XHTML compliant. Use the longtailvert CSS class to style the text of the tag labels.
    		  +
    coloredtagcloudA tag cloud that differentiates between the popularity of tags through colour. The colours are specified on the Options > Tags page.Apple Banana Blueberry Cherries Grapes Lemon Mango Orange Papaya Pear Pineapple Plum Strawberry Tamarillo  +
    sizedtagcloudA tag cloud that differentiates between the popularity of tags by using different sized fonts. The font sizes are specified on the Options > Tags page.Apple Banana Blueberry Cherries Grapes Lemon Mango Orange Papaya Pear Pineapple Plum Strawberry Tamarillo  +
    coloredsizedtagcloudA tag cloud that differentiates between the popularity of tags through colour and size. The colours and sizes are specified on the Options > Tags page.Apple Banana Blueberry Cherries Grapes Lemon Mango Orange Papaya Pear Pineapple Plum Strawberry Tamarillo  +
    coloredsizedtagcloudwithcountLike coloredsizedtagcloud, but includes the number of times the tag is used after each tag.Apple3 Banana3 Blueberry5 Cherries2 Grapes11 Lemon2 Mango6 Orange1 Papaya3 Pear3 Pineapple2 Plum1 Strawberry4 Tamarillo3  +
    tagcloudlistA tag cloud that differentiates between the popularity of tags through colour and size. The colours and sizes are specified on the Options > Tags page. The tags are presented as an ordered list if you're after something a little more semantic. CSS away to your hearts content.
    1. Apple
    2. Banana
    3. Blueberry
    4. Cherries
    5. Grapes
    6. Lemon
    7. Mango
    8. Orange
    9. Papaya
    10. Pear
    11. Pineapple
    12. Plum
    13. Strawberry
    14. Tamarillo
    		  +
    postsimplelistList of posts separated with spacesSomething fruity My Fruit Bowl Seasonal Produce++ 
    postcommalistList of posts separated with commasSomething fruity, My Fruit Bowl, Seasonal Produce++ 
    posthtmllistList of posts in <li> tags.
  • Something fruity
  • My Fruit Bowl
  • Seasonal Produce
    		• ++ 
    * If viewing the tag page for a single tag e.g. /tags/apple links for both union and intersection will display. If viewing the page for an intersection e.g. /tags/apple+banana then only the intersection link will display. If viewing a union page e.g. /tags/apple|banana then only the union link will display. On a non-tag page; then a big nasty gap will display - use the commalist format on these pages (: