Eventhough WordPress 2.3 hasn't yet been released to the general public at the moment I'm writing this, I'd like to do one or more posts on some of the new features that went into 2.3. Although tagging is propably the biggest new addition, everybody is already blogging about it, or will be. So I'll be concentrating one some smaller, but still very usefull new features.

In this post, that will be Importer Plugins. What are Importer Plugins? As most of you know, WordPress comes with a set of importers which can be used to import data from other formats/blogs into your blog. (Think DotClear, Blogger and many more) But there are many more systems out there which don't have importers that are build into WordPress. That's where plugins come in. A plugin can be used to extend the default WordPress behaviour and starting with 2.3 can also be used to add your own importer to WordPress.

So how do you create such a Importer Plugin? Let's build one step by step. We start with an empty plugin template. (For basic information on writing plugins I recommend reading the Codex Writing a Plugin article or this tutorial by Leonid Mamchenkov)

<?php
/*
Plugin Name: Importer Plugin
Version: 0.1
Plugin URI: http://wordpress.nazgul.nu/
Description: Example of an importer plugin.
Author: Nazgul
Author URI: http://nazgul.nu/
*/
 
/*  Copyright 2007 Nazgul
 
    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
*/
?>

So how do we turn this into an importer? We create a class which will do the importing for us. I based this class on the bundled importers, as they almost all use this form, but stripped out the fluff for now.

// The importer
class Test_Import {
	var $importer_code = 'importerplugin';
	var $importer_name = 'Importer Plugin';
	var $importer_desc = 'Import stuff';
 
	// Function that will handle the wizard-like behaviour
	function dispatch() {
		if (empty ($_GET['step']))
			$step = 0;
		else
			$step = (int) $_GET['step'];
 
		switch ($step) {
			case 0 :
				wp_import_upload_form('admin.php?import='.$this->importer_code.'&step=1');
				break;
			case 1 :
				check_admin_referer('import-upload');
				$this->import();
				break;
		}
	}
 
	// Function that does the actual importing
	function import() {
		$file = wp_import_handle_upload();
		if ( isset($file['error']) ) {
			echo '< p>Sorry, there has been an error.< /p>';
			echo '< p><strong>' . $file['error'] . '</strong>< /p>';
			return;
		}
		$this->file = $file['file'];
		$this->id = (int) $file['id'];
 
		// TODO: Write import code
	}
 
	// Default constructor
	function Test_Import() {
		// Nothing.
	}
}

What we see is a class with a constructor which does nothing, 2 functions and a couple of variables. Let's start with those variables. importer_code is the name which WordPress will be using to identify the importer internally. importer_name is the human readable name which will be shown on the Importer screen end importer_desc is the description which is displayed on that same page.

The importers are wizards. That means they can have multiple screens during various stages of the import process. That's where our dispatch function comes in. It shows the different screens based on the step in the wizard where you currently are. Currently the first step (0) shows an upload form and the second step does some security checking and runs the actual import by means of the import function.

So now that we have an importer, how do we let WordPress know it exists? We register it using the register_importer function. That function is part of wp-admin/includes/import.php which isn't loaded by default, so we'll have to do that as well.

// Instantiate and register the importer
include_once(ABSPATH . 'wp-admin/includes/import.php');
if(function_exists('register_importer')) {
	$test_import = new Test_Import();
	register_importer($test_import->importer_code, $test_import->importer_name,
		$test_import->importer_desc, array ($test_import, 'dispatch'));
}

We use include_once and function_exists because we don't want to kill the blog if the inclusion fails for some reason. (It will on pre 2.3 version because the import.php was located elsewhere) Next we instantiate our importer and register it, passing in our plugin code, name, description and dispatch function. That's all there is to building an Importer Plugin. I admit that this plugin doesn't actually import anything, but I'll leave that up as an exercise for the reader.

One last thing I'd like to include is some sort of protection. As stated, this behaviour is new to 2.3 and this plugin therefore won't work on older versions. Let's make sure people who try this plugin on older versions can't accidentally activate this plugin.

add_action('activate_'.plugin_basename(__FILE__), 'importerplugin_activate');
 
function importerplugin_activate() {
	global $wp_db_version;
 
	// Deactivate on pre 2.3 blogs
	if($wp_db_version<6075) {
		$current = get_settings('active_plugins');
		array_splice($current, array_search( plugin_basename(__FILE__), $current), 1 );
		update_option('active_plugins', $current);
		do_action('deactivate_'.plugin_basename(__FILE__));
	}
}

You can download the complete sourcecode for the plugin here.

That's it for now. Stay tuned for more posts about new 2.3 features.