WordPress.org

Plugin Directory

wiki:UltimateTagWarrior

Ultimate Tag Warrior

A Brief Overview

Ultimate Tag Warrior is probably the broadest of the tagging plugins floating around at the moment. In no particular order, it will...

  • Supports the display of posts in a tag intersection (e.g. Tag1 and Tag2)
  • Display the tags for a post
  • Display related tags for a post, tag, or intersection of tags
  • Display a tag cloud (varied by colour, font size or both... in either most popular first or alphabetical)
  • Display a.. weighted.. box.. graph.. thing. I need to think of a better name for it (:
  • ...and let you pick the start and end colours for the tag cloud and weighted box graph thing
  • Display a long-tail histogram of your top 150 tags
  • Allow easy modification of tags through the administration interface
  • Kickstart tagging by importing either existing categories as tags, or values from a custom field
  • Not hold you hostage! you can export the tags assigned to posts to a custom field
  • Allow you to format lists of tags with a detailed level of control...
  • ...but also hides the details of formatting if your sticking to fairly ordinary ways of displaying tags
  • Do more things in the next release: I have a fairly big todo list still todone...

Install

  1. Copy all of the plugin files into a folder located here: wp-content/plugins/UltimateTagWarrior
  1. Activate the plugin (You'll see two versions: 2.5.ish, and 1.3 Legacy. If you've previously installed UTW, enabling the legacy plugin will allow you to keep using the old template tags. There's also a tag archive plugin, which, unless you were planning on using it, can be left un-activated.)

At this point, you can tag posts; and links to tag pages on Technorati will automatically be appended to your posts. However, it's certainly worth looking into the configuration options which are available...

Configuration

Go into the Site Admin part of wordpress, then go to Manage, then the Tags sub-menu. This is where you'll find all of the configuration options, along with a set of tag administration tasks (but more on those later..)

The configuration options available are...

  • Base Url - When url rewriting is enabled, this is the place where the tags reside. This should be a directory name, relative to the root level of your site. This will almost always take the form of /tag/ (or other synonym for tag). Remember to update your .htaccess file when you change this value.
  • Automatically include local tag links - When set to yes, a comma separated list of tag links will be automagically appended to posts. The links will point at the local tag cosmos for your site.
  • Automatically include Technorati tag links - When set to yes, a comma separated list of Technorati tag links will be automagically appended.
  • Automatically add categories as tags - When set to yes, when a post is saved, any categories assigned to it will be added as tags. This is in addition to any tags in the tag field.
  • Use url rewriting for local tag urls (/tag/tag instead of index.php?tag=tag) - When set to yes, local tag cosmos urls will be of the form {home location}{base url}{tag name}. Otherwise, urls take the form {home location}/index.php?tag=tag. Before enabling this, ensure your .htaccess file is up to date!
  • Always display tag links on edit post page (instead of switching to a dropdown when there are many tags) - When set to yes, the post editing page will always show links to your tags, for easy tag editing. When this is set to know, the display switches to a dropdown list once there are fifty active tags (There comes a point where it gets hard to find tags. Trust me.)
  • Most popular color (for tag clouds) - If there is a tag cloud on any of your pages, this is the colour that the most popular tag will display in. Needs to be a colour in the form of #xxxxxx.
  • Least popular color (for tag clouds) - If there is a tag cloud on any of your pages, this is the colour that the least popular tag will display in. Needs to be a colour in the form of #xxxxxx.

Template Tags

First, a word about formatting

Ultimate Tag Warrior has a two-part formatting system: fine grained formatting definitions; with a set of "named" formats for common display situations. Named formats do 98% of what you need to do; so forget about the underlying magic for now, but remember that it's there if there's something a little out of the ordinary that you'd like to do.

The current named formats are...

htmllist

Local tag links, wrapped in <li> tags. The ul/ol tags aren't included to allow a bit more flexibility

commalist

A list of local tag links, seperated by commas. There's no trailing comma, because that would look stupid.

technoraticommalist

Like a "commalist", but linking to Technorati tag page instead of the local tag page.

weightedlinearbar

Draws a bar representation of tags. Popular tags have wide segments, less popular tags have narrower segments. Be the first one on your block to display your tags like this! This uses the tag cloud colours which can be specified through the tag management page. This suits tag sets of ~50 or less.

weightedlongtail

Draws a long tail histogram of your tags. This suits tag sets ~50 or more.

coloredtagcloud

Draws a tag cloud, with less popular tags in light grey.

sizedtagcloud

Draws a tag cloud, with popular tags in bigger letters.

coloredsizedtagcloud or sizedcoloredtagcloud

Draws a tag cloud with both the colour and size indicating prominence.

coloredsizedtagcloudwithcount

Draws a tag cloud with the colour and size; with the number of occurances following each tag.

Template Tags

The template tags available are a pretty homogenous bunch. If you're using named formats (see above); include template tags thusly:

<?php UTW_ShowSomething("formatname") ?>

(If, on the other hand, you're wanting to use a custom format; <?php UTW_ShowSomething("custom", $formattingObject) ?> is what you need. The structure of a formatting object is described later on...)

For example, to include a coloured tag cloud, you'd include this:

<?php UTW_ShowWeightedTagSetAlphabetical("coloredsizedtagcloud") ?>

If you wanted to show the tags for the current post, you could include this:

<?php UTW_ShowTagsForCurrentPost("commalist") ?>

or this:

<?php UTW_ShowTagsForCurrentPost("htmllist") ?>

depending on how you wanted the tags formatted. The first option would display "Tag1, Tag2" whereas the second would be "<li>Tag1</li><li>Tag2</li>".

Got that? Awesome.

Here's a list of the available functions:

UTW_ShowTagsForCurrentPost($formattype, $format="")

Shows the tags for the current post. Put this guy inside the wordpress loop.

UTW_ShowRelatedTagsForCurrentPost($formattype, $format="")

Shows related tags for the current post. Again, this belongs inside the wordpress loop.

UTW_ShowRelatedTagsForCurrentTagSet($formattype, $format="")

Shows the related tags for the current requested tags (for http://somesite/tag/foo+monkey the current requested tags are foo and monkey. Got that? Good). This belongs on the tag.php template.

UTW_ShowCurrentTagSet($formattype, $format="")

Shows the current requested tags. Again, belongs on tag.php

UTW_ShowWeightedTagSet($formattype, $format="")

Shows tags in weighted order. This can go anywhere.

UTW_ShowWeightedTagSetAlphabetical($formattype, $format="")

Shows tags in alphabetical order; but allows doing weighted formatting. This can go anywhere.

Administration

Edit Tags The Edit Tags functionality allows taking an existing tag and remove it, change its name, or split it into more than one tag.

To delete, select the tag from the dropdown list, and click the Delete Tag button. Click OK in the confirmation box.

To rename, select the tag from the dropdown list, enter the new name in the text box, and click the Rename button.

To split, select the tag from the dropdown list, enter a space separated list of tags in the text box, and click the Rename button.

Easy, eh?

Tidy Tags Tidy Tags is a utility for cleaning out orphans, and getting rid of duplicates. It does widesweeping changes to your tag data, so I suggest doing a backup of your tag tables before doing this.

Probably, you'll never need to use this; mostly it's for cleaning up data left behind by older versions of the plugin.

Convert Tags Convert Tags is a utility that will add the categories assigned to each of your posts as tags for those posts. Any tags which are already assigned to the posts are retained.

Again, this does widesweeping changes; so back up your tags first!

Custom Fields (I guess this could fall under convert tags, but no matter. In another version!) Custom Fields provides a way to move tags between the Ultimate Tag Warrior tag store and a custom field.

The Custom field name is the name of the custom field to be imported/exported from/to; and the delimiter is the character(s) to be used to delimit the tag string in the custom field.

When importing tags, the existing tags stored in UTW will be retained; however, when exporting, the UTW tags will overwrite any existing values. If you wish to preserve the existing values, import the tags into UTW first; then export.

Again, this does widesweeping changes; so back up your database first. (Yes, the whole thing. It's not just tags you can mess up with this one)

Custom Formatting Strings

Formatting involves either a single formatting string, or an associative array of formatting strings. If a single formatting string is specified, then that formatting string is used for every item in the list. If there's an array of strings, the appropriate formatting string is used for the various parts of the tag list (this will make more sense when you see it in practice)

  • %taglink% will display a link to the local tag page
  • %tag% will display the name of the tag
  • %tagdisplay% will display the presentation version of the tag (spaces instead of underscores, at the moment)
  • %tagcount% will display the number of occurances of a tag (not always applicable)
  • %tagweight% will display the percentage of times this tag is used (0-100)
  • %tagweightint% will display the tag weight, rounded up to the nearest integer
  • %tagweightcolor% will pick a colour based on the tag weight (not so useful, but here for completeness)
  • %tagweightfontsize% will pick a font size based on the tag weight (not so useful, but here for completeness)
  • %tagrelweight% will display the relative weight of the tag. The most popular tag has a weight of 100.
  • %tagrelweightint% will display the relative weight, rounded up to the nearest integer
  • %tagrelweightcolor% will pick a colour based on the relative tag weight
  • %tagrelweightfontsize% will pick a font size based on the relative tag weight
  • %technoratitag% will display a link to the tag page on Technorati
  • %flickrtag% will display a link to the tag page on Flickr
  • %delicioustag% will display a link to the tag page on del.icio.us
  • %wikipediatag% will display a link to the corresponding item in the Wikipedia

I'm happy to add any others to the list..

Now, the array of formatting strings, thing.

  • pre - the string to place in front of the list of tags
  • first - the formatting string to use for the first item
  • last - the formatting string to use for the last item
  • default - the formatting string to use for the items in between (and when the first or last strings aren't specified)
  • none - the formatting string to use when there are no items in the list
  • post - the string to place at the end of the list of tags

Perhaps examples will make this clearer! <li>%taglink%</li> will display all of the items in the list as links to the tag page, wrapped in <li> html tags. array("default"=>"%taglink%, ", "last"=>"%taglink%", "none"=>"No Tags") will display a comma list, with no trailing comma; or just "No Tags" if there are no items in the list.

Latest Source:

Lives here

Plugin Author:

Is Christine Davis, and she lives here

Last modified 8 years ago Last modified on 04/06/06 22:14:41