How To Create Your First WordPress Widget
Creating your first WordPress widget is a powerful experience — you get to build something cool for the most popular CMS on the web today. It is estimated that WordPress powers over 60% of the top 10 million sites on the web. After finishing this tutorial, you will know how to create a WordPress widget and have the basic knowledge to create your own custom widgets.
In this tutorial, we are going to build a widget that directs users from your personal blog to your RobberBaron channel. This has two applications: either you are a creator who already has a massive following or you are building a WordPress site for a creator who has a following. Either way, we are going to leverage basic WordPress functionality, WordPress's Settings API, WordPress's Widgets API and one of RobberBaron's developer functions to achieve our goal.
A WordPress widget is a small user interface element that can be placed on the user-facing side of a WordPress website and then subsequently be positioned using the admin's widget page. It is typically located either in the sidebar or the footer. A widget is a type of plugin that uses WordPress’s Widgets API. In this tutorial, the words 'widget' and 'plugin' will be used interchangeably. The widget we are creating today is positioned on the footer and is a button that opens a connected user's RobberBaron channel.
Step 1 — Download the source code and install the plugin
Firstly, download the source code we are going to use in this tutorial: DOWNLOAD SOURCE. To view the GitHub repo, CLICK HERE. After you download the source, unzip it. Rename the folder from 'robber-baron-tv-main' to 'robber-baron-tv'. Copy the folder into your local WordPress plugins folder. If you are completely new to WordPress, there is a manual associated with this widget that can help you with the installation process: GET IT HERE.
Once you are done with the installation, you will have access to these four rudimentary screens:
Screen 1 — the positioned RobberBaron widget in the widgets page:
Screen 2 — the RobberBaron settings page:
Screen 3 — the RobberBaron widget facing the user:
Screen 4 — the RobberBaron page the widget directs a user:
IMPORTANT: please install and run this widget on your local installation and download the manual if possible — this will make your learning so much easier because you will understand exactly what the plugin is trying to achieve.
Step 2 — Create the widget
Once you have downloaded the source code and installed the widget on your local WordPress installation, open the plugin folder in your favorite code editor/IDE.
The plugin has three important files that your should take a look at: robber-baron-tv.php (the widget entry point), includes/robber-baron-tv-admin.php (the admin code) and uninstall.php (the uninstaller).
To make sure that there are no clashes with names, it is important to give you functions unique names. The names of all the functions in our widget will be prefixed with 'robber_baron_tv_'.
a) robber-baron-tv.php: this is the widget's entry point— what WordPress sees when it looks into your plugin folder. This file not only tells WordPress what to do but what other files to load to accomplish that as well. As such, a WordPress widget can contain one or many files.
This file, which is largely in the form of a WordPress widget class, has important functions we need to take note of.
function __construct(): The constructor is where the class is formally created by initialising all the variables and calling the functions that we need to get the widget up and running.
public function form($instance): This creates the widget form for the widgets backend. This section is not very important but essentially, this is a form that you can use to populate rudimentary options that you will use wherever you choose to display the widget.
public function update($new_instance, $old_instance): This sections helps us save options to the WordPress database.
public function widget($args, $instance): The meat of the widget. In this section, we define what and how the widget is displayed.
public function robber_baron_tv_load_scripts(): This loads the scripts, javascript and css, needed to run the widget.
public function robber_baron_tv_add_options(): This is important on installation — it installs all the options the plugin will need.
function robber_baron_tv_widget_reg(): Registration of the widget that has just been created.
Let's go through all the important code in robber-baron-tv.php.
__construct(): some important things crucial to the functioning of the widget are happening in this function. In line 5, the plugins options are added — these options are added on the first run of the widget. On line 11, the saved RobberBaron user ID that you retrieved when you connected to RBTV is retrieved — if you haven't done this yet, this variable is empty.
form($instance): this is the widget form displayed in the admin's widget page. All you need to know is that this is how the widget is rendered.
update($new_instance, $old_instance): this updates what you have written in the widget admit and saves it to the database.
widget($args, $instance): this sections displays the widget. This widget is designed to be displayed in the footer of a page. Line 16–36 render the widget in the footer. Line 39–41 append link to the widget if the plugin has been connected with RBTV.
robber_baron_tv_load_scripts(): this loads the css file used by the widget. This is how script files — javascript and css — are loaded in WordPress.
robber_baron_tv_add_options(): this adds new widget options to the WordPress installation. This is run only once and will not run again until the plugin is installed again.
robber_baron_tv_widget_reg(): this registers the 'robber_baron_tv' widget with your local WordPress instance.
You now understand how the entry point and the widget section of the plugin works! Be patient with yourself and keep going through the file until you understand it.
b) includes/robber-baron-tv-admin.php: this section is the administration section of the plugin and can be accessed by the clicking on the 'RobberBaron.TV' menu item.
This class has numerous functions but the most important for your learning are the ones listed below.
function __construct(): the entry-point to the admin section.
public function robber_baron_tv_add_menu_page(): adds and menu item and associated page to WordPress.
public function robber_baron_tv_initialize_options(): uses the WordPress settings API to display input elements in the 'Connection' tab of the plugin.
public function robber_baron_tv_configuration_display(): displays the settings pages of the plugin.
function robber_baron_tv_connect(): this function 'connects' your local WordPress installation with your RobberBaron channel.
Let’s go through all the important code in includes/robber-baron-tv-admin.php.
__construct(): this is the entry-point into the file and the most important lines are 15–17. In these lines, the plugin connects with RobberBaron if an email exists. That is, the option 'robber_baron_tv_email_address' is not an empty string.
robber_baron_tv_add_menu_page(): This sections adds the 'RobberBaron.TV' menu page to WordPress. This menu page is where the settings on the widget will be.
robber_baron_tv_initialize_options(): this section uses WordPress's Settings API to create page that can save and edit WordPress options. A settings page has sections and those sections are filled with fields. Line 17–22 add a section. Once a section has been added, child fields can be added and registered. The rest of the code block does just that.
robber_baron_tv_configuration_display(): this code block outputs settings we created to the WordPress page.
robber_baron_tv_connect(): this is the second most important section of the plugin after displaying the widget with the widget() function. In this section, we use one of RobberBaron's public developer functions to get a userID that is used to build a http address to the user's channel. Essentially what is happening is that we send a user's email address in JSON format and we received a JSON response that contains the userID.
c) uninstall.php: this file removes all the options the plugin installed. This is beneficial because it prevents faulty setups of fresh installations.
Validation and Sanitising
WordPress has an easy mantra:
Sanitize early
Escape late
Always validate
SANITIZE: Data that is input (either by a user or automatically) must be sanitized as soon as possible. This lessens the possibility of XSS vulnerabilities and MITM attacks where posted data is subverted.
VALIDATE: All data should be validated, no matter what. Even when you sanitize, remember that you don’t want someone putting in ‘dog’ when the only valid values are numbers.
ESCAPE: Data that is output must be escaped properly when it is echo’d, so it can’t hijack admin screens. There are many esc_*() functions you can use to make sure you don’t show people the wrong data.
Follow the links below to learn more on the subject:
- https://developer.wordpress.org/plugins/security/securing-input/
- https://developer.wordpress.org/plugins/security/securing-output/
Conclusion
Learning WordPress plugin development is a long and winding road. Do not be afraid to tinker with the code and figure out what changes in the widget when you modify the code. Please also read the comments in the code carefully — there are a lot of nuggets in there that can radically help with your learning curve. Happy coding!
