## Ultimate Tag Warrior 3: Help

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

The Ultimate Tag Warrior is a tagging plugin for WordPress, designed by the rockin' Christine Davis. The source page for updated information on this plugin is found at Ultimate Tag Warrior.

The Ultimate Tag Warrior (UTW) is designed for WordPress sites to increase the possibilities and functions for tagging posts and expanding site navigation through the creation of lists of tags. It allows storing a set of keywords (current slang calls these "tags") against posts that behave like categories - the tags can be displayed on a post as links, and when clicked, the visitor is taken to an archive page for that tag. There are also RSS/atom feeds available for each tag. Unlike categories, for example, you can also view archive pages and feeds for sets of tags such as the posts which are tagged with both "photograph" and "food".

Beyond the category-like behaviour, Ultimate Tag Warrior plugin provides ways of getting an overview of your tags through tag clouds and graphic representation such as a long tail graph and/or weighted bar arrangement. UTW can also be coaxed into linking to other tag-savvy websites such as del.icio.us, Flickr and Technorati.

To add tags to posts, a menu is created listing all the tags in use on the site right in the Write Post panel. Click a tag in the list and it will be instantly added to your tag list. One of the more splendid things that it can do, is use the Yahoo! content analysis bits and pieces tagyu.com to look at the text of the current post, and make suggestions for the tags.

The Ultimate Tag Warrior is not for the timid. While it can be used by anyone to add tags to your posts and site, it has a wide variety of features that allow for a wide range of customization. I'll do my best to showcase the most common usages here, but for more graphic detail, check out the Ultimate Tag Warrior main page on my site.

### Installation

