{"id":18287,"date":"2020-12-30T17:00:58","date_gmt":"2020-12-30T16:00:58","guid":{"rendered":"https:\/\/qodeinteractive.com\/magazine\/?p=18287"},"modified":"2020-12-28T14:54:30","modified_gmt":"2020-12-28T13:54:30","slug":"create-wordpress-custom-widget","status":"publish","type":"post","link":"https:\/\/qodeinteractive.com\/magazine\/create-wordpress-custom-widget\/","title":{"rendered":"How to Create a Custom WordPress Widget"},"content":{"rendered":"

[vc_row][vc_column][vc_column_text]WordPress is the most popular CMS (Content Management System) in large part due to its flexibility. Thanks to its plugins and widgets, any user can create and manage a website. Furthermore, plugin and theme authors are constantly enhancing the default WordPress functionalities, often by adding new widgets. In doing so, they are helping all users, especially those with little to no coding experience. But, widget creation isn\u2019t reserved only for the most advanced WordPress users. While it is true that creating new widgets is more suited to developers, there is no reason why any intermediate WordPress user shouldn\u2019t try to create a WordPress custom widget. By creating custom widgets for your website, you can add or extend any existing website features. In this article, we will tackle how this can be done and share an example that we made for this occasion.
\n[\/vc_column_text][vc_empty_space height=”68px”][\/vc_column][\/vc_row][vc_row][vc_column][vc_column_text]<\/p>\n

What are WordPress widgets<\/h2>\n

[\/vc_column_text][vc_column_text]Before diving into the how-to part of this article, let us first clarify what WordPress widgets are. WordPress widgets are small pieces of content that are added to specialized areas called widget areas<\/strong>. Widget areas are located outside of the main page or post content.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]Widgets display various kinds of information that, and depending on the widget area where they are put, they could show on all pages or just some. The placement and number of possible widget areas depend on the WordPress theme you are using. Generally, most themes have widget areas in the sidebar, footer, and header<\/strong>. Certain widgets are available by default, while others are made available through a theme or a plugin.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]To find out which widgets and widget areas are at your disposal, you only need to navigate to Appearance > Widgets.<\/strong> Then, if you want to use a certain widget, you can simply drag it from the list of Available Widgets<\/em> on the left and drop it in the desired widget area on the right.[\/vc_column_text][vc_empty_space height=”50px”]

\n
\n \"Available <\/div>\n<\/div>[vc_empty_space height=”38px”][vc_column_text]Sometimes, specific widgets would be most effective in areas of your website that aren\u2019t covered by a theme\u2019s widget areas. In those cases, a user may decide to create custom widget areas<\/a> to display those widgets. However, there are cases where the desired functionality simply isn\u2019t available in the form of currently available widgets. Then, if you weren\u2019t able to find a suitable plugin, you should create a WordPress custom widget that meets your needs.[\/vc_column_text][vc_empty_space height=”80px”][vc_widget_sidebar sidebar_id=”new-top-picks-banner”][vc_empty_space height=”81px”][\/vc_column][\/vc_row][vc_row][vc_column][vc_column_text]<\/p>\n

How to create a custom WordPress widget<\/h2>\n

[\/vc_column_text][vc_column_text]Creating a custom WordPress widget involves adding a specifically created code either into the functions.php file<\/strong> of your theme or into your site-specific plugin<\/a>. Inserting the code should be done via FTP<\/a>. We trust that you are familiar with the use of FTP, or have taken a look at our article on it and are ready to proceed. Without going into the details of inserting it, we can focus on the process of creating the code for a WordPress custom widget. It\u2019s important to stress that you should make a backup of your website<\/a> beforehand as any code error could break your website. After doing that, you can proceed to the steps required to create the code.[\/vc_column_text][vc_empty_space height=”72px”][\/vc_column][\/vc_row][vc_row][vc_column][vc_column_text]<\/p>\n

Basic widget structure<\/h3>\n

[\/vc_column_text][vc_column_text]Since the 2.8.0 update, WordPress comes with a built-in class called WP_Widget<\/a>, which is responsible for creating widgets. And every WordPress widget is made by extending the functionality of the WP_Widget class. The WP_Widget class currently has 18 available (non-deprecated) methods that can be used when creating new widgets.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]For this article, we will cover the four most important methods, which are sufficient for creating a basic custom widget. Those are the following: __construct(), widget(), form()<\/strong> and update()<\/strong> methods. Depending on what kind of widget you wish to create, more methods might be needed.<\/strong> Those can be either some of the 18 belonging to the WP_Widget class or a specifically created method.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]To create a basic custom widget, you need to insert the four methods mentioned above within your class to extend the WP_Widget class. And, to be able to use the Widget within the dashboard, you also need to register it using the register_widget()<\/a> function. As such, the structure of a basic custom widget would look like this:[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]<\/p>\n

