An unexpected side effect to upgrading.
This afternoon, I did my first WordPress 2.0.4 to WordPress 2.1 upgrade. The site I chose for the upgrade was the companion Web site for the WordPress book I co-authored with Miraz Jordan, WordPress 2: Visual QuickStart Guide.
I followed the official WordPress Upgrading Instructions. (I am not an idiot.) I also followed the instructions I included in the first article of this series, “Upgrading WordPress to 2.1: Dealing with Plugin Compatibility,” to make sure my plugins were compatible and to get updates of plugins that were installed.
The upgrade went pretty smoothly. I updated 3 of the 10 plugins Miraz and I use on the site and inserted some if-then logic to disable plugin-specific code when a plugin isn’t available. Then I backed everything up, turned all the plugins off, and started the upgrade.
When the digital dust settled and I was able to view the site again, I was pleasantly surprised. Most of the site looked just fine. I enabled the plugins one-by-one and tested the site again after each one. I discovered that Rate My Stuff and CG-Feedread, which weren’t listed as plugins that worked with WordPress 2.1 did indeed work. (I added them to the list in the Codex.) The Search Pages plugin didn’t cause an error message, but didn’t seem to work, either. In addition, there appeared to be a slight formatting problem with the form generated by WP-ContactForm; but it may have been like that before the upgrade. And, of course, WP-Cron is no longer necessary, since periodic backup is now built into WordPress 2.1 with WordPress Database Backup 2.0.
There was, however, a relatively serious problem with the links list. This has to do with the way WordPress 2.1 handles link categories and changes made to the tag we used to display them:
In WordPress 2.1 links are now called bookmarks. And link categories have been merged with post categories, which are just called categories. Sound familiar? It should. That’s the way links and categories have been handled on the WordPress.com site for close to a year now. (Consult pages 69-73 in our book.)
To make this work, the upgrade process renumbers all of the link categories (unless they have the same name as a post category, I suppose). This isn’t a huge deal unless you use tags that refer to link categories by their numbers — as Miraz and I did. As a result, the
< ?php wp_get_links(3); ?> tag we had in the sidebar (for example) didn’t display anything because there weren’t any links in post category 3. This problem existed for all of the links we listed by category in the sidebar. All that displayed were the
h2 level headings for each group of links.
When I discovered the problem, I substituted the new category numbers into the tags. The result was a list of link names and descriptions, formatted without bullets (see illustration). This isn’t the way it appeared before the upgrade.
At first, I thought the
wp_get_links tag had been changed. But that wasn’t the case. Instead, WordPress 2.1 changed the information it recorded for links. In previous versions, it enabled you to include “before” and “after” attributes that were used, by default, to display links in a list. Those fields were gone, so “before” and “after” attributes had to be manually included with the
It turns out, I needed to provide some additional attributes. Here’s what the
wp_get_links tag needed to look like:
< ?php wp_get_links('category=9&show_description=0&before=
The resulting list looked like it always did (see image). I modified all of the tags as necessary, saved the modified template file, and was done.
In researching this problem, I looked into the Codex’s list of link tags. I noticed that there are some new link tags that will only work in WordPress 2.1. Unfortunately, the Codex entries for these tags were not complete when I consulted the Codex today. The one that appeared complete (but is still being edited) is
wp_list_bookmarks, which I thought would meet my needs. Unfortunately, I was unable to get the desired results with this tag, even when using the attributes discussed in the Codex. I’m not sure if the information is incorrect or incomplete or I just made some kind of mistake I can’t figure out.
In any case, be aware of changes to the way links are displayed on your site when you upgrade to WordPress 2.1.
And stay tuned; I’ll be sharing more tips about completing the upgrade as I continue to upgrade my six WordPress-based sites.