Currently, this plugin works with Wordpress 2.0 (do sing out if you're using 1.5'ish, and I'll see what I can do for you)

1. Copy the files to `wp-content/plugins/UltimateTagWarrior`.
2. Activate the Plugin: Go to the Plugins Panel and you will see three plugins listed under UltimateTagWarrior.
   - Ultimate Tag Warrior 3: This is the main plugin. Its functionality is covered by this document.
   - Ultimate Tag Warrior: Tag Archive 1.0: Optional Add-on plugin to render an archive view, based on tags. Requires Ultimate Tag Warrior 2.5.1+.
   - Ultimate Tag Warrior 1.3 Legacy: This is a plugin for compatibility with UTW 1.3. With this plugin installed, the syntax of the older plugin will continue to work; allowing you to use the new plugin code without making changes to your templates. You probably don't need this (:
3. Set Options: From the WordPress Administration Panels, choose Options > Tags. Set the options to meet your needs..

### Configuration

Ultimate Tag Warrior offers a wide range of customization options.

#### Help!

If you need access to this file for reference or help, or the link to the main Ultimate Tag Warrior page, I've provided two links under Help at the top of the screen to guide you. I've also added convenient links to move between the Configuration and Manage Tags pages.

#### Configuration Options

##### URL Settings

Use URL rewriting
  Enabling this will use the base URL and trailing slash options to render links to local tag pages as `/tags/tagname` instead of `index.php?tag=tagname`. Usage of this requires enabling Permalinks and making sure your `.htaccess` file is writable.
base url
  This is the location of the tag "folder" relative to your WordPress site root. It should have both leading and trailing slashes. If you change this, either click the Update Permalinks button or manually change your `.htaccess` file to reflect the change.
Include trailing slash on tag URLs
  This will append rewritten URLs with a slash, so instead of `/tags/tag`, URLs are `/tags/tag/`.

##### Meta Keywords

Include meta keywords
  Enabling this will automagically put a

      <meta name="keywords" content="comma, list, of, tags" />

  into the page header.

##### Embedded Tags

Use embedded tags
  Enabling this will cause wordpress to look for embedded tags when saving and displaying posts. A single embedded tag is marked [tag]like this[/tag], is added to the post when the post is saved and displays as a link when the post is displayed. A set of tags is marked [tags]like this, and this[/tags], and are added to the post when the post is saved, but do not display on the post.

##### Debugging

Include debugging information
  This will include debug information in comments. (Presently, there is no debug information (; )

##### Automatic Tag Link Inclusion (Automatic Feed Tags and Content Tags)

Include local tag links in feeds
  This will append a comma separated list of tags to the end of content items, when the content item appears in a feed.
Automatically include primary and secondary tag links
  These options allow specifying whether tag links should be included in the post text automatically. For each set of tag links, there is a list of the pre-defined formats that are available. The selected format will be used to display the tags. The prefix will display before the tags, and the suffix afterwards. There's also an option to indicate whether the tags should display before or after the content.

##### Global Formatting Settings

Colors and Font sizes
  This is the section that sets the font colors and sizes for displaying a tag cloud on your site. The colors must be full six digit hexadecimal values (e.g. `#FFFFFF` or `#8F5B2L`). Font sizes can be set for the most and least popular tags. Use only positive values for these. At the bottom of the list you can choose the font size unit as percentage, `px` (pixel, `pt` (point), or `em`. Both values use the same units.
Icons to display in icon formats
  This allows choosing the icons that display for icon based formats. You can choose as many icons to include as you would like. The same set of icons will appear in all locations. If you need to have different icons in different places; let me know, and I'll see if I can think of an alternative that will allow that.
The text to display when there are no tags
  This allows controlling the text that displays when there are no tags. You can leave this blank if you would like (:

##### Editing Options

Automatically add categories as tags
  This will add the names of any categories selected to the list of tags. They will appear in the post and in the tag cloud or lists.
Always display tag links on edit post page
  You have three choices here for the method to display the list of links to existing tags on the Write Post panel. None will not display anything. Tag List will display a list of all the existing tags. Dropdown will display the list in a dropdown menu.

##### Finally..

Save
  To save the changes you've made within this section, click the Save button.

### Manage Tags

#### Help!

If you need access to this file for reference or help, or the link to the main Ultimate Tag Warrior page, I've provided two links under Help at the top of the screen to guide you. I've also added convenient links to move between the Configuration and Manage Tags pages.

#### Edit Tags

The Edit Tags section allows renaming, replacing and deleting tags. If you add more than one tag, then each of the tags will be associated with each of the posts that were tagged with the original tag. For example, if you rename the `bananas` category to "`fruit, yellow`", then any post that was tagged with `banana` will become tagged with both `fruit` and `yellow` instead.

If you Rename to a tag that is already in use, then the two tags will merge together.

Deleting deletes a tag. You cannot undo this. There is a pesky dialog box that pops up to confirm deletions, so you better be sure about your choice.

#### Assign Synonyms

The Assign Synonyms section allows associating synonyms with tags. It's a way of having multiple words map on to a single tag. For example, if you had a `photography` tag; you might add `photo` and `photograph` as synonyms. Presently, the only place where synonyms are used is in the urls of tag pages - with the `photo` and `photograph` synonyms in place, if I go to the /tags/photo page, then the posts tagged with photography will display.

#### Tidy Tags

Use this at your own risk. Backup your database first, including the tag and post2tag tables in your backup.

While Tidy Tags seems to work okay, it does have the potential to mangle your tags. Use this function if you have a lot of orphaned tags or duplicate tags. Tidy Tags will go through the tags table and clean out orphaned or duplicate tags and sort everything out.

#### Convert Categories to Tags

Use this at your own risk. Backup your database first, including the tag and post2tag tables in your backup.

Once this is done, it cannot easily be undone. Clicking this button will add your site's Categories for all of your posts as tags and include them in the post tags, tag lists, and tag cloud.

#### Custom Fields

If you are currently using another plugin or custom fields for keywords or tags, you can import these into Ultimate Tag Warrior. In order to work, the keywords or tags must use the Custom Fields as seen on the Advanced Editing view of the Write Post panel.

Type in the custom field name into the custom field to import from. In the box for the delimiter, enter the character(s) used to separate each tag in the option field value area. This is usually spaces, commas, semi-colons, or pipe ( | ).

### Using Ultimate Tag Warrior

#### Adding Tags Via the Write Post Screen

This is the vanilla way of adding tags to a post. When you're on the Write Post (or Edit Post) screen, there is a text box labelled "Tags". If you type the tags you would like to associate with the post in the box, they will be saved when the post gets saved.

Depending on the editing options you've selected, there might be a quick-entry-thingamer. If you have the dropdown option selected, there will be a dropdown list with all of your tags. If you select a tag from the list, it will be added to the tag box. If you have the tag list option chosen, a list of links for each of your tags will display; and clicking on a tag link will add it to the tags box. Again, when you save the post, your tags will be saved also.

#### Getting Tag Suggestions

There is a Get Keyword Suggestions button. If you click it, it will send a request to tagyu.com for keyword suggestions. Clicking on any tags it returns will add those tags to the current post.

#### Using Embedded Tags

Embedded tags are tags which form a part of the content. They enable you to place tags in the middle of your content, rather than just at the end; and they allow you to add tags without being tied to the write post screen in wordpress.

For a single tag which is to be converted into an embedded tag link, the following syntax is used:

[tag]sometag[/tag]
When the post gets saved, "sometag" will be added to the post as a tag, and when the post is displayed, "[tag]sometag[/tag]" will be replaced with a link to the local tag pge for "sometag". Single tags will also display in any tags-for-posts type lists for the post.

In addition to sprinkling singular tags through your posts, you can add a block of tags also.

[tags]first tag, second tag[/tags]
If you place a comma separated list within "[tags]" and "[/tags]"; then each of those tags will be added to the post, when the post is saved. The "[tags]..[/tags]" block will not display when the post is viewed.

The embedded tags functionality will only add tags to a post, not overwrite them.

And if you don't like the start and end markers, or the format for the single links, the values used can all be found at the top of the ultimate-tag-warrior-actions.php file if you want to make changes. Changing the start and end markers can make the sky fall on your head if you aren't careful; and if you want to change the way the single links look you'll need to provide a custom format.