Create a custom widget in WordPress

January 17th, 2012 by Jamie

In this blog post, we will teach you what is required to create your very own WordPress widget. The widget in this example is fairly straightforward, it will create a div with a custom image, title and URL which will be displayed on the front end.

Some of you who are already wise to WordPress may be asking why we haven’t used the existing WordPress Text widget which allows the inclusion of text and HTML. The answer is simple, usability. If the content within this div may change regularly you want to simplify the process as much as possible so the client can easily manage the image, title and URL while removing the potential for them to affect the way it is displayed to the user of the website.

This has added advantages if you are allowing the user to manage HTML that if changed could break some functionality within the site, think a JavaScript accordion for example. Put simply it allows maximum flexibility for the client with zero potential for someone with no knowledge of HTML to inadvertently damage or break anything.

To create a custom widget open up the widgets.php file within the inc folder of your theme and create a new class that extends WP_Widget with the name of your widget. For example:


class DivName_Widget extends WP_Widget {

}

This class will fully contain your widget. Within here there are four functions that are required for the widget to fully function. They are:


function __construct() {
// code here
}
function widget($args, $instance) {
// code here
}
function form($instance) {
// code here
}
function update($new_instance, $old_instance) {
// code here
}


Think of each one of these functions as a separate feature of the widget:

• the constructor
• the widget to be displayed on the front end of the site
• the form to be located in the admin of WordPress
• function to update the information stored in the database.

The constructor function will contain one line that sets the name and description of the widget which is displayed in the admin area.


function __construct() {
parent::WP_Widget(/* Base ID */'Apply_Online', /* Name */ 'Apply_Online', array('description' => 'This is a widget to manage the apply online sidebar feature'));
}


The widget function is the code that will be displayed on the front end of the site. It contains to arguments, the arguments (if set) and the current instance of the widget.

What it echoes out the required html code while adding the data where relevant from the instance argument passed into the function.

function widget($args, $instance) {

    extract($args);
    $title = apply_filters('title', $instance['title']);
    $img = apply_filters('text', $instance[img]);
    $url = apply_filters('url', $instance['url']);
    $title = addslashes($img);
    $text = addslashes($text);
    $url = addslashes($url);
    echo "<div id='name'>";
    echo "<h2>$title</h2>";
    echo “<img src=$img alt=”title” />”;
    echo "<a href='$url' >Click Here</a>";
    echo "</div>”;
}

The form function again has the current instance of the widget passed into it as an argument to allow the current data to be displayed and edited in the admin area. If the instance is currently set then it populates the form with this data, else it populates it with default data to be overridden.

It then creates the form with all the inputs required to manage the data. There is no need to include the form field, or the submit button due to wordpress managing this functionality for you.

function form($instance) {

if ($instance) {

$title = stripslashes($instance['title']);

$img = stripslashes($instance[‘img’]);

$url = stripslashes($instance['url']);

} else {

$title = __(‘title’, ‘text_domain’);

$img = __(‘img’, ‘text_domain’);

$url = __(‘url’, ‘text_domain’);

}

?>

<label for=”<?php echo $this->get_field_id(‘title’); ?>”><?php _e(‘Title:’); ?></label>

<input class=”widefat” id=”<?php echo $this->get_field_id(‘title’); ?>” name=”<?php echo $this->get_field_name(‘title’); ?>” type=”text” value=”<?php echo $title; ?>” />

<label for=”<?php echo $this->get_field_id(‘img’); ?>”><?php _e(‘Image:’); ?></label>

<input class=”widefat” id=”<?php echo $this->get_field_id(‘img’); ?>” name=”<?php echo $this->get_field_name(‘img’); ?>” type=”text” value=”<?php echo $img; ?>” />

<label for=”<?php echo $this->get_field_id(‘url’); ?>”><?php _e(‘URL:’); ?></label>

<input class=”widefat” id=”<?php echo $this->get_field_id(‘url’); ?>” name=”<?php echo $this->get_field_name(‘url’); ?>” type=”text” value=”<?php echo $url; ?>” />

<?php

}

Finally the update function is called when you make changes to the data using the form in the admin area, it over-rides the old data in the database to display these changes on the front end of the site.

function update($new_instance, $old_instance) {

$instance = $old_instance;
$instance['title'] = stripslashes($new_instance['title']);
$instance['img'] = stripslashes($new_instance['img']);
$instance['url'] = stripslashes($new_instance['url']);
return $instance;
}

And thats it, with these four functions WordPress will manage the rest for you and you will have a fully functional custom widget.

This entry was posted on Tuesday, January 17th, 2012 at 11:02 am . You can follow any responses to this entry through the RSS feed.

Link to us

If you want to link to this blog, copy and paste the following HTML code to your website.

One Response to “Create a custom widget in WordPress”

1. Ali says:

   January 21, 2012 at 2:16 am

   Excellent Tutorial, it was very easy to follow. I used Notepad++ to help me edit the php files.