Blog

In Part 1, we looked at planning out our plugin.
Part 2 was all about making the tables that would support it.
In Part 3 we began work on our admin panel.
Part 4 examined the benefits of using Object Orientated PHP which brings us to:  Part 5
The final part, where we look at using WordPress’ nifty ShortCode functions.

The Magic of ShortCodes

The first thing that we do is open up our main plugin file, which in this case is tabberlist-main.php. Then we need to create a function (using our !function_exists check first), which I’m going to call tabberlist_display() because, well, it’s all about displaying the TabberList.

if (!function_exists('tabberlist_display')) {
	function tabberlist_display($atts) {

	}
}

Now that I have the function name defined, I go ahead and add the action script that will trigger the function when the page is loaded.

if (!function_exists('tabberlist_display')) {
	function tabberlist_display($atts) {

	}
}
add_shortcode('tabber_list', 'tabberlist_display');

The add_shortcode() function is a built in WordPress function that will be triggered on every page and post load. The first argument defines the name of the shortcode (’tabber_list’) and the second is a the function that is triggered if the name is found (the function we just declared, ‘tabberlist_display’). Now, the user can add a tabberlist shortcode to any post or page – which looks like [tabber_list], in case you’ve never used or seen one – and then the ‘tabberlist_display() function will then run.

Yup, that easy. We’re done here now, so thanks for reading!

Making it Do Stuff

OK, so it doesn’t do, well, anything. At least not obviously. If you copy this as it stands into your plugin file, then add a [tabber_list] shortcode into a post or page and publish it, then the [tabber_list] shortcode should not appear on the post. This indicates that everything is working correctly.

Wordpress is finding the shortcode, removing it from the post and running the function. But you want to be extra sure that it works, right? So we add this to our function to make sure that it really is working:

if (!function_exists('tabberlist_display')) {
	function tabberlist_display($atts) {
		$return = "Hello, world";
		return $return;
	}
}
add_shortcode('tabber_list', 'tabberlist_display');

Note that line 4 is very important – if you don’t return anything, WordPress won’t display anything.

So now if you add a [tabber_list] shortcode to any post or page, it should be replaced with ‘Hello, world’. Awesome.

ShortCode Attributes

But it gets better. Every instance of a ShortCode can be given unique attributes so that it functions differently in different situations. In TabberList, for example, I wanted the user to be able to select which categories would be displayed at any given time.

Using the logic that, if they don’t specify any categories, show them all and then, otherwise, show the specified categories, we can create an attribute for our TabberList which I have imaginatively titled ‘cat’.

Going back to our code, you’ll notice that the function tabberlist_display($atts) has an argument already ($atts). These contain any attributes that are declared within the shortcode and are separated by a space (e.g. [tabber_list cat=1,2,5]).

To get hold of our attributes, we can use a default PHP function and a built in Wordpress function, like so:

if (!function_exists('tabberlist_display')) {
	function tabberlist_display($atts) {
		extract(shortcode_atts(array( 'cat' => ''), $atts));
		return $return;
	}
}
add_shortcode('tabber_list', 'tabberlist_display');

The shortcode_atts() function takes the arguments given in ‘$atts’ and, in this case, puts them into a named array (’cat’). We could put in a default value (e.g. ‘cat’ => ‘1′) but, as we want the function to display all of the categories if the user hasn’t specified, then we leave the default blank.

We then use the PHP function extract() to get hold of the values from the array that was created by the shortcode_atts() function. Now that we have the values, we can do the following:

if (!function_exists('tabberlist_display')) {
	function tabberlist_display($atts) {
		extract(shortcode_atts(array( 'cat' => ''), $atts));

		if ($cat == "") {
			// Display all of the categories
		} else {
			// Display the selected category
		}
		return $return;
	}
}
add_shortcode('tabber_list', 'tabberlist_display');

And there you have it. Thanks to WordPress’ awesome API, creating user friendly plugins is a piece of cake! What I’ve explored over the past few weeks is really only the very beginning of what’s possible with this incredibly extensible and easy-to-use platform and I hope that I’ve inspired you to explore plugin development much more deeply.

