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:



65 thoughts on “Blog Topics Plugin – Take Two

  1. So, excuse my ignorance/naivety, but I’m wondering if I should copy the rewrite.php, sites.php, and topic.php files into my existing theme, or do they need to be modified? Thanks for your work on this, this is exactly what I’ve been looking for, you hit the nail on the head!

    1. You can try copying those files directly into your existing theme. They’ll probably need some tweaking to work with whatever css you’re using your theme, though. You’ll also need to do an include of the rewrites.php file in your existing theme’s functions.php file. You should at least get the functionality, but may need to work on the look/feel aspects.

      And, you’re welcome – I hope it works for you!

      1. Thanks, for replying so quick! I’m going to google the include thing, is that a standard PHP function?

      2. Yah – and it’s included in the content of the post about half-way up:

        //include the rewrites include_once dirname(__FILE__) . ‘/rewrites.php’;

  2. I can’t get the “include portal links” to show up in the widgets on the test theme or my own theme. I modified my functions.php, added the other files, and the widgets show up on my home page. However, when I click the links at the bottom (for the blog topics with posts widget), I get redirected to a page which doesn’t exist. Do I need to create a special page template or something? I can’t figure it out from looking at the back end of the sample theme.

    1. I’m not sure what you’re asking. The blog topics plugin doesn’t change the URL structure of your WPMU install. It adds a redirect for /sites/ to show all the sites within your blog that are applicable to a topic. So the structure is not

      If you installed WPMU in a sites subdirectory, there will be a conflict with this plugin. I haven’t done any testing on dealing with that sort of thing.

      1. It might be possibly, but I wouldn’t recommend it. You’re liable to get collisions with actual blog names and topic names, unless you put all topic names in the banned blog names list. And, you’d have to register rewrites for every one of the topic names. So, in other words, you may be able to do it, but it’s not something I’m going to implement in the plugin. Sorry.

  3. SOS… I updated to the latest version and now I am trying to figure out how to replicate what I had created before. I have a couple of (I hope) simple questions, the first of which is below:

    I publish the complete list of blog topics using this:


    Previously, the resulting links to the list of each topic’s blogs were powered by a file (cets_blog_topics_list.php) installed at the root containing:

    Now that there a slugs and whatnot, what would replace this code and the location of the file that was previously at the root?

  4. SOS… I updated to the latest version and now I am trying to figure out how to replicate what I had created before. I have a couple of (I hope) simple questions, the first of which is below:

    I publish the complete list of blog topics using this:

    Previously, the resulting links to the list of each topic’s blogs were powered by a file (cets_blog_topics_list.php) installed at the root containing:

    Now that there a slugs and whatnot, what would replace this code and the location of the file that was previously at the root?

  5. SOS… I updated to the latest version and now I am trying to figure out how to replicate what I had created before. I have a couple of (I hope) simple questions, the first of which is below:

    I publish the complete list of blog topics using this in my own site list template:
    cets_get_topics_html($used=true, $show_count=true)
    Previously, the resulting links to the list of each topic’s blogs were powered by a file (cets_blog_topics_list.php) installed at the root containing:

    define('WP_USE_THEMES', true);
    require( 'wp-config.php' );

    Now that there a slugs and whatnot, what would replace this code and the location of the file that was previously at the root?

  6. Hi, I got the the problem I posted above sorted out. One lingering question: When I use $orderby = ‘alpha’ I get a list sorted by the path, not the name of the blog.

    It seems that line 309 might have something to do with this:
    $orders = array('last_updated' => 'b.last_updated desc', 'alpha' => 'b.path', 'added' => 'b.registered desc' );
    so I tried:
    $orders = array('last_updated' => 'b.last_updated desc', 'alpha' => 'b.blogname', 'added' => 'b.registered desc' );
    to no effect. How can I order alpha by blogname?

    1. Hi, the blogname isn’t stored in the blogs table. It’s one of the downfalls of the system. The only way to actually sort by blog name is to build an array and then use php array sorting to sort by the name. I haven’t implemented that in this plugin.

      1. Thanks for your quick reply! If you could give me even the slightest clue as to what that would look like, syntax-wise, I could probably figure it out from there…?

      2. ok… it looks like you already did that in
        function get_blog_details_from_topic_id

        if ($orderby == 'alpha'){
        foreach ($blogs as $key => $row) {
        $domain[$key] = $row['domain'];
        $path[$key] = $row['path'];
        $blogname[$key] = $row['blogname'];
        $id[$key] = $row['id'];
        array_multisort($blogname, SORT_ASC, $blogs);

        I added a string to lower here to get it to integrate lowercase blog titles:
        $blogname[$key] = strtolower($row['blogname']);

        done! I think I can furhter create functions
        get_blog_details_from_topic_id_html and
        and I’ll be good to go. Thanks!

      3. Thanks for digging that up. I thought it was in there somewhere and just hadn’t had a chance to go spelunking for it yet. The boss has me working on other projects these days and WP is taking a backseat.

  7. One more from the trenches: in site admin, under Settings>Blog Topic, when I change a blog’s topic and Update Options, it does in fact change topics, but that change is not reflected in the pulldown menu; the menu flips back to the old topic. Any way to make the visible menu option synch with the assigned topic?

    1. ‘k, I fixed it:

      function get_topics_select($id = 0)
      change this line:
      if ($id == $topic->id)
      to this:
      if ($blog_topic == $topic->id)

      1. Hey raskull,

        do you by any chance have modified this plugin to display list of blogs sorted by topics? Something similar to what cets_blog_topics_list.php was before? And are you willing to share it? Please reply.

  8. I believe this plugin is a must for multisites!
    I have internationalized cets_blogtopics.php (widgets and theme not yet done)
    let me know If you are interested so that I can send to you modified file and pot file, also po and mo file for french.

    1. Thanks. Sure, send them to me. I’ve really not done anything with internationalization. But, I’m happy to include the files.

      Note, I just posted a minor change for 3.0 (just to the path for the uninstall script) in version 1.1.

  9. Hi DeannaS,
    I must be lost.
    Could you point me to the direction to download
    Blog Topics 1.1
    The only link I find is to but that says and is Blog Topics 1.0 and without any .pot files (I’ve downloaded and tried it).
    Thank you.

    1. The latest version of the plugin is the one on For some reason, it’s not picking up the right version number. (It says 1.1 in code.) I haven’t incorporated the pot files yet. They were sent to me be someone else that did the internationalization, but I just haven’t had a chance to merge his code with mine.

      1. Looked again and you are right . It says 1.1 in code.
        Thanx. It just gives this very annoying message to upgrade. ahhh
        Thanx again

  10. Is there any possibility to get this plugin extended to allow for sub-categories?


    having a bit of difficulty getting it to work properly with the multi-network plugin

    seems that sites on other ‘networks’ are also picking up the topics set for the primary network.

    If you had not seen the plugin before, it’s really a great piece of code from JJJ (buddypress dev)

    Either way, thank you for such a great plugin.

  11. I’m not really sure how we are supposed to get support for this plug in so I am posting my issues here. I am using MultiSite with WP v.3.01. I was recommended to try your plugin to categorize my sites. I have installed your plugin following the instructions provided. However, I am having 2 issue.

    1. I can set up the topics just fine. Although, I am not able to change the default topic that is automatically assigned when I set up a site. When I change the topic it says ‘Options Saved’ but my selection in the dropdown box reverts back to the original topic. Nothing changes.

    2. In the instructions it says, ‘Blog owners can select a topic for their blog at creation time’. I do not get this option when setting up a new site.

    I don’t know if these issues are related or not but this plug in is not usable functioning the way it is for me right now.

    Thanks or your help.

    1. I just realized that when your goto ‘Blog Topic’ under settings that it simply displays the top most topic in the dropdown box. If you change the topic and click ‘Update Options’ it says ‘Options Saved’ and reverts back to the top most topic in the dropdown box.

      1. Hei Bill, i just wanna share.

        In file cets_blogtopics.php, around line 751, find this:


        change to:


        hope this help.

    1. I’m out of town right now and don’t have ready access to the code. I’m not even sure exactly which widget or function you’re referring to. Feel free to open the code. If you know what widget you’re referring to, it should be fairly easy to find the piece in the code and modify it yourself.

      1. thanks lot for you replay and your great plugin,

        i am using file home.php in cets_blog_topics_sampletheme with php-exec plugin to display the out put of this plug-in in my home page as a post , but i get

        *post name (url)
        *very short words from the post (about 5 words )
        * blog name

        what i need to show more words from the post ,

        i checked most of code but i could find the part of code doing that

        anther issue , that when i press on more posts or all sites to this topic it give me no thing

        please help me with this issue

        Thanks alot

  12. Have the plugin installed according the above instructions. I am running WP 3.0.1 and BuddyPress 1.2.6.

    The plugin is not offering the category selection drop-down box during sign up. When one selects to add a blog, the option to select a category is not available. Any suggestions?

    Alan Smith

  13. Hi, and first of all, thanks for the plugin! I’m having a bit of trouble, though, and have posted on the forums with no answer. Hoping I can get some help here 🙂

    I have the plugin installed correctly, and topics created. I have my main site’s topic set to “Miscellaneous” and private on the “blog topic” screen, and a child blog’s topic set to “clothing” and public on it’s respective blog topic screen. I updated my theme’s functions.php to include the rewrite file, and uploaded that, along with topic.php and sites.php to my current theme.

    My issue is that when I visit, it’s displaying posts from my main site as well as posts from the child site that is assigned to the “Clothing” category. Also, clicking the “previous posts” link is displaying the exact same posts. I ‘m pretty sure that it’s trying to use one of my own template files, and that’s where the problem probably lies, but I can’t figure out which one!

    1. Yah, sorry – I’m not really doing much WordPress stuff anymore (sadly).

      But, you’re right that it’s not pulling in your template. Are you sure you are actually calling the rewrites code? It should be the last line of your functions.php in theme:

      //include the rewrites
      include_once dirname(__FILE__) . '/rewrites.php';

      And, then you need to be sure to also have the files sites.php and topic.php in your theme as well. Those are the files that actually get included via the rewrites and which will actually display your content.

      A default sites page (from the sample theme) would look something like this:

      1. Yep, I definitely have sites.php and topic.php in my theme, pulled directly from the sample theme folder. I put the rewrite include right before the closing “?>” in my functions.php file, because I get all sorts of icky errors if I make it the absolute last line.

        After all of that, here’s this:

        There’s supposed to be one site listed under that topic, TNT: TrashN2Tees”


      2. Yes, it’s supposed to be before the ?> in your functions.php

        One thing you can try is just putting an echo tag in either rewrites.php or the topic.php to see if they’re even getting called correctly.

      3. Sorry – I really can’t spend a bunch of time debugging this for you. You can try echoing further down in topic.php to see if the code is being called.

      4. Actually, one more question…am I supposed to be creating pages in my WP backend and using topic.php and sites.php as the templates for them?

      5. Sorry, I’ll stop flooding your inbox, just wanted to let you know that I think I figured out a way around my issue! I just took most of what was on sites.php and c/p’d it into home.php, uploaded, and it seems to be working! I still need to style everything, but that’s the easy part IMO, lol!

        Thanks again for the plugin!

  14. Also, is there a way to list all of my topics, have a count of how many sites are in that category beside each topic name, and have the topic names link to a page that lists the titles of all of the sites belonging to that topic?

    1. There are functions in the plugin that would help you do those things, but I don’t have the sample code to give you. Read through the functions and I think you’ll be able to figure it out.

  15. Hi

    Your plugin is awesome however,

    I followed your installation guide to the tee.

    Either from site admin > sites > edit blog > blog topic options

    OR from

    Blog’s wp-admin > settings > blog topic

    It has selected in the drop down box featured topic.

    When I change it to another topic and hit save it always reverts back to the featured topic.

    Is this a bug ? should I reinstall ?

    Cheers for the help,


  16. Ok, it isnt the featured topic.

    It reverts back to ID 2.

    I have uninstalled reinstalled.

    Any ideas why it’s doing this?



  17. What is the substitute for cets_blog_topics_list.php in latest version of this plugin? If there isn’t any, can you advise on how to acheive same result? Thanks.

  18. It’s not really a plugin that’s going to work well installing via wordpress automatically. There’s a sample theme included with the plugin that shows how to implement it. Download it and look at the sample theme and read the readme stuff.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s