Blog Topics Plugin – Take Two

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.

  1. 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.
  2. 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
  3. 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

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 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

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

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.

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:
Front end view of topic name widget.

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

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

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

Back end view of related posts widget

And, here’s how it displays on the front end:

Front end view of related posts widget

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

Back end view of featured topic with posts widget

And, here’s what it looks like on the front end:

Front end view of featured topic with posts widgetFront end view of featured topic with posts widgetTopics 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

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

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:
or this:

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:



The Great Plugin Update

I’ve been spending the last little while updating plugins for WP/WPMU  All the plugins can be found here:

Most of these are minor updates – mostly just testing the plugins and making sure they work on There are a few significant changes:

New Blog Defaults

There was a timezone bug in this one. I think that’s fixed now. I also added support for the new settings in 2.9, including the auto-embed URLs and embed sizes and added the xmlrpc options (which aren’t new, I’d just never put them in before).

Embed RSS & Embed Gmaps

Have you read this post about not, under any circumstances, calling wp-load in a plugin? Yah, well, um, guilty. I will say that the use of wp-load was something that I stole from someone else. But, I suppose that’s not a good excuse, is it. Anyway, I’ve updated these two plugins so that they no longer do that. In so doing, I found a bug with CSS loading in Embed RSS. That’s fixed as well.  The UI has changed a bit. Instead of using the tinymce window loader, I’m now using a hidden div a’la Viper’s Video Quicktags. In fact, major props go out to him as much of the code is stolen right from that plugin. Yay open source, right? Anyway, here’s what it looks like now.

UI for Embed RSS

The new pop up window for the Embed RSS button.

WPMU Theme Info

I added the show/hide code like the Plugin Stats plugin. Other than that, no major changes here.

WPMU Default User Role

I added the  blog id number for all blogs identified as “/”  in the drop down list of blogs for the site administrator.  This is primarily only useful for domain mapped blogs.

Blog Topics

This one is a total rewrite. Look for a separate blog post on this coming soon.

All the rest simply got tested and their readme files tweaked.