If you’ve enjoyed this introduction on creating WordPress Plugins, please consider subscribing to my RSS feed or to my email list.

In Part 1, we looked at planning out our plugin.
Part 2 was all about making the tables that would support it.
In Part 3 we began work on our admin panel.
Today, we look at creating a class to help organise our code better.

Including The Class

I’m going to keep all of my class declarations in a separate file. This file will need to be included in ‘tabberlist-main.php’, so I add the following lines just under the commented metadata and license information. While I’m at it, I may as well go ahead and create a new instance of this class.

include('classes/tabberlist-class.php');
$tabberlist = new tabberlistclass;

That’s all that needs to be done here. This instance should now be available to us through the rest of the program. Or it would be, if the class actually existed yet. Better go and create it.

I open up a new text file and save it as ‘tabberlist-class.php’. I like to keep my code ultra-organised, so it gets its own folder (’classes’) too. Overkill? Maybe, but who knows what features I’ll want to add later.

In this new file, I start by making sure that this class only gets declared once (in the same way I did for the functions in ‘tabberlist-main.php’).

<?php
if ( !class_exists('tabberlistclass') ) {
	class tabberlistclass {

	}
}
?>

We declare the class using the ‘class’ syntax. Notice that there are no brackets after ‘tabberlistclass’.

Class Terminology

Classes don’t have variables and functions. They have attributes and methods. For our purposes, an attribute is basically a variable and a method is basically a function.

They have different names because of the way object orientated programming works. A class is an object – a discrete ‘thing’, like, for example, a ball. This object has attributes in the same way as a ball has a size and a shape. It also has methods, which can be thought of like verbs – in this case, our ball can bounce or roll.

An ‘instance’ (which we declared above) is a copy of our ball. We can make as many copies as we like, and each of these copies can have attributes applied to them. We could have different coloured or different sized balls. However, they would all share the same methods – they would all be able to roll or bounce.

For this plugin, creating a class is probably unnecessary. However, it does help to keep everything organised and it also serves as a protection against function conflicts.

If I declare a method within my class and it happens to be called ‘testFunction()’, but there’s already a function that’s been declared elsewhere in my code called ‘testFunction()’, then no conflicts arise. A good naming convention should prevent conflicts anyway, but this is serves as an extra layer of protection.

Display Methods

In order to keep our admin display code clean, I put all of the dynamic functionality into methods within the ‘tabberlistclass’ and then call them through the instance.

So, I open up the ‘tabberlist-admin.php’ file and make it look like this:

<?php
global $tabberlist;
if (isset($_POST['tabberListSave'])) {
	$tabberlist->update();
}

?>
<div class="wrap">
	<div id='icon-tools' class='icon32'></div>
	<h2>TabberList Admin</h2>
	<p class='description'>Welcome to TabberList. Select a skin, and start entering makin' some lists!</p>
	<form name="form_development" method="post" action="<?php echo str_replace( '%7E', '~', $_SERVER['REQUEST_URI']); ?>" enctype="multipart/form-data">
	<?php $tabberlist->selectSkin(); ?>
	<?php $tabberlist->getTitle(); ?>
	<div id='tabberlistOuterTabs' class='tabberlistAdminTabs'>
		<ul>
			<li><a href='#categories'>Edit Categories</a></li>
			<li><a href='#list'>Edit Lists</a></li>
		</ul>
	</div>
	<div id='categories' class='clear tab'>
	<p class='description'>Use the field below to add a new category. To delete categories, check the boxes next to the categories you would like to delete and hit "Save Changes". To have a category's items not counted in the final total, uncheck the box in the "Counted" column.</p>

	<table class='form-table adminTabberTable'>
				<tr valign='top'>
					<th scope='row'><label for='newCat'>Add New Category</label></th>
					<td><input type='text' name='newCat' id='newCat' size='60' /></td>
				</tr>
			</table>
			<?php $tabberlist->tabberListDisplayCats(); ?>

	</div>
	<div id='list' class='clear tab'>
		<h3>Current Categories:</h3>
			<div id='tabberlistAdmin' class='tabberlistAdminTabs'>
				<?php $tabberlist->adminCatTabs(); ?>
				<?php $tabberlist->adminCatDivs(); ?>
			</div>
	</div>
			<p class="submit">
				<input type="submit" name="tabberListSave" id="tabberListSave" class='button-primary' value="Save Changes" />
			</p>

	</form>
