## Custom Formatting

Table of Contents

- Installation
- Configuation
  - Help
  - Configuration Options
- Manage Tags
- Help
- Edit Tags
- Assign Synonyms
- Tidy Tags
- Convert Categories to Tags
- Convert Custom Field Lists to Tags

- Adding UTW Tags to Themes
  - Formatting single.php and index.php
    - Tags for the current post
    - Related tags for the current post
    - Related posts for the current post
    - An inline tag-adder
    - The deprecated one
  - Formatting tag.php
    - Display the current tag set
    - Display the tags related to the current tag set
  - Formatting tags.php
    - Create a tag archive page.
    - Display a tag cloud
    - Display a long-tail graph
    - Display a weighted bar.. thing
  - Predefined Formats
- Custom Formatting
  - The Parts of a Custom Format
  - The Parts of a Format String
  - Putting it all together

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 tags | single - 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 list | last - 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

Placeholder | Description | Output
--- | --- | ---
%tagurl% | The URL of a tag | http://www.site.com/tags/foo_bar
%taglink% | A link to a tag | Foo Bar
%tag% | The tag, as found in URLs | foo_bar
%tagdisplay% | The tag as displayed (includes spaces) | Foo Bar
%tagjsescaped% | The tag, escaped for including in javascript | Bar\'s
%tagcount% | The number of times the tag is in use | 12
%tagid% | The id for the tag | 15
%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 weight | 85%
%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 integer | 24
%tagrelweightcolor% | The colour that corresponds to the tag weight | #111111
%tagrelweightfontsize% | The font size that corresponds to the tag weight | 114%
%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 integer | 24
%tagrelweightcolorrank% | The colour that corresponds to the tag rank | #111111
%tagrelweightfontsizerank% | The font size that corresponds to the tag rank | 114%
%relatedtagids% | A comma separated list of related tag ids | 12,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 | Foo Bar
%flickrtag% | Link to the Flickr page for the tag. This removes spaces from the tag, in the URL. | Foo Bar
%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 tag | Foo Bar
%technoratiurl% | The url to Technorati, with an icon | http://www.technorati.com/tag/foo+bar
%flickrurl% | The url Flickr | http://www.flickr.com/photos/tags/foobar
%deliciousurl% | The url to del.icio.us | http://del.icio.us/tags/foo_bar
%wikipediaurl% | The url to Wikipedia | http://en.wikipedia.org/wiki/foo_bar
%gadabeurl% | The url to gada.be | http://foo.bar.gada.be
%zniffurl% | The url to Zniff | http://zniff.com/?s=%22foo_bar%22&sort=
%rssurl% | The url to the RSS feed | http://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 post | 11

##### 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 (:

Placeholder | Description | Output
--- | --- | ---
%title% | The title of a post. | Something about Apples
%postlink% | A link to a post | Something about Apples
%excerpt% | The excerpt of a post | Apples are a marvellous thing. Filled with appley goodness
%postdate% | The date of the post, formatted using the default date format from the Options > General page | 13 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).