Implementing Custom Widgets in Your Plugin
Posted on 16th June 2023
Introduction
WordPress plugins allow you to extend the functionality of your website without having to edit the core code of WordPress. One popular way to do this is by adding custom widgets to your plugin. In this article, we will show you how to add custom widgets to your WordPress plugin.
What is a Widget?
In WordPress, a widget is a piece of functionality that you can add to your website. WordPress comes with a number of default widgets, such as the Recent Posts widget, the Calendar widget, and the Meta widget.
You can also add custom widgets to your WordPress plugin. These widgets can be anything you want, from a simple text widget to a complex widget that displays a list of your most recent posts.
Creating a Custom Widget
Creating a custom widget is a two-step process. First, you need to create the widget itself. Second, you need to register the widget so that WordPress knows it exists.
Creating the Widget
To create a widget, you need to create a new PHP class that extends the WP_Widget class. This class will contain all the code for your widget.
Here is an example of a custom widget class:
class My_Custom_Widget extends WP_Widget {
// The rest of the widget class goes here…
}
As you can see, the class name is My_Custom_Widget. You can name your widget class anything you want.
Next, you need to add a constructor function to your widget class. This function will give your widget a name and description, and it will also set some other options for the widget.
Here is an example of a constructor function:
class My_Custom_Widget extends WP_Widget {
function __construct() {
// Give your widget a name and description
parent::__construct(
‘my_custom_widget’,
‘My Custom Widget’,
array( ‘description’ => ‘This is my custom widget.’ )
);
}
}
As you can see, the constructor function takes three parameters:
The first parameter is the id of the widget. This should be a unique string that is used to identify the widget.
The second parameter is the name of the widget. This is the name that will be displayed in the WordPress admin area.
The third parameter is an array of options for the widget. In this example, we are setting the description option for the widget.
Next, you need to add the widget() function to your widget class. This function is responsible for outputting the content of the widget.
Here is an example of the widget() function:
class My_Custom_Widget extends WP_Widget {
// The rest of the widget class goes here…
function widget( $args, $instance ) {
// Output the content of the widget
echo ‘Hello world!’;
}
}
As you can see, the widget() function takes two parameters:
The first parameter is an array of arguments for the widget.
The second parameter is an array of options for the widget.
In the widget() function, you can use the $args and $instance parameters to output the content of the widget.
In this example, we are simply outputting the string “Hello world!”.
Registering the Widget
Once you have created the widget, you need to register it so that WordPress knows it exists.
To register a widget, you need to add the following code to your plugin:
add_action( ‘widgets_init’, ‘my_register_widgets’ );
function my_register_widgets() {
register_widget( ‘My_Custom_Widget’ );
}
As you can see, we are using the widgets_init action hook to register our widget. We are also using the register_widget() function to register our widget.
Adding Fields to Your Widget
In the previous section, we showed you how to create a custom widget and register it with WordPress. In this section, we will show you how to add fields to your widget.
Adding fields to your widget allows users to customize the widget from the WordPress admin area.
Creating the Form Fields
To add fields to your widget, you need to use the form() function. This function outputs the HTML for the widget form fields.
Here is an example of the form() function:
class My_Custom_Widget extends WP_Widget {
// The rest of the widget class goes here…
function form( $instance ) {
// Output the options form on the widget admin page
}
}
As you can see, the form() function takes one parameter: an array of options for the widget.
In the form() function, you can use the $instance parameter to output the HTML for the widget form fields.
In this example, we are outputting a text field for the widget title.
Saving the Widget Options
When the user saves the widget form, WordPress will call the update() function. This function is responsible for saving the widget options.
Here is an example of the update() function:
class My_Custom_Widget extends WP_Widget {
// The rest of the widget class goes here…
function update( $new_instance, $old_instance ) {
// Save the widget options
}
}
As you can see, the update() function takes two parameters:
The first parameter is an array of new options for the widget.
The second parameter is an array of the old options for the widget.
In the update() function, you can use the $new_instance and $old_instance parameters to save the widget options.
In this example, we are using the $new_instance[‘title’] variable to save the widget title.
Displaying the Widget Options
In the previous section, we showed you how to add fields to your widget and save the widget options. In this section, we will show you how to display the widget options in the front-end of your website.
Retrieving the Widget Options
To retrieve the widget options, you need to use the get_options() function. This function retrieves the widget options from the database and returns them as an array.
Here is an example of the get_options() function:
class My_Custom_Widget extends WP_Widget {
// The rest of the widget class goes here…
function get_options() {
// Get the options from the database
$options = get_option( ‘my_custom_widget_options’ );
// Return the options as an array
return $options;
}
}
As you can see, the get_options() function retrieves the widget options from the database using the get_option() function.
The get_option() function takes one parameter: the name of the option to retrieve. In this example, we are using the my_custom_widget_options option.
Next, the get_options() function returns the options as an array.
Outputting the Widget Options
Once you have retrieved the widget options, you can output them in the front-end of your website.
Here is an example of how to output the widget options:
class My_Custom_Widget extends WP_Widget {
// The rest of the widget class goes here…
function widget( $args, $instance ) {
// Get the options from the database
$options = $this->get_options();
// Output the options
echo ‘Title: ‘ . $options[‘title’];
}
}
As you can see, we are using the $this->get_options() function to retrieve the widget options.
Next, we are outputting the title option using the echo statement.
Conclusion
In this article, we showed you how to add custom widgets to your WordPress plugin. We also showed you how to add fields to your widget and how to display the widget options in the front-end of your website.