</div>

The first thing we have to do is bring the $tabberlist instance into this file (remember, this file is being called from within a function in our ‘tabberlist-main.php’ file), which we do by using ‘global’. This gives us access to this instance and, therefore, each of the methods within the tabberlistclass.

I’m going to focus on one method which should give you an idea of how this all works:

<?php
global $tabberlist;
if (isset($_POST['tabberListSave'])) {
	$tabberlist->update();
}

?>

To call a method within a class, we use the following syntax: ‘$instance->method();’ (to call an attribute, we would use ‘$instance->attribute;’ – note the lack of parenthesis). So, in this case we are calling the ‘update()’ method within the $tabberlist instance.

Moving back into the ‘tabberlist-class.php’ file, we need to declare a method that will take care of all of the updating for us.

<?php
if ( !class_exists('tabberlistclass') ) {
	class tabberlistclass {

		function update() {
		}

	}
}
?>

Currently, this does nothing but it has the potential to do a whole lot. From within this method, I can call a whole bunch of other methods that perform all of the data processing. For example, I could have a method that adds all the new categories to the database. It would look like this:

<?php
if ( !class_exists('tabberlistclass') ) {
	class tabberlistclass {

		function update() {
			$this->dbAddCats();
		}

		function dbAddCats() {
			// Code to add categories to database
		}
	}
}
?>

Notice the use of the ‘$this’ syntax. This tells the program that the required method is within this class.

By using a class, I can keep all of my admin panel display code free from the data processing code. This can be very helpful for debugging – if something doesn’t look right, then I go to the ‘tabberlist-admin.php’ file and debug the display.

If, on the other hand, something isn’t behaving right, then I know to look within the ‘tabberlist-class.php’ file and find out what’s causing the error.

In the final part of this series, we’ll look at using the shorttags functions built into WordPress that allows the user to quickly and easily add our lists to their posts. Subscribe to my RSS feed to make sure you don’t miss it!

Just a quick one to let you know that TabberList is now available to download! Grab it from this page right here!

Exciting times!

In Part 1, I posted my Plugin Plan that Portrayed the Promise of the Program and then in Part 2 I got Technical and Tore into the TabberList Tables! Here in part 3, we finalise our forms and fill them with funky features!

Creating an Options Page

Getting some sexy admin panels going on in WordPress is a piece of cake. First, we need to tell WordPress that we want our own Admin panel and then we need to tell it where to get the info.

So, first thing I do is open up my ‘tabberlist-main.php’ file and I add the following:

if (!function_exists('tabberlist_actions') ) {
	function tabberlist_actions()
	{
		add_options_page("TabberList", "TabberList", 1, "TabberList", "tabberlist_menu");
	}
}

Again, the ‘if (!function_exists…))’ part is all about preventing fatal errors – functions can only be declared once so what this is saying is: “If you’ve seen me before then I’m not the function you’re looking for. You can go about your business. Move along.”

The add_options_page() is a a built in WordPress function that lets it know that we want to have our own admin panel. As you can see, there are five parameters. Here they are in order:

• Page title – The text that will go between the <title> tags (in this case, “TabberList”)
• Menu title – The text that will actually appear in the WordPress admin panel (again, “Tabberlist”)
• Capability – What permissions the user needs to be able to access the panel (0 is subscriber, 10 is admin – I’m happy to let anyone except a subscriber edit this list, so I set it to 1)
• File/handle – If no function is declared, this needs to be the file that handles menu display. Otherwise, it’s just a unique identifier (we’re declaring a function, so this will just be a handle – “TabberList” is fine)
• Function – The function to run when the user clicks on the link in the admin panel (in this case, I’ve called it “tabberlist_menu”)

The sharp amongst you (that’s all of you, right? ) will notice that we now need to declare the “tabberlist_menu” function so that WordPress knows what to do when someone clicks our Options page in the admin panel (not to mention avoiding fatal errors from having non-existent functions).

So let’s declare it:

