jotsheet

On Jack Vinson’s site, I noticed an interesting though unobtrusive section of “related content” links. I thought at first that these were local to his KM blog, but they’re actually external links. It’s all done via the excellent Waypath plugin.

The Waypath plug-in is ported to Movable Type, Drupal, Radio, WordPress, B2, and other publishing systems. Upon posting your entry, the plugin, called via a simple tag, queries Waypath’s server for related content and inserts preformatted HTML linking to other blogs. With a little bit of tweaking, which I share below, I think this could be a great addition for many blogs out there.

Table of contents

1. Recommended configuration
2. Further recommendations
3. A note about ampersands
4. Styling Waypath’s HTML
5. Advanced tweaks with Regex

Recommended configuration

First, you’d better download the plug-in. Installation is simple and straightforward, and the README is in plain English. These are the settings that worked best for me (I use Movable Type):

<MTRelatedFromWaypath maxResults="3" focus="3" style="2" decode_html="1">

• maxResults="3" : Three is a good number of related links. No need to crowd your own post with others’ content.
• focus="3" : Important setting! Keep the focus narrow! With the default focus=”2″, I got lots of irrelevant stuff.
• style="2" : I wish that the plugin provided shorter summaries or some control over their length. The summaries returned by style="3" are just too long.
• decode_html="1" : Optional. Fixes some strange HTML stuff I was getting in a few of the links. (But see the warning in the section “A note about ampersands” below.)

Further recommendations (with MT-specific code but general ideas)

As you might imagine, the Waypath recommendation engine works best for stuff that other people blog about, such as politics, sports, and entertainment. You’ll find that some of the most irrelevant results are returned when you’re posting narcissistic entries about your own life. That’s why it’s a good idea to exclude by category. The simplest way to do this in MT is with MTSwitch. If you need more fine-grained control, try the Compare plugin. The following code would restrict the Waypath plugin to the Sports and Entertainment categories on your hypothetical blog:

This also has the benefit of reducing your rebuild time, since the Waypath server will only be queried for those relevant categories. On subsequent rebuilds, however, the results are cached, so the Waypath server is not queried more than it needs be, unless you change an option such as focus (in which case a whole need round of Waypath queries are required).

A note about ampersands (Or, why don’t my pages validate anymore?!)

To validate, the W3C wants ampersands in URLs to be encoded in URLs. Don’t ask me why; it’s probably the stupidest validation rule ever, since no browser in the history of the WWW has gotten confused by a bare ampersand in a URL. Nevertheless, to meet spec, ampersands in URLs should be “&” and not “&”.

Waypath starts out generating good code, and all of the ampersands in URLs are encoded. The problem is that when we use decode_html="1" to ensure proper display of related links, the option decodes the proper & to the improper &. So you’re between a rock and a hard place: if you want your pages to look good to visitors, use decode_html="1". If you want geek chic, don’t use it. (Ideally, Waypath should fix the plugin to never decode ampersands in URLs.)

(As a side note, it seems you cannot use the Amputator plugin with decode_html="1" to get the best of both worlds. Amputator has no effect on MTRelatedFromWaypath if decode_html="1" is included.)

Here’s my recommendation. It’s not that vital to use decode_html="1" if you’re not displaying summaries from other blog posts, because that’s where this option does its real work. Thus:

• If you choose style="1" or style="2", omit decode_html="1" so that your pages have a shot at validating. However, you’ll still probably have to deal with the problem of '. I tell you how to fix it below.
• If you choose style="3", include decode_html="1" and live with a non-validating site. The frequent display issues that crop up aren’t worth the overrated status symbol of valid (X)HTML.

The HTML that Waypath spits out (and some CSS to style it)

With style="2", this is the basic HTML you’ll get:

And here’s the CSS I use to style the above HTML:

The one that will impress your friends is the rule for .wp-item-blogname:before, which adds the text “from blog” before the blog’s name. This is actually useful.

If you’re so inclined, you could hide the Waypath image, although I think it’s quite nice-looking and I’ve left it alone. You’d hide it with this:

Advanced tweaks with Regex

To alter the content of what’s produced by the Waypath plugin, you’ll need Brad Choate’s Regex plugin. With this powerful tool, you can hack up the output of the Waypath plugin to tweak it in interesting ways.

Changing the Waypath image

For example, a better solution than linking to the Waypath image remotely is to store the image locally. To do this, you’ll need to save the file to your Web server and change all of the references to the Waypath image URL using the Regex plugin. You can also put in the width, height, and title attributes for an added bonus.

Don’t forget to apply the regex, like so: <MTRelatedFromWaypath regex="waypathImage">

Adding a title attribute to Waypath links

You might be interested in adding a descriptive title attribute to your Waypath links. Since links to source blogs have the attribute ltyp=a and normal recommended links have the attribute ltype=s, you can give your readers a nice hint about the related links from Waypath.

Note: I do not recommend altering those regular expressions. I spent something like two hours tooling around to get them to work, and I have no idea why! They’re very simple, and I started out doing something sexier, but I encountered some veeerrry funky behavior with Mr. Choate’s prize plugin. Anyhow.

Fixing the ' thorn in your side

Contrary to popularly held nerd belief, “'” is not a valid HTML entity. The numeric entity, “'”, is. So the W3C validator will complain, and some browsers will complain. What you can do is replace the ' with ' and go on your way.

Adding the “from blog” descriptor

Last up is a highly useful content modification of Waypath’s output. Above, via CSS, we added the text “from blog:” before the source blog by using the .wp-item-blogname:before selector. Problem is, :before is not understood by Internet Explorer, and that’s a lot of the Web audience. With MTRegex, however, we can just insert the text, so let’s do it:

All the regex, rolled into a big ball

And remember, to apply all of these regular expressions, we need to call them somehow. You can do it a couple of ways, but here’s an efficient way:

Share This