Tuesday , 18 June 2019
Home / Programming / WordPress / Plugins / Widgets API – WordPress Plugin Tutorial
WordPress Widgets API
WordPress Widgets API

Widgets API – WordPress Plugin Tutorial

This post is part of the WordPress Plugin tutorial series. To find a link to all tutorials in order, then please click here.

The widgets API is what we’ll be learning next. It’s very simple to use. It does involve having basic knowledge of PHP OOP. If you don’t know how to create classes, then I recommend you learn the fundamentals of OOP and then come back here.

Getting Started

Create a new plugin called wpWidgetEx. In our index.php file, lets use this bit of code.

We’re including 2 files called func.inc.php and widget.class.php. Create these 2 files and leave them blank for now. We’re also introduced to a new action hook which is called widgets_init. This hook is fired when the widgets are initiated.

Let’s open up our func.inc.php file and include this bit of code.

When we hook into the widgets_init action, we call our jk_wex_reg_widget() function and inside this function we register our widget with the register_widget() function. This function has 1 required parameter which is the name of the class for your widget. In our case, it’s JK_WEX_Custom_Message_Widget.

Widgets API

Open up your widget.class.php file and this is where we’ll be defining our widget class. We’ll be working on this file for the rest of our tutorial. Copy this bit of code into that file.

Our class has 4 main functions. We’ll be discussing each function separately. Our first function, is the constructor function.

In this function, we’ll be adding details about our Widget and what it does. Let’s update it to this.

In our constructor function, we create an array with some options for our widget. The first option is the classname. The classname is the name of the class you’ll find in the <li> tags. If you wish to style it, then you would use this class to do so. Next, is our description. The description is a very short summary of your widget and what it does. This will be displayed to the user when they’re configuring their widgets.

Next, we run the WP_Widget() function and pass in 3 arguments. You first pass in a special ID for your widget. The next parameter accepts is a human readable name for your widget. The last parameter is the options for your widget. This must be an array. We’ll be passing in the array we created earlier.

Let’s take a look at our next function which is the form() function. Add this bit of code.

First, we create some default settings for our widget. Remember, your user can set up multiple instances of your widget. So, it’s always good to have some default values. You can have as many default options as you want and give them any names. In our case, we allow the user to change the title and the message. Next, you’ll notice the form() function is passed 1 variable named $instance.  This variable contains all the current values of this widget. We use the wp_parse_args() function to merge both arrays. Next, we create variables for each item in the array to make it shorter and easier to use.

Then, we start outputting our form. Notice, we’re using 3 special functions inside our form. The first function is get_field_name(). This function creates name attributes for your form. We pass it in the name we want to use.  The next function is esc_attr() function to make sure the output is clean and prevents XSS injections. Lastly, the get_field_id() function returns a special id for our input and label fields. This helps prevent any collisions with other widgets.

Let’s update our update() function to this.

Like the settings API, the widgets API takes care of updating the values. However, you do get the chance to filter or validate the data before it’s updated. The update() function allows us to do this. It’s pretty simple what’s going on here. We’re passed in 2 variables named $new_instance and $old_instance. It’s pretty obvious what values they hold.  The Widgets API already secures the data before inputting it, but we make sure by stripping any tags passed inside. We then return the data for it to be inputted into the database.

As you can see, we don’t even have to create these values with the options API as the widgets API does it already for us.

Lastly, let’s take a look at our widget() function.

The widget() function is the function that runs on the front end of your website. This is what’s rendered when someone views your widget in action. The first thing we do is extract the $args and $instance variables. We convert them from arrays into separate variables. All our values that we created are stored in the $instance array. The $args array contains arguments for our widget. This includes $before_widget, $after_widget, $before_title, and $after_title.

Before we start, we first apply filters to the title. We haven’t talked about apply_filters yet, but for now just know that you need to do it. We’ll talk more about this function in another tutorial. Next, we start echoing out our widget. You’ll notice that  that our variables extracted earlier from our $args array is being echoed out. This is important to echo out as they contain HTML markup for our widget and helps stylize our widget according to our theme. In between these echoes, we also echo out our title and message. You’re more than welcome to modify this however you like.


That’s it! The WordPress widget API is a very simple class to extend and use.

About Jasko Koyn

Check Also

WordPress Meta Boxes

WordPress Meta Boxes – WordPress Plugin Tutorial

WordPress meta boxes are used to display certain information or options in a page. It’s …

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.