Bonetree Blog

Tutorial: A random title plugin for Wordpress

A couple of people have noticed the random titles displayed under my blog name up in the header (refresh the page to see what I mean). The actual reason I did that was simply because I couldn’t come up with a reasonable title to use by default. So my indecision led me to whip up a quick little plugin that would randomly pick a quote from a text file I created.

To be honest, this could have been made a bit more robust by adding a WP admin options page allowing you to add/remove quotes but I didn’t want to spend too much time on it, and this way might be a bit better as a tutorial for someone just starting to hack Wordpress. By the way, I’m assuming you have some basic PHP knowledge in this tutorial. Let’s begin…

Creating a plugin for Wordpress is actually much easier than most people think, and to keep it simple, it all starts with picking a name. Let’s call our plugin Random Title Quotes (I never said I was original). Now let’s get Wordpress to notice our new plugin. Any php file that you drop in the wp-content/plugins/ directory will be picked up by Wordpress as a plugin. To organize things a little better make a directory under that and call it random-title-quotes. This is where we’ll be putting all of our PHP files.

This is actually a very simple plugin so we’ll just need one PHP file. Create a file called random-title-quotes.php in the directory you just created. Now open this file up in your favourite text editor (I like Ultraedit for Windows). First thing’s first, we need to add a proper header so that Wordpress knows what to do with our plugin.

Here’s an example of mine:

Plugin Name: Random Title Quotes
Plugin URI: http://blog.bonetree.net
Description: This plugin displays a random quote as your blog title line.
Version: 1.0
Author: Daniel Torreblanca
Author URI: http://blog.bonetree.net

Copyright 2008 Daniel Torreblanca (email : …)

To be thorough, you might also want to include some licensing text. Here’s an example:

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

These two snippets should appear commented right at the top of your PHP script, like this:

1
2
3
4

<?php
/*
    Header and licensing comments go here...
*/

We’ll also need a plain text file called quotes.txt in the same directory. That file should contain one quote per line and will be read by our plugin. Make up your own quotes or grab some online.

Now that all the boring stuff is done, save that file and load up your Wordpress Admin > Plugins page. You should see an entry for your new plugin. You can try activating it if you want, but it won’t do anything at this point. Now, there are probably several ways to go about writing this plugin, but for this example I’ll be using a WP filter hook. Filters are functions which you register with Wordpress to filter certain content, such as posts, comments, excerpts or in our case, the blog title. Wordpress provides “hooks” which allow you to filter any of these items.

Wordpress has a function called get_option() which is used all over the place to get the value of options from the options table in your Wordpress database. What we’re going to do is register a filter that will be called whenever get_option(’blogdescription’) is called. In it we’ll essentially throw away the title returned from the database and replace it with a random quote which we’ll read from quotes.txt.

This is what our code will look like now:

1
2
3
4
5
6
7
8
9
10
11

define('QUOTES_FILE', ABSPATH.PLUGINDIR.'/random-title-quotes/quotes.txt');
 
function rtq_getquote($title)
{
    $quotes = @file(QUOTES_FILE);
    if( $quotes ) {
    	$title = $quotes[array_rand($quotes)];
    }
 
    return $title;
}

I like to use a prefix for all my plugin functions to reduce the likelihood of any conflicts. In this case I’ve chosen rtq_. The $title parameter to our function contains the value returned by get_option(’blogdescription’). If we encounter an error while opening the quotes file, our function will just return what was in the database. Otherwise, we’ll return a random quote.

And that’s it! You might be asking yourself, “Is it REALLY that easy!?”. Well, no, it’s not. But it’s not a whole lot more difficult. Now that we have that function written all we have to do is tell Wordpress to use it when get_option(’blogdescription’) is called. To do that we use the add_filter() function:

add_filter('option_blogdescription', 'rtq_getquote');

Stick that line at the bottom of your PHP file, outside of the rtq_getquote() function and that’s it. Now any time a template calls bloginfo(’description’) it’ll return a random quote from your quotes.txt file.

NOTE: This also has the side-effect of populating the “tagline” field on the WP Options > General tab with a random quote, so if you hit the “Update Options” button it’ll save that to your database, overwriting what you may have had previously.

For the lazy, here’s a zip containing all you need. Just drop it into your WP plugins directory, activate it and you should be good to go.

• Random Title Quotes Plugin

Posted in Tutorials |
Tags: php, plugin, wordpress |