Ultimate Tag Warrior 1.0

A Wordpress plugin by Christine Davis

http://www.neato.co.nz/manyfaces/wordpress-plugins/ultimate-tag-warrior/
Contents
  1. Are you ready, for ultimate tag warrior?
  2. A quick overview
  3. Updates
  4. Installation
  5. Updating your wardrobe theme
    1. Tags on a post
    2. Popular tags
    3. Tag archive
    4. The tag page
    5. Tag cloud
  6. Tag Administration
  7. Linking to Tags
  8. API Reference
    1. ultimate_show_post_tags
    2. ultimate_show_popular_tags
    3. ultimate_tag_archive
    4. ultimate_tag_cloud
    5. ultimate_show_related_tags
    6. ultimate_get_posts
    7. ultimate_save_tags
    8. ultimate_display_tag_widget
    9. ultimate_tag_templates
    10. ultimate_rewrite_rules
    11. function ultimate_tag_admin
    12. ultimate_admin_menus
  9. What else?

  1. Are you ready, for ultimate tag warrior?

    Ultimate tag warrior is not something to be undertaken lightly. There are passages that are twisty, and all alike. There may even be pong. I'm pretty sure there are no sideways scrolling platform games. Actually, I don't know that there is pong or twisty passages either. The point is, ultimate tag warrior has a higher than average barrier to entry: you need to be using Wordpress 1.5(+), you need to be okay with modifying templates, there's some URL rewriting, not to mention database changes (There's a little guy to do that last one for you. All you have to do is ask him. P.S. This is what happens in step four of the installation. More on that, after step three of the installation.).

  2. A quick overview

    This document is getting long and scary. This is an overview that tells you the basics of what you need to know if you've already got a pretty good handle on how to cram plugin functions into your wordpress install.

    To install, run the ultimate-tag-warrior-install.php. This creates a table for tags and a table that maps tags to posts. You only need to run this once - none of the upgrades change the database schema. There's also a default tag.php template file for the default theme to be wrangled as you see fit.

    To use, there are four functions of interest:

    ultimate_show_post_tags($separator=" ", $baseurl='/tag/', $notagmessage = "No Tags", $morelinks="")
    Displays a list of tags associated with the current post. $seperator seperates them, $baseurl is where the text of the tag links to, $notagmessage is displayed when there are no tags, and links to the urls specified in $morelinks are displayed as »s. Usually, the $baseurl and $morelinks look something like "{somesite}/tags/".
    ultimate_show_popular_tags($limit=10)
    Displays a list of the most popular tags. Tags are wrapped in <li> tags, and include the number of matching posts.
    ultimate_tag_cloud($order='tag', $direction='asc')
    Display a space-separated list of tags in the specified order. Tags are displayed as links to the tag page, and have css classes based on popularity. "taglevel1" are most popular (20x more popular than the average), and "taglevel7" are the least popular (less popular than the average).
    ultimate_tag_archive($limit = 20, $postlimit=20)
    Displays an archive-type page, using tags. The top $limit tags are retrieved and displayed in a table with the top $postlimit posts for that tag. If there are more posts, a "More from xxx..." link is included as well. This behaves in a similar manor to a category archive plugin that I've also written (which is why it's in this plugin too).

    As far as wrangling your tags; if you go to the Manage menu in the administration side of wordpress, there is a Tags menu which allows doing some basic administration of tags. You can rename tags, and delete tags at this stage.

    To view tagged postings, go to /tag/{tagname} or /tags/{tagname} for a single tag; or, you can use del.icio.us-esque syntax, and go to /tag(s)/{tag1}+{tag2}+...+{tagn} to get the intersection of a set of tags.

  3. Updates

    Ch-Ch-Ch-Changes
    0.1
    Initial Release
    0.2
    Couple of bug fixes
    Addition of tag clouds
    Addition of administration tools
    1.0
    Tag1+Tag2 syntax is supported for getting the intersection of N tags.
    ultimate_show_post_tags now defaults to linking the text to the local tag page instead of technorati; and allows specifying a list of base tag urls to link to
    1.1
    ultimate_show_related_tags was added.
    Moving from version to version

    From 0.1 to 0.2

    From 0.2 to 1.0

    From 1.0 to 1.1

  4. Installation

    There are six steps to enlightenment through ultimate tag warrior.

    1. Make a backup of your database. In the unlikely event of everything turning into a sticky pile of goo, you'll want one of these. If you are a maverick installer, you can skip this. But don't say I didn't warn you if it turns into a sticky pile of goo!
    2. Copy files into the right places. There are three files that need to be in certain places.
      ultimate-tag-warrior.php
      Copy this file to /wp-content/plugins/
      ultimate-tag-warrior-install.php
      Copy this file to /wp-content/plugins/ as well. (Unless you want to copy it somewhere else. That's cool too. There's nothing special about it that requires it to be here. If you do copy it somewhere else, later on when I get you to run the code that lives in this file; you're on your own.)
      tag.php
      Copy this file to /wp-content/themes/default/
    3. Breathe in. Breathe out. Relax. Congratulate yourself for making it this far. Take a moment to prepare yourself for the next step.
    4. In a web browser, go to http://{yoursite}/wp-content/plugins/ultimate-tag-warrior-install.php which will get the little guy I talked about in the introduction to update the wordpress database with the tables needed for ultimate tag warrior. Two tables are added tags and post2tag (Actually, the tables use the table prefix; so in general, wp_tags and wp_post2tag are added; but it could be blog_tags and blog_post2tag it all just depends on your setup). Tags contains the tags, and post2tag has the associations between tags and posts.
    5. Next, go to http://{yoursite}/wp-admin/plugins.php (the plugins admin page). Somewhere on that list, there ought to be an entry for ultimate tag warrior. Now would be a good time to click the activate link.
    6. Lastly, go to http://{yoursite}/wp-admin/options-permalink.php and click the Update Permalink Structure button. This will enable URL's of the form /tag/tagname. You need to do this after you activate the plugin.

    That's all that needs to happen for tagging to start happening. To be able to see the tags, you'll need to make changes to your templates. Luckilly, the next section tells you what you need to know!

  5. Updating your wardrobe theme

    It turns out that ultimate tag warrior is like a three plugins rolled into one.

    Show tags on a post

    In the index.php template, include a call to ultimate_show_post_tags

    <p class="postmetadata">Posted in <?php the_category(', ') ?> <strong>|</strong> <?php edit_post_link('Edit','','<strong>|</strong>'); ?> <?php comments_popup_link('No Comments &#187;', '1 Comment &#187;', '% Comments &#187;'); ?></p> Could become... <p class="postmetadata">Posted in <?php the_category(', ') ?> <strong>|</strong> Tagged with <?php ultimate_show_post_tags(", ", '/tag/') ?> <strong>|</strong> <?php edit_post_link('Edit','','<strong>|</strong>'); ?> <?php comments_popup_link('No Comments &#187;', '1 Comment &#187;', '% Comments &#187;'); ?></p>

    This is the minimum that I'd do. However, if you are mighty, you might want to consider one (or both) of these next two ways to make your blog more taggy.

    Include a list of popular tags

    The most typical place to put this would be in the sidebar. To display the most popular tags, include something like this in your sidebar:

    <li><h2>Popular Tags</h2> <ul> <?php ultimate_show_popular_tags(); ?> </ul> </li>
    Include tags in the archives

    The third facet of tag display is the tag archive. This sorta fits in the archives.php template (moreso if you're also using the category archive. There's a calendar version on the way, I promise!). You'll want to include something along the lines of this:

    <h2>Archives by Tag:</h2> <ul> <?php ultimate_tag_archive(); ?> </ul>
    Change tag.php to match your style

    If the theme you use is significantly different from the default template, then you're going to need to create a tag.php in your theme. There are two ways to approach this (there could be others, but, well, you know.):

    1. Start with the default tag.php file, and wrangle it to match the rest of the theme.

    2. Start with a copy of index.php, and poke in the bits needed to display items matching a tag.

    Which ever way you choose, there are three bits of code that need to be in the final template.

    1. Twp magical lines at the top of the template, but after the header: global $posts, $id; ultimate_get_posts(); This code will populate the $posts variable with matching posts.
    2. The if statement at the beginning of the main while loop<?php if($id <> "") { ?><? // Ultimate Tag Warrior needs this before the start of a post?>
    3. The close brace at the end of the main while loop

    To include a list of related tags, make a call to the ultimate_show_related_tags function. With no parameters, the function returns tags wrapped in <li> tags.

    Tag cloud

    Perhaps you would like a tag cloud. There are two parts to this: updating a theme to include a call to the tag cloud function, and adding CSS to style the tag cloud.

    For a tag cloud ordered alphabetically, include

    <?php ultimate_tag_cloud() ?>

    For a tag cloud ordered by tag popularity (most to least)

    <?php ultimate_tag_cloud("count","desc") ?>

    For the CSS; you'll need to add some things to the style.css file. What I've included in this example will vary the presentation using the size only. By all means use colours or any other means you'd like to differentiate tag popularity.

    .taglevel1 {font-size:22px} .taglevel2 {font-size:18px} .taglevel3 {font-size:16px} .taglevel4 {font-size:14px} .taglevel5 {font-size:12px} .taglevel6 {font-size:10px} .taglevel7 {font-size:8px}

  6. Tag Administration

    In order to administer tags, you need to be higher than level 3. Hokay! Click on the "Manage" link in the wordpress admin system; then click on the "Tags" submenu. This will display a list of all of the tags. Beside each tag, there are two links.

    Rename tag, takes you to a page which allows changing the display of a tag. Type the new name in the text box, hit "Save", and then your tag will be renamed. If there's already a tag with that name, the display of the tag widgets looks okay (there are no duplicates); but the counts for the tags might be a little bit off if posts have been tagged with both versions. Some kind of merge thing is on my todo list; but you know what they say about building Rome.

    Delete tag, takes you to a confirmation page. If you click yes; then the tag (and the associations to posts) will be deleted. This isn't something you can undo, so be careful (:

  7. Linking to Tags

    The plugin creates redirects that simplify the urls that tags use. If you had the tags pony and circus, these are the ways you could access the tag pages:

    Easy, eh?

  8. API Reference

    ultimate_show_post_tags($separator="&nbsp;", $baseurl='/tag/', $notagmessage = "No Tags", $morelinks = "")
    $seperator
    The character that seperates tags. It only appears between tags, and not at the beginning or end of the list.
    $baseurl
    The base URL to link the text of a tag to. The tag link takes the form {baseurl}{tagname}. The default points to the local tag page.
    $notagmessage
    The text to display when a post has no tags.
    $morelinks
    Either a single link as a string, or an array of links. The links are base urls to other systems that support tagging. As with the base url, the final links take the form of {url}{tagname}. Each link is displayed as an » for brevitys sake.

    This function displays a list of the tags associated with the current post (that is, the one defined by the global variable $post). Each tag is displayed as a link to the tag page specified by the base url, along with » characters for any links specified in $morelinks.

    I opted for using a seperator, rather than a prefix and postfix for the list items; so if you wanted to wrap the tags in <li> tags, you'd need to use </li><li> as the seperator, and wrap the whole list in a pair of <li> tags (not to mention the list tags).

    Useful urls for $morelinks are http://www.technorati.com/tags/ http://del.icio.us/tags/ and http://www.flickr.com/photos/tags/

    ultimate_show_popular_tags($limit=10)
    $limit
    The maximum number of tags to retrieve.

    This function creates a list of the most popular tags, with the number of occurances. The opening and closing list tags aren't included, to allow choosing between ordered or unordered lists in the enclosing template.

    The format of the tags that are output is:

    <li>{tagname} ({count})</li> e.g. <li>Photo (87)</li>

    ultimate_tag_archive($limit = 20, $postlimit=20)
    $limit
    The maximum number of tags to get
    $postlimit
    The maximum number of posts to get for each tag

    Perhaps you are familiar with the category archive plugin I wrote. This function creates a tag archive in the same format; but using tags instead of categories.

    This function returns the top tags (the maximum is specified by $limit), and the most recent posts (the maximum number of posts to display is specified by $postlimit). If there are more posts, then a link to the tag page is also displayed.

    css class = tagarchive

    css class = tagarchivename
    {the name of the tag} - {the total number of matching posts}
    css class = tagarchiveposts
    {the most recent postings for this tag. If there are more postings than the limit specified, a link is included to the tag page.}
    ultimate_tag_cloud($order='tag', $direction='asc')
    $order
    The order to display tags in. Valid choices are "tag" and "count".
    $direction
    The direction to sort the tags in. Valid choices are "asc" (makes most sense for sorting by tag) and "desc" (makes most sense for sorting by count).

    This function displays a list of tags, in the specified order. The tags are displayed using a CSS class depending on the tag popularity; and the tags link to their tag page.

    The popularity algorithm is kinda hinky. The popularity of a tag depends on how many posts it appears on compared to the average.

    "taglevel1" is the largest, and has the tags which are used more than 20x the average; and "taglevel7" is the smallest, and has all of the tags which are used less than average. The rest of the tag levels cut off at 10x the average, 6x the average, 4x the average, 2x the average, and 1x than the average.

    ultimate_show_related_tags($pre = '<li>', $post = '</li>', $notags='None')
    $pre
    Prefix for each tag
    $post
    Postfix for each tag
    $notags
    The text to display when there are no related tags.

    This function displays a list of tags that are related to the current tag set (if you are looking at /tag/monkey then the current tag set is monkey. /tag/monkey+banana has monkey and banana as its current tag set). Each of the tags is wrapped in the prefix and postfix specified; and for each tag, there is a + link, that adds the tag to the tag set, a link to the tag, and an indication of the number of times the tag is used.

    Related tags are all of the tags, from all of the posts that match the current tag set; excluding the ones which are already part of the current tag set.

    If you place this function pretty much anywhere but tag.php, nothing is going to happen.

    The rest of the functions do the behind the scenes donkey-work; and as such aren't too interesting in the day-to-day running of ultimate tag warrior.

    ultimate_get_posts()

    The code for selecting tagged posts from the database. It looks in the tag get variable; and when more than one tag is specified, the posts which match all of the tags are retrieved.

    ultimate_save_tags($postID)
    $postID
    The ID of the current post

    Writes the tags for the current post to the database.

    ultimate_display_tag_widget()

    The code for displaying the tag entry box on the post editing page.

    ultimate_tag_templates()

    The code for displaying the tag pages, and the tag archive page.

    ultimate_rewrite_rules()

    The code for redirecting requests to /tag/ and /tags/.

    function ultimate_tag_admin()

    The code that performs the administration magic.

    ultimate_admin_menus()

    The code that hooks the administration up to the manage menu.

  9. What else?

    I have a todo list. Some of these things are more likely than others to get done.