This tutorial will explain how to create Wordpress widget from scratch. We will make widget using PHP5 OOP. You will also learn how to implement configuration page for your widget.
Getting started
You should already have Wordpress installed, either on your local machine or on a testing server. For this tutorial we will use the Wordpress version 2.7. You should also have a theme that support widgets. You could use the default one or make a wordpress theme from scratch and widgetize it.
Widget name
The first task in creating a Wordpress widget is to think about what the widget will do, and make a (hopefully unique) name for your widget. Check out Plugins and the other repositories it refers to, to verify that your name is unique; you might also do a Google search on your proposed name. The name can be multiple words.
Widget files
We will start by creating a folder widget-name in our wp-content/plugins/ directory, where Wordpress stores all it’s plugins. It’s a good idea to always create a folder for your plugin, even if it consists only of 1 file, so you could add more files later.
The next step is to create our main widget file widget-name.php. To make Wordpress recognize it as a plugin we should add a specific header to it, that describes our widget.
Widget header
php
/*
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
*/
?> Our widget should appear in Wordpress administration area in inactive plugin list. Information about your widget will be extracted from the header of a main widget file. To continue developing our widget we must activate our plugin by clicking Activate to the right of the plugin entry.
Creating widget structure
There are different ways to create a Wordpress widget. I prefer creating it as a static class, but the downside of this method it that our widget will support php5 only, anyway I believe, that support for php4 can already be dropped. So let’s create our main class, that will contain all widget methods.
error_reporting(E_ALL);
add_action("widgets_init", array('Widget_name', 'register'));
class Widget_name {
function control(){
echo 'I am a control panel';
}
function widget($args){
echo $args['before_widget'];
echo $args['before_title'] . 'Your widget title' . $args['after_title'];
echo 'I am your widget';
echo $args['after_widget'];
}
function register(){
register_sidebar_widget('Widget name', array('Widget_name', 'widget'));
register_widget_control('Widget name', array('Widget_name', 'control'));
}
}
Our plugin should not throw any level errors (even notices), so we should turn error reporting on while we are developing. We will remove this line when the widget will be finished.
The add_action function hooks our register method to an widgets_init event. You can read about it in Wordpress codex. It takes the action hook name as its first parameter and the callback function as a second parameter. You should definitely read about callbacks in php manual.
To make widget appear in widgets menu in Wordpress we must register them first, we do that with our register method which creates a widget itself and a control panel for it.
The before_widget, after_widget, before_title and after_title in widget method are required for compatibility with various themes.
Navigate to widgets page in administration area and activate it. To do that press add button next to your widget. It should appear at current widgets column, you can press edit button next to it too see the control panel. Don’t forget to press save changes button!
The text from your widget method should appear in your blog sidebar.
Saving Widget Data to the Database
Most WordPress Widgets will need to get some input from the site owner or blog users and save it between sessions, for use in its filter functions, action functions, and template functions. This information has to be saved in the WordPress database, in order to be persistent between sessions. There are two basic methods for saving Widget data in the database.
WordPress Options
This method is appropriate for storing relatively small amounts of relatively static, named pieces of data - the type of data you’d expect the site owner to enter when first setting up the Widget, and rarely change thereafter. Option values can be strings, arrays, or PHP objects (they will be “serialized”, or converted to a string, before storage, and unserialized when retrieved). Option names are strings, and they must be unique, so that they do not conflict with either WordPress or other Plugins. Here are function you will need to modify options.
add_option($name, $value);
update_option($name, $new_value);
delete_option($name);
Create a custom database table
This method is appropriate for data associated with individual posts, pages, attachments, or comments — the type of data that will grow as time goes on, and that doesn’t have individual names. See Creating Tables with Plugins for information on how to do this.
Plugin Installation
If you need to install default data for your widget it is best to use activation hook. It takes 2 parameters. First one is a path to the main plugin file inside the wp-content/plugins directory. And the second one is the function to be run when the plugin is activated. Any of PHP’s callback pseudo-types will work. We will add activate method that will install default data for our widget.
error_reporting(E_ALL);
add_action("widgets_init", array('Widget_name', 'register'));
register_activation_hook( __FILE__, array('Widget_name', 'activate'));
register_deactivation_hook( __FILE__, array('Widget_name', 'deactivate'));
class Widget_name {
function activate(){
$data = array( 'option1' => 'Default value' ,'option2' => 55);
if ( ! get_option('widget_name')){
add_option('widget_name' , $data);
} else {
update_option('widget_name' , $data);
}
}
function deactivate(){
delete_option('widget_name');
}
function control(){
echo 'I am a control panel';
}
function widget($args){
echo $args['before_widget'];
echo $args['before_title'] . 'Your widget title' . $args['after_title'];
echo 'I am your widget';
echo $args['after_widget'];
}
function register(){
register_sidebar_widget('Widget name', array('Widget_name', 'widget'));
register_widget_control('Widget name', array('Widget_name', 'control'));
}
}
Creating widget control panel
We should use our control method for displaying and updating form with widget options. Here is a basic template for it.
function control(){
$data = get_option('widget_name');
?>
<p><label>Option 1<input name="widget_name_option1"
type="text" value="" /></label>p>
<p><label>Option 2<input name="widget_name_option2"
type="text" value="" /></label>p>
php
if (isset($_POST['widget_name_option1'])){
$data['option1'] = attribute_escape($_POST['widget_name_option1']);
$data['option2'] = attribute_escape($_POST['widget_name_option2']);
update_option('widget_name', $data);
}
}
You should be able to access it on the widgets page.
Conclusion
I hope this tutorial gave you all the information you need to build your first Wordpress widget. If you have something to add or found an error, please feel free to post a comment below. And I want to add that Wordpress codex is a great source of information.
courtsy: http://valums.com
1 comment:
Great post! I'm learning a lot from this. I'm wondering if you can include the source files for it however?
Post a Comment