if (!function_exists('tabberlist_menu')) {
	function tabberlist_menu()
	{
		include 'tabberlist-admin.php';
	}
 }

Nothing really to see here, to be honest. I like to keep things clean and tidy, so I’m going to have my admin form in a separate file. All I need to do here is include that file, which I’ve called ‘tabberlist-admin.php’. Nice.

We’ll look into that file in more detail in just a bit but, before we do, we need to add an action that sets this whole crazy chain of events in motion.

add_action('admin_menu', 'tabberlist_actions');

This simply tells WordPress to execute the ‘tabberlist_actions’ function whenever the ‘admin_menu’ is loaded. That’s it! This is all you need to create your very own options page in the WordPress dashboard. Pretty easy, right? Here’s the code in full:

if (!function_exists('tabberlist_menu')) {
	function tabberlist_menu()
	{
		include 'tabberlist-admin.php';
	}
 }

if (!function_exists('tabberlist_actions') ) {
	function tabberlist_actions()
	{
		add_options_page("TabberList", "TabberList", 1, "TabberList", "tabberlist_menu");
	}
}
add_action('admin_menu', 'tabberlist_actions');

Of course, right now there’s nothing on that options page, which is less exciting. Let’s fix that now.

Creating the Options Form

We open up a new file and save it as ‘tabberlist-admin.php’.

Then we start creating our form. In order for everything to look right, we wrap our form in two divs with a special WordPress class, like so:

<div class="wrap">

</div>

I’m a big fan of consistent styling, so I tend to just borrow the standard WordPress styles and icons and such as much as possible so that my options page fits in nicely with the rest of the WordPress admin pages. I also throw in a brief introduction. Note that the “class=’description’” style is, again, a WordPress class.

<div class="wrap">
	<div id='icon-tools' class='icon32'></div>
	<h2>TabberList Admin</h2>
	<p class='description'>Welcome to TabberList. Select a skin, and start entering makin' some lists!</p>
</div>

For more information on styling your admin pages, check out the excellent summary at OneExtraPixel.com.

The next thing we need to do is open up the <form> tags. All of our form html elements must go in between these tags, or any of the data that users enter won’t get picked up on save.

<div class="wrap">
	<div id='icon-tools' class='icon32'></div>
	<h2>TabberList Admin</h2>
	<p class='description'>Welcome to TabberList. Select a skin, and start entering makin' some lists!</p>
	<form name="form_development" method="post" action="<?php echo str_replace( '%7E', '~', $_SERVER['REQUEST_URI']); ?>" >
			<p class="submit">
				<input type="submit" name="tabberListSave" id="tabberListSave" class='button-primary' value="Save Changes" />
			</p>	

	</form>
</div>

Important things to note:

• The form needs to have a method declared (either ‘post’ or ‘get’)
• The form needs an action, which should point to the script that is going to process it. In this case, we use $_SERVER['REQUEST_URI'] which is a PHP constant that passes the name of the current page (as it’s this page that will have the processing instructions in it -more on that in part 4)
• The <input> tag needs a type (in this case, it’s ’submit’) so the form knows what kind of input field it is
• The <input> tag needs a name so that it can be identified by the processing script
• The <input> tag needs a value, as (in this case) it will be what appears on the button itself. It will also be what is passed to the processing script when the form is submitted.

Again, in a fit of fitting-in, I have used a predefined WordPress class on this button (’button-primary’). This will change the button into the big blue WordPress button that we all know and love.

And there we have it!

OK, so not quite. If you go to this options page now, all you’ll see is simply a title and a Save Changes button. That’s because I’m going to declare a TabberList class to take care of some of our form creation and processing and we’ll do all of that in Part 4.

Remember to subscribe to my RSS feed so that you don’t miss an episode!

Part 2 of my originally-titled Wordpress Plugin Development series continues. Today: plugin setup and database structures.

Plugin Setup

The first thing we do is take care of the most important part of any development – the credits. People need to know who you are and, more importantly, where they can go and give you stuff. So tell them here.

Wordpress uses this commented data to display your information in the dashboard so it needs to be eye-catching and full of links, as mine is here. Hurrah!

