Quite some time ago, I launched the first version of the Blog Topics Plugin. I hadn’t updated it since way back in September of 2008. Originally, it was relying on URLs with query parameters for all the portal aspects of the plugin. For instance, if you wanted to link to a page of blogs from one topic, you’d have a URL like, “index.php?topic=1.” It worked, but was less than elegant. So, for our own work, we modified the plugin to use permalinks, and added some additional features. The publicly released version was treated like the forgotten stepchild. Lots of people have downloaded it and I think lots of people have used it. It continued to work, but it got no love.
Not anymore. I’ve now completed a long overdue overhaul of the plugin. Now, all the portal aspects can be switched on and off in the widgets. And, I’ve provided some sample theme code to show how to use the permalinks (which are written into the theme, not the plugin).
So, let’s run through how the plugin works now.
Where to put the files
The plugin comes with a bunch of files. So, let’s break down where they go.
- wp-content/mu-plugins
This is where the main part of the plugin should be installed. You need to install the cets_blogtopics.php and the cets_blog_topics folder (and the files within) in the mu-plugins directory. The cets_blogtopics.php file should be in the root of the mu-plugins directory or the plugin will not run.
- wp-content/plugins
All of the widgets should be installed in the plugins directory and only enabled on the blogs on which you want to use them. None of these are required widgets, and you should only install the ones you wish to actually use. (See below for an explanation of each of these.) The following are widget files:
- cets_bt_featured_topic_with_posts_widget.php
- cets_bt_related_blogs_widget.php
- cets_bt_related_posts_widget.php
- cets_bt_topicname_widget.php
- cets_bt_topics_with_posts_widget.php
- wp-content/themes
All of the code in the cets_blog_topics_sampletheme directory is, as the name suggests, sample theme code. To test it and play with it, install it in the wp-content/themes directory. You will need to enable it via Site Admin -> Themes, and then you will have to activate it on a selected test blog. You should install this AFTER installing the plugin and widgets. The theme utilizes the cets_bt_topics_with_posts widget and the cets_bt_featured_topics_with posts widget.
Now What?
Now you have the files where they belong, now what?
For a fresh install, the plugin will create a couple of tables in the database. The names will most likely be wp_blogs_cets_topic and wp_blogs_cets_topic_relationship. (The first part may be different if you’ve customized your database prefix in your WPMU install.) In previous versions, the table names used plural syntax. Plural syntax of table names is just one of my many pet peeves about the database design in WPMU (don’t get me started on that). There are a few new fields as well – description, slug, thumbnail, banner, and featured are all new in the topic table. (Thumbnail and banner aren’t actually in use yet.) If you already had the plugin installed, the upgrade script will attempt to alter the tables for you automatically.
By default, you must have at least one topic. The plugin installs with the default topic of “uncategorized.” If you’d like it to install with multiple topics, you can alter the code of the cets_blogtopics.php file on line 120 to add additional items to the array of default topics. Don’t worry – there’s a visual way to add and edit topics once the plugin is installed as well.
The Site Admin Features
Most of the site admin features of the plugin are found under Site Admin -> Blog Topics Management. The screen has three parts:
The first section is where site admins can add and edit topics, slugs, and descriptions. Slugs are what will be used for the portal permalinks. So, make sure that they contain no spaces, are short, and are human readable. The slugs are also used in the sample theme to create menu options. Think carefully about your slugs. The description is also used in the sample theme code, as well as in the blog topic name widget. Here’s what the administration screen looks like for this part:

Administrative View of Adding and Editing Blog Topics
The second part of the administrative interface allows you to set a featured topic. Again, the featured topic is utilized in the sample theme code and in the featured topic widget. A featured topic is not required to run the plugin, but is required for the featured topic widget.

Administrative View of Setting a Featured Topic or Uninstalling
The final part of the site admin interface is the uninstall feature. Clicking the uninstall link will remove the database and clean up the site options associated with the plugin. Manual deletion of files is still required.
There’s one other place where site admins can manage things. On Site Admin -> Blogs -> Edit, you can set the blog topic on a specific blog, and choose whether or not a blog is included in the aggregation bits (the widget & portal pieces). You’ll find these options in the Misc Blog Actions section of the blog editing page, and they look like so:

Blog Editing Features for Site Admins
Blog Admin Options
That pretty much covers what the site admins can do to administer the plugin itself. What about the blog admins? When a user first creates a new blog, she will find a new option on the sign up page, just under the Privacy section:

User View of Sign Up Option
It defaults to selecting the first item in the list, which is in alphabetical order. We’ve noticed that some people don’t really pay much attention here, and will just sign up with the default option, no matter what it is. Fortunately, there’s an easy way for blog admins to change the selected topic. In Settings -> Blog Topic, blog admins can change the topic of their blog and decide whether or not their blog should be included in the aggregation bits of the plugin.

