WordPress widgets seem to be far less popular than shortcodes. Perhaps it’s because they are a little trickier to code and often thought of simply as a sidebar component.
However the prevalence of drag-and-drop builders is freeing widgets from the confines of the sidebar and turning them into an increasingly powerful tool in the WordPress site building process.
Learning how to build your own WordPress widgets will empower you to create websites that are quick to build and easy to manage.
The WordPress Codex widget page starts:
WordPress Widgets add content and features to your Sidebars.
This is perfectly true–but that sells widgets a bit short, as they act as the primary building block for many site design tools such as Site Origin’s Page Builder, Beaver Builder and the Ultimatum framework.
And while the array of widgets is massive, they can’t possibly cover every functionality requirement of every site, so learning to build your own widgets will be an enormous help when building WordPress websites.
Here, we’ll make a couple widgets–the first being the world’s simplest widget and a fairly complicated widget that integrates with the media library with a few hints and tips thrown in along the way for good measure.
Some familiarity with PHP will be useful, as will some front-end coding skills, but you certainly don’t have to be an expert developer.
Okay, let’s start with the Hello World widget.
Say Hello To The World’s Simplest Widget
Since WordPress 2.8, building widgets has been a matter of extending WordPress’ own widget class, WP_Widget, resulting in your custom widget only having to focus on 4 main functions:
- Initialisation (__construct) – handles actions to take when the widget is first created such as enqueueing specific javascript or stylesheets in the output
- Front-end display (widget) – handles the generation of the widget’s HTML output
- Back-end form (form) – handles the generation of the form controls that make up the widgets edit interface in the Admin interface
- Update (update) – handles the form submission from the back-end form, updating stored data as necessary
To add your custom widget to WordPress is a simple matter of wrapping your custom widget class in a standard plugin file along with a call to register it.
Here’s an example:
https://gist.github.com/bestwebsite/73dfaa258a3397ca1b18
The widget file uses the standard plugin header and includes just the custom widget class (My_Widget) and a call to the register_widget function that has been hooked to the widgets_init action.
The back-end interface is achieved by outputting a single textbox form control in the formfunction. Notice how the control’s id and name attributes are generated using the get_field_id and get_field_name functions provided by the base widget class.
Existing values for controls are held in the $instance argument.
When the form is submitted, by clicking Save, the update function is used to pre-process the data before it is saved.
All pretty simple and, let’s be honest, pretty useless, so let’s take a look at a slightly more complicated and more useful example.
Something More Useful
Working with custom post types inevitably creates a need for a custom widget.
In this scenario, we will build a widget that displays the thumbnail, title and excerpt for a story custom post type. The widget will provide a dropdown list of published stories to select from as well as providing a setting to automatically choose the most recently published.
The back-end form and the front-end display look something like this:
https://gist.github.com/bestwebsite/6a322585af1d99ffb99c
The widget back-end form still looks pretty simple and indeed all we’ve done is replaced the title textbox control with a select control. The built-in WordPress function get_posts is used to build a list of story post type titles.
You’ll notice in the form function that a Most Recent option is hardcoded with a value of 0 – this will kick-off slightly different processing in the front-end display, widget, function.
If Most Recent has been selected then the widget function will grab the most recently published story post type (again using get_posts) otherwise it will pull in the post selected from the widget select control.
If a story has been found then a custom-sized thumbnail, title, excerpt and read more link are output.
A simple but useful example as displaying the content of custom post types is a common use case for a custom widget.