class Widget_Name extends WP_Widget {\r\nfunction __construct() {\r\n\/\/ Some code here\r\n}\r\npublic function widget( $args, $instance ) {\r\n\/\/ Some code here\r\n}\r\npublic function form( $instance ) {\r\n\/\/ Some code here\r\n}\r\npublic function update( $new_instance, $old_instance ) {\r\n\/\/ Some code here\r\n}\r\n}function name_of_the_register_function() {\r\nregister_widget( 'Widget_Name' );\r\n}add_action( 'widgets_init', 'name_of_the_register_function' );<\/pre>\n
[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]We\u2019re going to quickly elaborate the purpose of every piece of the code, before proceeding to study the example we made for this article.
\n[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]The __construct()<\/a> method creates the widget using four possible parameters: ID, name, widget, and control options. All parameters are optional, but the ID needs to be lowercase and unique.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]The widget()<\/a> method is the one that displays the widget content on the frontend.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]The form()<\/a> method displays the widget options form in the backend. It is responsible both for the availability and the design of the options within the widget. These options are seen when the widget is added to a widget area.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]The update()<\/a> method updates the options selected within the widget.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]The content of each of the above-mentioned methods differs significantly based on the purpose of the widget. Technically speaking, it means that every subclass of the WP_Widget class (i.e. every widget) overrides the above-mentioned parent methods of the WP_Widget class differently.<\/strong>[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]Apart from that, you also need to register the widget. To do so, you need to \u201chook\u201d it to the corresponding hook<\/a> using the add_action()<\/a> function. You can do it by adding two arguments \u2013 \u201cwidgets_init\u201d as the hook and the name of your callback function. That callback function needs to contain the use of the register_widget function, with the widget class name as the argument (in our example that\u2019s Widget_Name<\/em>).[\/vc_column_text][vc_empty_space height=”72px”][\/vc_column][\/vc_row][vc_row][vc_column][vc_column_text]<\/p>\n
Our example<\/h3>\n
[\/vc_column_text][vc_column_text]Now that the widget structure is clearer, we can proceed to an actual example. We made the following widget for the purposes of this article.
\n[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]<\/p>\n
\/**\r\n* Adds Custom_Widget widget.\r\n*\/\r\nclass Custom_Widget extends WP_Widget {\r\n\/**\r\n* Register widget with WordPress.\r\n*\/\r\nfunction __construct() {\r\nparent::__construct(\r\n'custom_widget', \/\/ Base ID\r\nesc_html__( 'My Custom Widget', 'text_domain' ), \/\/ Name\r\narray( 'description' => esc_html__( 'A basic custom widget', 'text_domain' ), ) \/\/ Args\r\n);\r\n}\r\n\/**\r\n* Front-end display of the widget.\r\n*\r\n* @param array $args Widget arguments.\r\n* @param array $instance Saved values from the database.\r\n*\r\n* @see WP_Widget::widget()\r\n*\r\n*\/\r\npublic function widget( $args, $instance ) {\r\necho $args['before_widget'];\r\nif ( ! empty( $instance['title'] ) ) {\r\necho $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title'];\r\n}\r\nif ( ! empty( $instance['text'] ) ) { ?>\r\n<p class=\"custom-widget-text\">\r\n<?php echo nl2br( esc_html( $instance['text'] ) ) ?>\r\n<\/p>\r\n<?php }\r\nif ( ! empty( $instance['link'] ) ) { ?>\r\n<a href=\"<?php echo esc_url( $instance['link'] ); ?>\"\r\ntarget=\"<?php echo esc_attr( $instance['link_target'] ); ?>\" class=\"custom-widget-link\">\r\n<span><?php echo esc_html__( 'Learn more', 'text_domain' ); ?><\/span>\r\n<\/a>\r\n<?php }\r\necho $args['after_widget'];\r\n}\r\n\/**\r\n* Back-end widget form.\r\n*\r\n* @param array $instance Previously saved values from the database.\r\n*\r\n* @see WP_Widget::form()\r\n*\r\n*\/\r\npublic function form( $instance ) {\r\n$title = ! empty( $instance['title'] ) ? $instance['title'] : '';\r\n$text = ! empty( $instance['text'] ) ? $instance['text'] : '';\r\n$link = ! empty( $instance['link'] ) ? $instance['link'] : '';\r\n$link_target = ! empty( $instance['link_target'] ) ? $instance['link_target'] : '_blank';\r\n?>\r\n<!-- Title -->\r\n<p>\r\n<label for=\"<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>\">\r\n<?php esc_attr__( 'Widget Title:', 'text_domain' ); ?>\r\n<\/label>\r\n<input class=\"widefat\" id=\"<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>\"\r\nname=\"<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>\" type=\"text\"\r\nvalue=\"<?php echo esc_attr( $title ); ?>\">\r\n<\/p>\r\n<!-- Text -->\r\n<p>\r\n<label for=\"<?php echo esc_attr( $this->get_field_id( 'text' ) ); ?>\">\r\n<?php esc_attr__( 'Widget Text:', 'text_domain' ); ?>\r\n<\/label>\r\n<textarea class=\"widefat\" rows=\"16\" cols=\"20\" id=\"<?php echo esc_attr( $this->get_field_id( 'text' ) ); ?>\"\r\nname=\"<?php echo esc_attr( $this->get_field_name( 'text' ) ); ?>\"><?php echo esc_attr( $text ); ?>\r\n<\/textarea>\r\n<\/p>\r\n<!-- Link URL -->\r\n<p>\r\n<label for=\"<?php echo esc_attr( $this->get_field_id( 'link' ) ); ?>\">\r\n<?php esc_attr__( 'Insert URL:', 'text_domain' ); ?>\r\n<\/label>\r\n<input class=\"widefat\" id=\"<?php echo esc_attr( $this->get_field_id( 'link' ) ); ?>\"\r\nname=\"<?php echo esc_attr( $this->get_field_name( 'link' ) ); ?>\" type=\"text\"\r\nvalue=\"<?php echo esc_attr( $link ); ?>\">\r\n<\/p>\r\n<!-- Link target -->\r\n<p>\r\n<label for=\"<?php echo esc_attr( $this->get_field_id( 'link_target' ) ); ?>\">\r\n<?php esc_attr_e( 'Open link in a new tab?', 'text_domain' ); ?>\r\n<\/label>\r\n<select class=\"widefat\" id=\"<?php echo esc_attr( $this->get_field_id( 'link_target' ) ); ?>\"\r\nname=\"<?php echo esc_attr( $this->get_field_name( 'link_target' ) ); ?>\">\r\n<option value=\"_blank\" <?php echo ( $link_target == '_blank' ) ? 'selected' : ''; ?>>Yes<\/option>\r\n<option value=\"_self\" <?php echo ( $link_target == '_self' ) ? 'selected' : ''; ?>>No<\/option>\r\n<\/select>\r\n<\/p>\r\n<?php\r\n}\r\n\/**\r\n* Sanitize widget form values as they are saved.\r\n*\r\n* @param array $new_instance Values just sent to be saved.\r\n* @param array $old_instance Previously saved values from the database.\r\n*\r\n* @return array Updated safe values to be saved.\r\n* @see WP_Widget::update()\r\n*\r\n*\/\r\npublic function update( $new_instance, $old_instance ) {\r\n$instance = array();\r\n$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? sanitize_text_field( $new_instance['title'] ) : '';\r\nif ( current_user_can( 'unfiltered_html' ) ) {\r\n$instance['text'] = ( ! empty( $new_instance['text'] ) ) ? $new_instance['text'] : '';\r\n} else {\r\n$instance['text'] = ( ! empty( $new_instance['text'] ) ) ? sanitize_text_field( $new_instance['text'] ) : '';\r\n}\r\n$instance['link'] = ( ! empty( $new_instance['link'] ) ) ? sanitize_text_field( $new_instance['link'] ) : '';\r\n$instance['link_target'] = ( ! empty( $new_instance['link_target'] ) ) ? sanitize_text_field( $new_instance['link_target'] ) : '';\r\nreturn $instance;\r\n}\r\n} \/\/ class Custom_Widget\r\n\/\/ register Custom_Widget widget\r\nfunction register_custom_widget() {\r\nregister_widget( 'Custom_Widget' );\r\n}\r\nadd_action( 'widgets_init', 'register_custom_widget' );<\/pre>\n
[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]Even though this code may appear complicated at first glance, the widget it creates is rather simple. We developed it from the basic widget example given on the Widgets API<\/a> page, which we suggest you peruse. The code is properly commented to make it easier to review.<\/strong> Let us do so, part by part.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]Firstly, the widget is created using a subclass called Custom_Widget<\/strong> that extends the WP_Widget<\/strong> class. The same widget is registered at the end, by using the register_widget()<\/strong> function and the widgets_init<\/strong> hook.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]<\/p>\n
\/**\r\n* Adds Custom_Widget widget.\r\n*\/\r\nclass Custom_Widget extends WP_Widget {\r\n\/\/ Some code here\r\n} \/\/ class Custom_Widget\r\n\/\/ register Custom_Widget widget\r\nfunction register_custom_widget() {\r\nregister_widget( 'Custom_Widget' );\r\n}\r\nadd_action( 'widgets_init', 'register_custom_widget' );<\/pre>\n
[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]The Custom_Widget class has four methods. Using the __construct()<\/strong> method, we created a widget with custom_widget<\/strong> as its ID. The other two arguments mean that the name of this widget is My Custom Widget<\/strong>, while the description is A basic custom widget<\/strong>. You will be able to see this after navigating to Appearance > Widgets, within the Available Widgets<\/em> section.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]<\/p>\n
\/**\r\n* Register widget with WordPress.\r\n*\/\r\nfunction __construct() {\r\nparent::__construct(\r\n'custom_widget', \/\/ Base ID\r\nesc_html__( 'My Custom Widget', 'text_domain' ), \/\/ Name\r\narray( 'description' => esc_html__( 'A basic custom widget', 'text_domain' ), ) \/\/ Args\r\n);\r\n}<\/pre>\n
[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]The widget()<\/strong> method displays three parts of the widget\u2014the title of the widget, a piece of text, and a Learn more<\/em> link.<\/strong> By wrapping each of the parts with if{\u2026} statements<\/a>, we have made sure that those parts are only shown if they are inserted within the widget options. We also included the \u2018before_widget\u2019 and \u2018after_widget\u2019 values around the widget content, and the \u2018before_title\u2019 and \u2018after_title\u2019 values around the widget title. These four values are defined for all widget areas, default or custom. That is done during the widget area registration process using the register_sidebar()<\/a> function.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]Additionally, the labels were escaped for secure use<\/a> with the following functions: esc_attr()<\/a>, esc_url()<\/a>, esc_html()<\/a>, and esc_html__()<\/a>. Furthermore, most of the labels are translatable. However, to translate them, you would need to make sure that the text_domain<\/strong> string, which was added as a placeholder translate domain, is replaced with a proper theme or site-specific plugin translate domain. This is especially helpful for the Learn more<\/em> label, placed on the link.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]Finally, by further wrapping the text with the nl2br()<\/a> function, we have ensured that any line breaks that might have been inserted in the textarea in the backend are properly displayed in the frontend.[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]<\/p>\n
\/**\r\n* Front-end display of the widget.\r\n*\r\n* @param array $args Widget arguments.\r\n* @param array $instance Saved values from the database.\r\n*\r\n* @see WP_Widget::widget()\r\n*\r\n*\/\r\npublic function widget( $args, $instance ) {\r\necho $args['before_widget'];\r\nif ( ! empty( $instance['title'] ) ) {\r\necho $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title'];\r\n}\r\nif ( ! empty( $instance['text'] ) ) { ?>\r\n<p class=\"custom-widget-text\">\r\n<?php echo nl2br( esc_html( $instance['text'] ) ) ?>\r\n<\/p>\r\n<?php }\r\nif ( ! empty( $instance['link'] ) ) { ?>\r\n<a href=\"<?php echo esc_url( $instance['link'] ); ?>\"\r\ntarget=\"<?php echo esc_attr( $instance['link_target'] ); ?>\" class=\"custom-widget-link\">\r\n<span><?php echo esc_html__( 'Learn more', 'text_domain' ); ?><\/span>\r\n<\/a>\r\n<?php }\r\necho $args['after_widget'];<\/pre>\n
[\/vc_column_text][vc_empty_space height=”28px”][vc_column_text]Using the form()<\/strong> function, we have created four simple widget option fields. Those are the following:[\/vc_column_text][vc_empty_space height=”22px”]