This tutorial will explain how to create Wordpress widget from scratch. 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.
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.
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="<?php echo $data['option1']; ?>" /></label></p>
<p><label>Option 2<input name="widget_name_option2"
type="text" value="<?php echo $data['option2']; ?>" /></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.
.jpg)