<?php
/*
Plugin Name: TabberList
Plugin URI: http://www.line-in.co.uk
Description: A plugin to manage categorised lists with funky tabs for WordPress
Version: 0.1
Author: Simon Fairbairn
Author URI: http://www.line-in.co.uk
*/
/*
	Copyright 2009  Simon Fairbairn  (email : linein@simonfairbairn.com)

  ... License stuff (GNU, for those that care - full text available in plugin) ...
*/

Now that’s done, it can be safely released to the world knowing that everyone is going to be aware of exactly who made this marvellous magical mess.

Although, really, it should probably do a little bit more than advertise your site, so let’s go make it do stuff.

Doing Stuff

So, what did we want it to do? I often find that referring back to the Plugin Development Plan will remind me what it was I was supposed to be doing when I started.

And, look, it does!

Since I’ve decided that this plugin will require its own table in the WordPress database, I should go ahead and create the tables.

Note that this plugin needs its own table because of the vast amount of relational material it will hold when it’s being used by all the thousands of people that are going to love it. Yours might not.

If all you need to keep track of is one or two settings, then Wordpress comes built in with some amazingly simple functions that allow you to easily interact with the database and it’s probably easier and smarter to use them.

Read this, then make yer choice.

Install Functions

To make the tables, we need to have a script that does the following things:

1. Runs only when the plugin is first activated
2. checks to see if the tables exist in the database
3. If they don’t exist, creates them

So let’s do that.

First things first, make sure that this function hasn’t been previously declared. If it hasn’t go ahead and declare it. Then we call the global $wpdb instance (an instantiation of the WordPress database class and a useful layer of protection between the database and, well, me).

if (!function_exists('tabberlist_install')) {
	function tabberlist_install() {
		global $wpdb;
		$list_table_name = $wpdb->prefix . "tabberlist";
		$category_table_name = $wpdb->prefix . "tabberlistcat";

	}
}

register_activation_hook(__FILE__, 'tabberlist_install');

I grab the ‘prefix’ variable from the WordPress database class so my tables will be prefixed with the same thing as the rest of the WordPress tables (default: ‘wp_’). This is important in keeping databases organised.

Some hosts only allow 1 database per user so, potentially, a user with multiple, database-driven aspects to their sites (such as a WordPress install and a separate forum) will have a gajillion tables in their db. I’ve seen this and it’s not pretty so we add the WP prefix to our tables to keep all the WordPress tables bunched together.

Aside – To all hosts out there: let your users have as many databases as they want (or at least 5)! It’s not hard, it’s not expensive and there’s no good reason not to! Thanks, web developers and site admins everywhere.

Version Control

I want to throw in some version control (an idea wholly stolen from the WordPress Codex – that place has a ton of useful stuff and is worth reading every opportunity you get).

So, I create a variable that has the current version number and then I go and get the current version that is listed in the database. The two are compared and, if they do match, then it tells us that the user has installed this plugin before and that they are using the current version and it skips to the bottom.

If they don’t match, then we do a quick check to see if there are database tables installed that have the same name.

if (!function_exists('tabberlist_install')) {
	function tabberlist_install() {
		global $wpdb;
		$tabberlist_version = "0.7.0";
		$hasInstalled = get_option("tabberlist_version");
		$list_table_name = $wpdb->prefix . "tabberlist";
		$category_table_name = $wpdb->prefix . "tabberlistcat";
		if ($hasInstalled != $tabberlist_version) {
			if( $wpdb->get_var("show tables like '$list_table_name'") != $list_table_name) {

			}
		}
	}
}

?>

If no tables exist that have the same name, then we go ahead and create some using the magic of SQL:

