Skip to main content

Create a wordpress widget

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.

Activate plugin

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.

Activate widget

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.

Your widget in 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.
Widget options

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


Comments

Anonymous said…
Great post! I'm learning a lot from this. I'm wondering if you can include the source files for it however?

Popular posts from this blog

Financial Engineering

Financial Engineering: Key Concepts Financial engineering is a multidisciplinary field that combines financial theory, mathematics, and computer science to design and develop innovative financial products and solutions. Here's an in-depth look at the key concepts you mentioned: 1. Statistical Analysis Statistical analysis is a crucial component of financial engineering. It involves using statistical techniques to analyze and interpret financial data, such as: Hypothesis testing : to validate assumptions about financial data Regression analysis : to model relationships between variables Time series analysis : to forecast future values based on historical data Probability distributions : to model and analyze risk Statistical analysis helps financial engineers to identify trends, patterns, and correlations in financial data, which informs decision-making and risk management. 2. Machine Learning Machine learning is a subset of artificial intelligence that involves training algorithms t...

Wholesale Customer Solution with Magento Commerce

The client want to have a shop where regular customers to be able to see products with their retail price, while Wholesale partners to see the prices with ? discount. The extra condition: retail and wholesale prices hasn’t mathematical dependency. So, a product could be $100 for retail and $50 for whole sale and another one could be $60 retail and $50 wholesale. And of course retail users should not be able to see wholesale prices at all. Basically, I will explain what I did step-by-step, but in order to understand what I mean, you should be familiar with the basics of Magento. 1. Creating two magento websites, stores and views (Magento meaning of website of course) It’s done from from System->Manage Stores. The result is: Website | Store | View ———————————————— Retail->Retail->Default Wholesale->Wholesale->Default Both sites using the same category/product tree 2. Setting the price scope in System->Configuration->Catalog->Catalog->Price set drop-down to...

How to Prepare for AI Driven Career

  Introduction We are all living in our "ChatGPT moment" now. It happened when I asked ChatGPT to plan a 10-day holiday in rural India. Within seconds, I had a detailed list of activities and places to explore. The speed and usefulness of the response left me stunned, and I realized instantly that life would never be the same again. ChatGPT felt like a bombshell—years of hype about Artificial Intelligence had finally materialized into something tangible and accessible. Suddenly, AI wasn’t just theoretical; it was writing limericks, crafting decent marketing content, and even generating code. The world is still adjusting to this rapid shift. We’re in the middle of a technological revolution—one so fast and transformative that it’s hard to fully comprehend. This revolution brings both exciting opportunities and inevitable challenges. On the one hand, AI is enabling remarkable breakthroughs. It can detect anomalies in MRI scans that even seasoned doctors might miss. It can trans...