February 05, 2023

Create a Custom Widget in WordPress

One of the flexible features WordPress offers is creating a custom widget to extend functionality and add dynamic content to different areas of a website. Learn how to create a custom widget in WordPress with a simple example.

Create a Custom Widget in WordPress

WordPress widgets are one of the easiest ways to add dynamic content to different sections of a website. These widgets provide complete control over what content will be displayed in which areas of the website and offer reusability of code without editing theme files each time. In this post, we will create a WP custom widget from scratch.

 

What is a Widget in WordPress?

A WordPress widget is a block of code adding some functionality that can be added from the widget area. WordPress offers some default widgets such as search, categories, archives, recent posts etc, which can be added to any section on the website. Widgets allow users to add features without editing theme files and repeating the same code in many places. Widgets can be added to the sidebar, header, footer or other custom widget areas.

 

How to Create a Custom Widget in WordPress?

Creating and adding a custom widget in WordPress provides several advantages, such as displaying custom content in selected areas of the website, reusing the functionality across the website and improving user engagement. Creating a custom widget basically requires three steps: create a widget class, register the widget and use it on the website from the widgets area of WordPress. We are going to add a custom widget in WordPress for our "property" post type with the following steps. 

 

Step 1: Create a Widget Class

This is the first step to create a new widget in WordPress. In this step, we create a widget class by extending the WP_Widget class of WordPress. We create a PHP file property-posts-widget.php, which defines a PHP class. Steps to create a widget class are as follows:

  • Create a PHP class named Property_Posts_Widget, extending the WP_Widget class of WordPress.
  • In the construct() method of the class, we call the parent class constructor, providing it three parameters: property_posts_widget as a unique ID of this widget, a name of the widget to be displayed, and an array of configurations.
  • The widget() method of this class will render the recent posts on the website wherever this widget is used. In this method, we use WP_Query to fetch the posts of type property that are published and we limit the number of posts using the count value of this widget.
  • The form() method of the class is the method that will render a form to change the settings of this widget in the widgets area of WordPress. We use two input fields in the form: one for the title of the widget and the second one for the number of posts to be displayed.
  • The update() method of the class will update the widget settings whenever the widget form is submitted. We sanitize the title using the sanitize_text_field function and the absint function for the count field.
<?php
/**
 * Property Posts Widget
 */

class Property_Posts_Widget extends WP_Widget {

    public function __construct() {
        parent::__construct(
            'property_posts_widget',
            __('Property Posts', 'text-domain'),
            [
                'description' => __('Displays recent Property custom posts.', 'text-domain')
            ]
        );
    }

    /**
     * Frontend Output
     */
    public function widget($args, $instance) {

        echo $args['before_widget'];

        if (!empty($instance['title'])) {
            printf('%s%s%s',
                $args['before_title'],
                apply_filters('widget_title', $instance['title']),
                $args['after_title']);
        }

        $count = !empty($instance['count']) ? absint($instance['count']) : 5;

        $query = new WP_Query([
            'post_type'      => 'property',
            'posts_per_page' => $count,
            'post_status'    => 'publish'
        ]);

        if ($query->have_posts()) :?>
            <ul class="property-widget">
            <?php
            while ($query->have_posts()) :
                $query->the_post();?>
                <li>
                    <?php
                    if (has_post_thumbnail()) {
                        printf('<a href="%s">%s</a>', get_permalink(), the_post_thumbnail('thumbnail'));
                    }
                    ?>
                </li>
                <h4>
                    <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
                </h4>
                <p><?php echo wp_trim_words(get_the_excerpt(), 20); ?></p>

                </li>
            <?php
            endwhile;
            ?>
            </ul>
        <?php
            wp_reset_postdata();
        else:
            printf('<p>%s</p>', __('No properties found.', 'text-domain'));
        endif;

        echo $args['after_widget'];
    }

    /**
     * Widget Settings
     */
    public function form($instance) {

        $title = isset($instance['title']) ? $instance['title'] : 'Latest Properties';
        $count = isset($instance['count']) ? $instance['count'] : 5;
        ?>
        <p>
            <label>Title</label>
            <input class="widefat"
                   name="<?php echo $this->get_field_name('title'); ?>"
                   type="text"
                   value="<?php echo esc_attr($title); ?>">
        </p>

        <p>
            <label>Number of Posts</label>
            <input class="tiny-text"
                   name="<?php echo $this->get_field_name('count'); ?>"
                   type="number"
                   value="<?php echo esc_attr($count); ?>"
                   min="1"
                   max="20">
        </p>
        <?php
    }

    /**
     * Save Settings
     */
    public function update($new_instance, $old_instance) {

        return array(
            'title' => sanitize_text_field($new_instance['title']),
            'count' => absint($new_instance['count'])
        );
    }
}
 

Step 2: Register the Widget

After creating the class, we need to register it so it will start showing in the widgets area of WordPress and we can use it on the website. We include the property-posts-widgets.php file in the functions.php file of the active theme. Then we register our widget using the function register_widget using the widgets_init hook of WordPress.

include('property-posts-widget.php');

/**
 * Register Widget
 */
function register_property_posts_widget() {
    register_widget('Property_Posts_Widget');
}
add_action('widgets_init', 'register_property_posts_widget');
 

Step 3: Use the Widget on The Website

All done, now we can use our custom widget we just created and display recently published properties anywhere on the website. We have control over the number of properties that will be displayed on the front-end side. To use or change the settings of this widget, follow these steps:

  • Go to Appearance ➡ Widgets from the left-side navigation of the WordPress dashboard.
  • The widgets area will now show the widget we created.
  • Add the widget to any section by dragging it and dropping it in the available widgets area, such as the header, footer, or any registered area.

We just demonstrated how to create a new widget in WordPress with an example. Creating custom widgets is a great way to extend the functionality of a website while keeping the code organized.

Home