if (!function_exists('tabberlist_install')) {
	function tabberlist_install() {
		global $wpdb;
		$tabberlist_version = "0.7.0";
		$hasInstalled = get_option("tabberlist_version");
		$list_table_name = $wpdb->prefix . "tabberlist";
		$category_table_name = $wpdb->prefix . "tabberlistcat";
		if ($hasInstalled != $tabberlist_version) {
			if( $wpdb->get_var("show tables like '$list_table_name'") != $list_table_name) {
				$sql = "CREATE TABLE " . $list_table_name . " (
					id mediumint(9) NOT NULL AUTO_INCREMENT,
					dateAdded VARCHAR(15),
					dateDeleted VARCHAR(15),
					item tinytext NOT NULL,
					url tinytext NOT NULL,
					new VARCHAR(10) NOT NULL,
					deleted VARCHAR(10) NOT NULL,
					cat_id int(5) NOT NULL,
					UNIQUE KEY id (id)
				);";
				require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
				dbDelta($sql);
				add_option("tabberlist_version", $tabberlist_version);
			}
			if ($wpdb->get_var("show tables like '$category_table_name'") != $category_table_name) {
				$sql = "CREATE TABLE " . $category_table_name . " (
					id mediumint(9) NOT NULL AUTO_INCREMENT,
					category tinytext NOT NULL,
					description tinytext,
					counted VARCHAR(10) NOT NULL,
					UNIQUE KEY id (id)
				);";
				dbDelta($sql);
			}

		}

	}
}

If you’re not familiar with SQL language, then basically we’re going through and creating the database columns. For example, the first table has a column named ‘id’ that is integer only, will not take anything more than 9 digits long, will auto increment – automatically add the next available number – if not given something specific and is not to be left blank.

The next column is called ‘dateAdded’ and is a variable character (letters and numbers) string that is no longer than 15 characters. MySQL does have a separate DATETIME data type, but for this plugin we’re using UNIX timestamps (number of seconds since January 1 1970 00:00:00 GMT) so it’s easier just to throw in and retrieve the string of numbers. MySQL requires everything in a specific format (DD-MM-YYYY HH:MM:SS), so it would be a lot of messing around converting to and from timestamps and MySQL DATETIME.

The final thing to note is the UNIQUE KEY declaration. Each table needs a unique key column where every value in that column is, well, unique. We need to tell MySQL which column that is (and then make sure that every entry is totally unique – the best way is to leave that column well alone when writing to the DB – let MySQL take care of the numbering or things get messy fast).

After we’ve declared our tables, we need to require the ‘upgrade.php’ file so that we can use the dbDelta WordPress function. This function does some internal database checking before it adds our table, and will allow us to painlessly change our table structure in future versions of the plugin should we need to.

Which we shouldn’t, cause we had a plan!

We then add an option using the WordPress add_option() function to the standard wp_options table which simply records the current version of our plugin. This simple key/value pair will tell future versions of the plugin what version is currently installed.

Finally, we repeat the table creation process for our ‘categories’ table. Et volia, our very own plugin tables, primed and ready for data. Stay tuned for part 3, where I explore more Plugin Development goodness…

Sign up to my RSS feed so that you don’t miss a step and, if you find it useful, remember to share!

I’ve been asked by Adam Baker of ManVsDebt fame to create a plugin that will help him organise his Stuff page.

In case you don’t know, Adam Baker, his wife and his young daughter are off travelling the world (currently they’re in New Zealand) and Adam is blogging about his attempts to get out of debt and into life. A noble aim and a pretty damned exciting adventure by all accounts.

Anyhow, one of the pages on his blog features lists of all the stuff that he and his family own. At the moment, it is just a single page with a big long list.

Adam put a call out on Twitter for someone to help re-organise this page and I volunteered my services. So, this weekend at Line In will be mostly about me creating a new plugin which I have tentatively named TabberList.

And, in a fit of productivity, I have also decided that I’m going to blog about my adventures in WordPress Plugin Development Land.

I have tentatively named this “Developing a Plugin”.

Snappy.

Part 1 – Planning

I’ve heard rumours that having some sort of a plan is often a good idea if you’re going to do something big and so, being the kind of man that likes to experience new things, I thought I’d give it a go. Here’s my first attempt:

My Plugin Plan

Not too shabby, right?

I know, I know. I can turn my hand to anything. Did you see the database table outline in the top right hand corner? Pretty proud of that part.

Now that I have a plan firmly in hand, I’m ready to start hacking WordPress to pieces.

Hold on to your mousemats, it’s going to be a hell of a ride*.

*Excitement not guaranteed.

Remember to sign up to my RSS feed so that you don’t miss a step!