Custom Formatting

Table of Contents

  • Adding UTW Tags to Themes
  • Custom Formatting

    • Custom formatting is a way of specifying the way lists of tags should display. If you want to display tags in a way that the predefined formats can't accomodate, this is the way to do it.

    A custom format is an associative array of format strings, which specify how different parts of a tag list display. Format strings contain placeholders for various bits of tag information.

    The parts of a custom format

    This is an overview of the various parts of a custom format. pre and post wrap everything; first/default/last is the usual way of displaying tags (default is the only one that's really needed; first and last provide a way of changing the way the first and last item look.). single and none are special cases.

    pre - goes in front of the tagssingle - how to format the tag when there is exactly one tag (useful when using a first format that depends on a last format to close HTML tags and what-not)post - goes after the tags
    first - formats the first item differently (when specified. Otherwise use default)default - the format of the items in the middle of the listlast - formats the last item differently (when specified. Otherwise use default)
    none - displays when there are no tags

    The parts of the format that are going to be included are placed into an array, thusly:

    $format = array('pre'=>'<span class="tags">','default'=>'%taglink%','post'=>'</span>');

    The order of the parts doesn't matter; but the case of the array keys does.

    The parts of a format string

    Each format string can contain bits of text, HTML markup and placeholders. The placeholders are bits which get replaced by tag specific information like links to tags, icons or frequency of use values.

    Replacement bits for a tag format
    PlaceholderDescriptionOutput
    %tagurl%The URL of a taghttp://www.site.com/tags/foo_bar
    %taglink%A link to a tag
    %tag%The tag, as found in URLsfoo_bar
    %tagdisplay%The tag as displayed (includes spaces)Foo Bar
    %tagjsescaped%The tag, escaped for including in javascriptBar\'s
    %tagcount%The number of times the tag is in use12
    %tagid%The id for the tag15
    %tagweight%The percentage of times this tag is used (#this tag/#tag associations)7.56
    %tagweightint%The ceiling of %tagweight%8
    %tagweightcolor%The colour that corresponds to the tag weight#888888
    %tagweightfontsize%The font size that corresponds to the tag weight85%
    %tagrelweight%The relative tag weight (#this tag/#the maximum tag). The most popular has a relative weight of 100%. If the most popular tag is used 25 times, and the least popular is used once; then the least popular has a weight of (1/25) * 100 = 4%23.5
    %tagrelweightint%The relative tag weight, rounded up to the nearest integer24
    %tagrelweightcolor%The colour that corresponds to the tag weight#111111
    %tagrelweightfontsize%The font size that corresponds to the tag weight114%
    %tagrelweightrank%The tag rank of a tag. If there are tags used 10 times, 8 times, 2 times and once; the tag rank of 10x is 100, 8x is 75, 2x is 50 and 1x is 25. This is useful for evening out spikes at the popular end of the scale.23.5
    %tagrelweightintrank%The tag rank, rounded up to the nearest integer24
    %tagrelweightcolorrank%The colour that corresponds to the tag rank#111111
    %tagrelweightfontsizerank%The font size that corresponds to the tag rank114%
    %relatedtagids%A comma separated list of related tag ids12,42,56
    %intersectionurl%If viewing either a tag page, or the intersection of two or more tags, this is the URL of the page to see the intersection of the current tags, and the tag being displayed.http://www.site.com/tags/Monkey+Fishsticks+Foo_Bar
    %unionurl%If viewing either a tag page, or the union of two or more tags, this is the URL of the page to see the union of the current tags, and the tag being displayed.http://www.site.com/tags/Monkey|Fishsticks|Foo_Bar
    %intersectionicon%Link to the intersection url, with the intersection icon.
    %intersectionlink%Link to the intersection url, displaying a + as the link text+
    %unionicon%Link to the union url, with the union icon
    %unionlink% Link to the intersection url, displaying a | as the link text|
    %operatortext%On intersection pages, "and"; on union pages "or". Otherwise empty.and
    %operatorsymbol%On intersection pages, "+"; on union pages "|". Otherwise empty.+
    %technoratitag%Link to the Technorati page for the tag. Turns spaces into +'s in the tag URL
    %flickrtag%Link to the Flickr page for the tag. This removes spaces from the tag, in the URL.
    %delicioustag%Link to the del.icio.us page for the tag. The tag in the URL is left unchanged.Foo Bar
    %wikipediatag%Link to the Wikipedia page for the tag. Spaces are converted to underscores in the tag URL.Foo Bar
    %gadabetag%Link to the gada.be page for the tag. Spaces are converted to fullstops in the tag URL.Foo Bar
    %znifftag%Link to the Zniff page for the tag. Spaces are converted to underscores in the tag URL.Foo Bar
    %rsstag%A link to the RSS feed for the tagFoo Bar
    %technoratiurl%The url to Technorati, with an iconhttp://www.technorati.com/tag/foo+bar
    %flickrurl%The url Flickrhttp://www.flickr.com/photos/tags/foobar
    %deliciousurl%The url to del.icio.ushttp://del.icio.us/tags/foo_bar
    %wikipediaurl%The url to Wikipediahttp://en.wikipedia.org/wiki/foo_bar
    %gadabeurl%The url to gada.behttp://foo.bar.gada.be
    %zniffurl%The url to Zniffhttp://zniff.com/?s=%22foo_bar%22&sort=
    %rssurl%The url to the RSS feedhttp://www.site.com/tags/foo_bar/feed/rss
    %technoratiicon%Links to Technorati, with an icon
    %flickricon%Links to Flickr, with an icon
    %deliciousicon%Links to del.icio.us with an icon
    %wikipediaicon%Links to Wikipedia with an icon
    %gadabeicon%Links to gada.be with an icon
    %znifficon%Links to Zniff with an icon
    %rssicon%Link to the RSS feed, with an icon
    %tagsetrssicon%Link to the RSS feed of the current tagset, with an icon
    %icons%Display a set of icons. The union and intersection icons only display when appropriate; the other icons can be toggled on and off through the Options page.
    %postid%The ID of the current post11
    Replacement bits for a posts format

    There aren't as many placeholders for posts as there are for tags. I figure that most of the time posts will be displayed in the Wordpress Loop; and as such the standard posty-bits are available. Let me know if there's anything else you need (:

    PlaceholderDescriptionOutput
    %title%The title of a post.Something about Apples
    %postlink%A link to a postSomething about Apples
    %excerpt%The excerpt of a postApples are a marvellous thing. Filled with appley goodness
    %postdate%The date of the post, formatted using the default date format from the Options > General page13 January, 2006
    %content%The contents of a post...

    Putting it all together

    This is a simple format with everything! It renders tags inside a span named tags-134 (where 134 is the ID of the current post); and puts square brackets around the whole list.

    $format = array( // Create an array
        'pre'=>'<span class="tags-%postid%">', // specify a "pre" string. This will go in front of the list of tags.
        'single'=>'[%taglink%]', // The display for a single tag. It includes both square brackets.
        'first'=>'[%taglink% ', // The display for the first item, when there are two or more.
        'default'=>'%taglink% ', // The display of the items in the middle of the list
        'last'=>'%taglink%]', // The display of the last item.
        'none'=>'[No Tags]', // The text that displays when there are no tags specified.
        'post'=>'</span>'); // Close off the span from the pre format part.

    Not all of the formatting bits are required (including default is strongly recommended, however); so if the format you are constructing doesn't need one of the bits, or doesn't need anything to display, you can leave it out. This is a simpler format that uses only a subset of the formatting parts: it shows each tag in a box, separated by pipes; with no pre or post wrapping the list and nothing displayed when there are no tags.

    $format = array(
        'single'=>'[%taglink%]', // Self-closing single item
        'default'=>'[%taglink%] | ', // First isn't needed, since it is the same as the default
        'last'=>'[%taglink%]'); // Different behaviour for the last (no pipe)

    For more examples, have a look in the GetFormatForType function in ultimate-tag-warrior-core.php - each of the predefined formats has an underlying custom format (even the long tail graph).