Widget Base Class
Word of introduction
Widget Base Class is a PHP class which facilitates widget creation, by faster creationm sanitization, validation and updates of Widget fields. Such an approach lets one set up widgets much faster, without code repetitions and care for repeated data validation.
Thanks to that we can get rid of the update method completely and stop worrying about the form validation itself.
Usage
Instatitaion
To use the base class, simply include it within your theme / plugin files and then extend it with the child class, in a same way as you extend WP_Widget class.
For instance let's analyze the sample class which is a part of this repository
class Sample_Widget_Base_Child extends Widget_Base {
function __construct() {
$this->text_fields = array( 'title' );
parent::__construct(
'sample_widget_base_child', // Base ID
__( 'Supply Widget Base Child', 'textdomain' ), // Name
array( 'description' => __( 'Sample Widget Base Child.', 'textdomain' ), ) // Args
);
}
Note that, we're using the parent constructor here and we're passing the arguments of the new widget we want to have available.
Built in methods
The widget does all of the data validation on its own. However we have to define the fields we want to use, so that our base class would have an idea on what kind of fields we'd like to use.
By default the class handles the following fields
- input
- checkbox
- select
- textarea
Say we want to define the title of our widget. Let's take a look at our constructor
function __construct() {
$this->text_fields = array( 'title' );
/* some code here */
);
}
We have defined an array of text_fields, which are then automatically validated and rendered by the base class. In the same way we can define other fields. The class assumes their names go as follows:
- text_fields
- text_areas
- checkboxes
- select_fields
Now we want to be sure that the text field is rendered on the Widget Dashboard place whenever we want it. Henceforth the parent gti() comes to help. We'll place it within our child class form method.
public function form($instance) {
// generate the text input for the title of the widget. Note that the first parameter matches text_fields array entry
echo parent::gti( 'title', 'Title', $instance );
}
The method takes at least three arguments. The first one corresponds to the key within our text_fields array and serves as the inputs "name" and "id" attribute. The second one is the label of the input field. And the third one is the widget's instance. There are two more optional arguments "note" and a "class". The first one prints a nice side note below the field, which can serve as a helpful text for the end user. The second one assigns custom class to the input container.
Similary the functions for other fields follow the same naming pattern: gt - generate textarea, gtc - generate checkbox, gts - generate the select field. To find out the complete list of arguments and their use cases analyze the code of the base class: https://github.com/gicolek/Widget-Base-Class/blob/master/widget-base.php