Blog Admin View of Setting Blog Topic
The Widgets
Okay, so we have the plugin installed, and we’ve categorized our blogs. Now what? What do we DO with that information. Here come the widgets. There are five of them. Some are incredibly simple – and could be used on any blog in the network. Others are really meant to be a part of your root blog, acting as portal pieces. Let’s start with the simplest one first.
Blog Topics Name
The blog topics name widget (cets_bt_topicname_widget.php) displays the name and, optionally, the description of the topic. Like most of the widgets, it can also create a link to a portal page. In this case, if you follow the code in the sample theme, the portal page would display a list of all the other blogs that fall under the same topic. Here’s how it looks from the backend:

Back end view of blog topics name widget.
And, here’s how it displays data on the front end. If you elect to include the portal link, the topic name becomes the link:

Pretty simple, right? Yah, we don’t actually use this one, either. But, it was written, so I thought someone might want it.
Related Blogs Widget
The related blogs widget is a bit more interesting. It lists the top N blogs that are categorized under the same topic. This one doesn’t have any portal parts, so it’s very safe to use, even if you’re not implementing any of the portal pieces. The list will simply link to each of the blogs directly. Here’s how it looks on the back end:

Back end view of the related blogs widget
And here’s how it looks from the front end. (This example doesn’t list many blogs, since I was pulling these screen shots from my development environment. Clearly, you’d have a longer bulleted list in a production environment.)

Front end view of related blogs widget
Related Posts Widget
Here’s where things start to get fun. This widget will pull the N most recent posts from all the blogs that share the same topic affiliation. This widget can again include portal links. If you follow the sample theme code, the portal links would be to a page that lists more recent posts from that topic and a page that lists all sites in that topic. These are optional, of course. Here’s the back end view:

Back end view of related posts widget
And, here’s how it displays on the front end:

Front end view of related posts widget
Featured Topic With Posts Widget
The last two widgets are the workhorse widgets for the sample theme code. The first, the featured topic with posts widget, is fairly similar to the related posts widget, except for that instead of pulling the posts from the same topic as the current blog, it pulls the posts from whichever topic the site admin has set as featured. Again, you can determine how many posts to include and whether or not to include the portal links. Here’s what it looks like from the back end:

Back end view of featured topic with posts widget
And, here’s what it looks like on the front end:
Topics with Posts Widget
Finally, the last widget allows you to pull all the topics and a selected number of posts from each topic. Use this one carefully – it’s fairly resource intensive. We’ve done some experimenting with different ways to cache this puppy. But, haven’t figured out what the best approach is yet. You can also exclude certain topics. We use this widget in conjunction with the featured topic widget to show the featured topic’s posts in a separate area. And, as always, the portal links are optional. Here’s how it looks on the back end:

Back end view of topics with posts widget
And, here’s how it looks from the front end. That image in there? That’s part of the sample theme code. We’ll talk about that in a minute.

Front end view of topics with posts widget
The Sample Theme
Whew – are you still with me? One last section – the sample theme. First I have to ask you a favor. Don’t just install this sample theme and run with it, okay? I tried to dumb it down enough so as to not be too tempting. It’s pretty bare bones. It’s really meant as a guide – a way to help you understand how to make all this portal stuff work. Okay, that said, how does it work? Where’s the magic?
Most of the magic is in the rewrites.php file. Here’s where you’ll find the code to tell wordpress to take any URL that includes topic= or sitelist= and turn into a URL that looks like this:
topic/mytopic/
or this:
sites/mytopic/
And, furthormore, this code lets wordpress know to send those URLS to topic.php and sites.php, respectively. We get this code to run by including it in the functions.php file of the theme. The code for that is way down at the bottom of the rewrites.php file and looks like this:
//include the rewrites
include_once dirname(__FILE__) . '/rewrites.php';
Of course, you also need the topic.php and the sites.php files as well. These are the files that display all the recent posts from a topic or all the sites from a topic. I’ve tried to add commenting in each of these files so you know what’s going on there. Note that, as written, these files also make a custom feed link. If you want to use that, you’ll need to also use the topicfeed.php file.
The home page is really just a widgetized template that utilizes the Topics with Posts widget and the Featured Topic with Posts widget. The widgets are called in home.php using the nifty the_widget() function. But, they could also be set via the back end widget tools.
My cohort in crime, and designer/css guru, Kevin Graeme, has added some nifty css tricks to the sample theme. Remember that image in one of the widgets up above? Well, that’s just a little css trick based on the slug of the topic. If you check out style.css right about line 281, you’ll see a comment that tells you what to do if you want to implement that trick. You’ll need to create a style for each of your topics. Easy peasy.
Okay, I think that’s it. Hopefully, this will help you figure out how to use all this stuff.
Of course, you probably want to know where to get all this stuff, eh? It’s here: http://wordpress.org/extend/plugins/blog-topics/
Enjoy!