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.
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.
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:
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 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:
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.
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 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:
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.
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:
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:
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.)
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:
And, here’s how it displays on the front end:
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:
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:
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.
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:
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.
Most of these are minor updates – mostly just testing the plugins and making sure they work on 188.8.131.52. 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.
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.
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.
Today, I had a request for my Simple Dashboard plugin to add the ability to change the contextual help on the dashboard. I had never looked into doing something like that & I wasn’t sure if there were any hooks for it. But, this is exactly what I love about WordPress. While I didn’t end up using a “hook” per se, it was super super simple to modify the the plugin to allow site admins to add their own contextual help for the dashboard. It took all of 10 minutes.
I’ve had a couple of requests to update my New Blog Defaults plugin for WPMU. I finally got around to doing it. Here are the new features:
The ability to close comments on the first post and page.
The plugin has long had the ability to set the blog’s default comment status. But, because the about page and the hello world post are created before the New Blog Defaults code is run, those two items weren’t affected. I could have just checked to see if you have the default status set as closed, then those items should have a status that matches. But, ultimately, I like to make my plugins as flexible as possible. So, now you can control each of those settings yourself.
Adding User to Other Blogs
This request came from the BBPress world. If you have BBPress installed on a specific blog, you need everyone to be on that blog as a subscriber. While this plugin won’t go through your existing user list and add them to a blog, and it won’t add people that just sign up without creating a blog, it will add users that both sign up and create a blog to the blog or blogs of your choice. You can set the role you’d like them to have as well. Personally, I think this is probably better handled in a separate plugin that fires on user add – not on blog creation. But, it’s not difficult to add it here. And, it might be useful for those BuddyPress installs where people are limited to a single blog and always get a blog on signup.
Best practice for upgrading plugins has always been to first deactivate the plugin, upgrade, and then reactivate the plugin. For site admins of WPMU sites, this is a laborious process, partly because you’d need to go through each blog to determine whether or not the plugin has been activated. This plugin provides a snapshot view of which blogs are using any particular plugin.
For sites that are using Plugin Commander to manage plugins, additional columns for the Plugin Commander settings of Auto Activate and User Controlled are included.
For sites that are using Plugin Manager, additional columns for the Plugin Manager settings of Auto Activate, User Controlled and Supporter Controlled are included.
Data is regenerated on viewing the plugin stats page if the data is more than one hour old. Data can be regenerated anytime via the “Regenerate” button (as seen in the above screen shot).
WPMU has two ways to activate themes – either sitewide, or on a blog-by-blog basis. But, there’s no convenient way built-in to know which themes are actually being used, or by whom. This plugin addresses that issue by creating a “Theme Usage Info” sub-menu of the Site Admin menu. Included on the page are two tables of data – one of themes currently being used, and one of themes not currently being used. The currently used themes table provides information on how many blogs are using the theme, which blogs are using it, and whether or not the theme is currently activated site-wide. The table of unused themes provides information on whether the theme is currently activated sitewide.
In addition, site admins can choose to provide this information to their users via a toggle on the administration page.
If enabled, users will be able to view data on theme usage in Appearance -> themes for every theme except the currently activated theme. A single line of text is added just before the activate link indicating how many blogs are currently using the theme:
When clicked, a scrolling list of themes is displayed in a thickbox: