Did you know that you can create your very own custom widget in WordPress? While there are tons of additional widgets that come with some themes and plugins, WordPress also gives the option to code custom widgets manually for all users. In this WordPress tutorial, you will learn how to implement a basic widget in WordPress. If this sounds intimidating, then let us reassure you – the only ingredients you will need is the basic knowledge of WordPress and PHP. So, without further ado, let’s get started.
What you’ll need
Before starting this tutorial, you’ll need the following:
- Access to WordPress admin dashboard
- Any text editor
Table of Contents
A Word on WordPress Widgets
Widgets in WordPress are intended to make it easy for you to add items to your site through a simple drag-and-drop interface. Right out-of-the-box, WordPress ships with a number of widgets. These default widgets give you some basic utility and are compatible with every WordPress theme. But sometimes, such cookie-cutter widgets simply don’t cut it. In such cases, your best option is to scourge for plugins that offer you the functionality you desire. And while you may find plugins for most typical tasks, there are some scenarios where even third-party plugins won’t fulfill your requirements. This is where custom widgets come in hand. Custom widgets have to be created from the ground-up. This gives users a complete control and.
Setting the stage
To begin with a custom widget creation in WordPress, you need to make certain key decisions. First, you can choose to code the widget in a custom plugin. This will enable it to work with any site using that plugin. Or, you can simply add the widget to the functions.php file of a specific theme, which will make it work with only that theme. Secondly, you have the option to add the widget on a live site, or in a local environment. In accordance with sound development practices, we highly recommend you to first implement the widget in a local environment (see the tutorial how to run WordPress on Docker). Once you’ve made sure that it’s working fine and dandy, you can easily port it over to your site.
How do WordPress custom widgets work: Widgets API
WordPress lets your code custom widgets by providing you the Widgets API. To create any custom widget, you have to use the standard WP_Widget class from the API. This base class offers around 20 functions that you can play around with. Out of these, 4 is a minimum requirement for any widget to work. These 4 functions are:
- __construct() – constructor function
- widget() the contains output of the widget
- form() – determines widget settings in the WordPress dashboard
- update() – updates widget settings
Of course, there are plenty of other methods that provide additional functionality. For more on the WP_Widget class, take a look at this page.
Creating WordPress custom widget
IMPORTANT: It’s strongly recommended to create a full backup of your WordPress site (click her for tutorial) before proceeding further. In addition, you should also use WordPress child theme.
Now that we’ve laid out the conceptual foundation for our task, let’s get to work on its implementation. For this tutorial, we will be creating a simple Hello World custom widget, just so that you can learn the ropes of widget creation in WordPress. Of course, you can then move on to creating more complex widgets on your own.
One more thing: we are writing this code in the functions.php file of the currently loaded theme, but you can do so in any custom plugin.
Now open any text editor in your computer and create a new class which extends the base WP_Widget class, like this:
Now, we start implementing the 4 functions mentioned above one by one. The first in the list is the constructor method, which we will use to determine an ID, the name of the widget as it appears in the UI and a description:
Next, we move on to the widget’s appearance i.e. how will the front-end of the widget look like. This will be done through the widget() function:
Here, we have configured the output of our widget so that it displays the term ‘Hello World!’, and displays the title of the widget as specified by the user.
Now, we have to program the back-end of the widget using the form() method:
Here you can see how the custom widget has been setup. If the user supplies a title, then that title will be inserted in the HTML form we created. Otherwise, we will set the name of the title as Default Title. This is how the widget will appear in the WordPress admin area.
Last, but certainly not the least, we have to implement the update function to refresh the widget every time the settings have been changed.
All this is doing, is taking the current title of the newly created instance, removing any HTML/PHP tags , passing the title to the instance and returning it.
There is one more thing left to do here: you need to use an additional function to register the widget with WordPress:
Do note that the above lines have to be placed outside the hstngr_widget funtion.
We have defined a new function called hstngr_register_widget(), which registers our widget using the widget ID, specified in the __construct() function. Then, we have tied this function using widgets_init, which loads this widget into WordPress through the built-in add_action() method. Your final custom WordPress widget code should look like this:
You can either use File Manager, FTP client or WordPress Editor to add this code to your theme’s functions.php file. Add the code to active theme’s function.php file and press Update File button to save changes.
Now, simply go to your WordPress admin area, and navigate over to the Appearance -> Widgets section. You should see a widget named Hostinger Sample Widget in the Available Widgets list.
From here, drag the widget and drop it in the Sidebar menu on the right side of the page. You will now be able to set the title of the widget. Save it, and then visit your site. You will be welcomed with a custom widget with the title of your choice, and filled with the words ‘Hello World!’ inside.
Congratulations, you have successfully created your first ever custom WordPress widget. You can now preview how your widget looks like.
Creating a WordPress custom widget from a scratch can seem like a high mountain to climb for many. In reality, however, it is easily achievable for anyone having an entry-level skill set of HTML and PHP. In this tutorial, we showed you how to make a WordPress widget with the bare minimum number of steps. From here, you can go on to create more functional widgets. If you have found this helpful, be sure to check out other WordPress guides.