How to Create a Custom WordPress Widget

Table of Contents

Widget is one of the most useful features provided by WordPress. Most WordPress developers even don’t use this feature. Even only a few developers know that there is an option to Create a Custom WordPress Widget

If you are one of those few who know that we can create a Custom WordPress Widget, this post is for you. In this, I will walk you through the complete process of how to create a custom WordPress Widget.

Here I will use an example with the following scenario, which was the client’s actual requirement.

The requirement was to create a custom category (Taxonomy) for the woocommerce products with the name “Items”.

All the terms added to Items taxonomy needs to be added to different product page sidebar like shop page, single page etc. First thing came to my mind was to create a shrtcode and then add to the sidebar of different pages but then I realize that instead I should create a custom WordPress widget which I can use at different locations by just drag and drop and even if client wants to remove that any time then he/she can remove.

Following are the steps I performed to create a custom WordPress widget that can add a custom taxonomy with the name “items”.

Step 1 – Create a custom taxonomy with the name “items”

Add the following code to your active theme’s functions.php or inside the plugin main file.

/**
 * add custom taxonomy to woocommerce products
 */
add_action( 'init', 'dcs_custom_taxonomy_Item' );
function dcs_custom_taxonomy_Item()  {
 $labels = array(
  'name'                       => 'Items',
  'singular_name'              => 'Item',
  'menu_name'                  => 'Item',
  'all_items'                  => 'All Items',
  'parent_item'                => 'Parent Item',
  'parent_item_colon'          => 'Parent Item:',
  'new_item_name'              => 'New Item Name',
  'add_new_item'               => 'Add New Item',
  'edit_item'                  => 'Edit Item',
  'update_item'                => 'Update Item',
  'separate_items_with_commas' => 'Separate Item with commas',
  'search_items'               => 'Search Items',
  'add_or_remove_items'        => 'Add or remove Items',
  'choose_from_most_used'      => 'Choose from the most used Items',
 );
 $args = array(
  'labels'                     => $labels,
  'hierarchical'               => true,
  'public'                     => true,
  'show_ui'                    => true,
  'show_admin_column'          => true,
  'show_in_nav_menus'          => true,
  'show_tagcloud'              => true,
 );
 register_taxonomy( 'item', 'product', $args );
 register_taxonomy_for_object_type( 'item', 'product' );
}

/**

* add custom taxonomy to woocommerce products

add_action( 'init', 'dcs_custom_taxonomy_Item' );

function dcs_custom_taxonomy_Item() {

$labels = array(

'name' => 'Items',

'singular_name' => 'Item',

'menu_name' => 'Item',

'all_items' => 'All Items',

'parent_item' => 'Parent Item',

'parent_item_colon' => 'Parent Item:',

'new_item_name' => 'New Item Name',

'add_new_item' => 'Add New Item',

'edit_item' => 'Edit Item',

'update_item' => 'Update Item',

'separate_items_with_commas' => 'Separate Item with commas',

'search_items' => 'Search Items',

'add_or_remove_items' => 'Add or remove Items',

'choose_from_most_used' => 'Choose from the most used Items',

);

$args = array(

'labels' => $labels,

'hierarchical' => true,

'public' => true,

'show_ui' => true,

'show_admin_column' => true,

'show_in_nav_menus' => true,

'show_tagcloud' => true,

);

register_taxonomy( 'item', 'product', $args );

register_taxonomy_for_object_type( 'item', 'product' );

}

Step 2 – Create a custom WordPress widget

Now add the following code to your active theme’s functions.php or inside the plugin main file. This will create a custom widget with the name “DCS Widget”. You can change this and use any name for your widget.

/**
 * Custom widget in available widgets
 * @return [type] [description]
 */
function dcs_load_widget() {
    register_widget( 'dcs_widget' );
}
add_action( 'widgets_init', 'dcs_load_widget' );
class dcs_widget extends WP_Widget {
 function __construct() {
 parent::__construct(
  'dcs_widget',
  __('DCS Widget', 'dcs_widget_domain'),
  array( 'description' => __( 'Sample widget based on DCS Tutorial', 'dcs_widget_domain' ), ) 
  );
 }
 public function widget( $args, $instance ) {
  $title = apply_filters( 'widget_title', $instance['title'] );
  echo $args['before_widget'];
  if ( ! empty( $title ) )
  echo $args['before_title'] . $title . $args['after_title'];
  $terms = get_terms( array(
      'taxonomy' => 'item',
      'hide_empty' => false,
  ) );
  foreach ($terms as $key => $value) {
   echo "<br>".$value->name;
  }
  echo $args['after_widget'];
 }
 public function form( $instance ) {
  if ( isset( $instance[ 'title' ] ) ) {
   $title = $instance[ 'title' ];
  }
  else {
   $title = __( 'New title', 'dcs_widget_domain' );
  }
  ?>
  <p>
  <label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label> 
  <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />
  </p>
  <?php 
 }
 public function update( $new_instance, $old_instance ) {
  $instance = array();
  $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
  return $instance;
 }
}

/**

* Custom widget in available widgets

* @return [type] [description]

function dcs_load_widget() {

register_widget( 'dcs_widget' );

}

add_action( 'widgets_init', 'dcs_load_widget' );

class dcs_widget extends WP_Widget {

function __construct() {

parent::__construct(

'dcs_widget',

__('DCS Widget', 'dcs_widget_domain'),

array( 'description' => __( 'Sample widget based on DCS Tutorial', 'dcs_widget_domain' ), )

);

}

public function widget( $args, $instance ) {

$title = apply_filters( 'widget_title', $instance['title'] );

echo $args['before_widget'];

if ( ! empty( $title ) )

echo $args['before_title'] . $title . $args['after_title'];

$terms = get_terms( array(

'taxonomy' => 'item',

'hide_empty' => false,

) );

foreach ($terms as $key => $value) {

echo "<br>".$value->name;

}

echo $args['after_widget'];

}

public function form( $instance ) {

if ( isset( $instance[ 'title' ] ) ) {

$title = $instance[ 'title' ];

}

else {

$title = __( 'New title', 'dcs_widget_domain' );

}

<p>

<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>

<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />

</p>

<?php

}

public function update( $new_instance, $old_instance ) {

$instance = array();

$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';

return $instance;

}

Optional (Bonus code) – Advanced option to exclude some terms by id

Add the following code instead of step 2 in the functins.php

/**
 * Custom widget in available widgets
 * @return [type] [description]
 */
function dcs_load_widget() {
 register_widget( 'dcs_widget' );
}
add_action( 'widgets_init', 'dcs_load_widget' );
class dcs_widget extends WP_Widget {
 function __construct() {
  parent::__construct(
   'dcs_widget',
   __('DCS Widget', 'dcs_widget_domain'),
   array( 'description' => __( 'Sample widget based on DCS Tutorial', 'dcs_widget_domain' ), ) 
  );
 }
 public function widget( $args, $instance ) {
  $title = apply_filters( 'widget_title', $instance['title'] );

  $excludeTerms = explode(",", $instance['excludeTerms']);

  $hideEmpty = $instance['hideEmpty'];
  
  echo $args['before_widget'];
  if ( ! empty( $title ) )
   echo $args['before_title'] . $title . $args['after_title'];
  $terms = get_terms( array(
   'taxonomy' => 'item',
   'hide_empty' => ($hideEmpty=="on")?true:false,
   'exclude' => $excludeTerms,
  ) );
  foreach ($terms as $key => $value) {
   echo "<br>".$value->name;
  }
  echo $args['after_widget'];
 }
 public function form( $instance ) {
  if ( isset( $instance[ 'title' ] ) ) {
   $title = $instance[ 'title' ];
  }
  else {
   $title = __( 'New title', 'dcs_widget_domain' );
  }

  if ( isset( $instance[ 'excludeTerms' ] ) ) {
   $excludeTerms = $instance[ 'excludeTerms' ];
  }

  if ( isset( $instance[ 'hideEmpty' ] ) ) {
   $hideEmpty = $instance[ 'hideEmpty' ];
  }
  ?>
  <p>
   <label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label> 
   <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />

   <label for="<?php echo $this->get_field_id( 'excludeTerms' ); ?>"><?php _e( 'Exclude these terms (comma separated ids):' ); ?></label> 
   <input class="widefat" id="<?php echo $this->get_field_id( 'excludeTerms' ); ?>" name="<?php echo $this->get_field_name( 'excludeTerms' ); ?>" type="text" value="<?php echo $excludeTerms; ?>" />


   <input class="widefat" id="<?php echo $this->get_field_id( 'hideEmpty' ); ?>" name="<?php echo $this->get_field_name( 'hideEmpty' ); ?>" type="checkbox" <?php echo $hideEmpty?"checked":''; ?> />
   <label for="<?php echo $this->get_field_id( 'hideEmpty' ); ?>"><?php _e( 'Hide Empty' ); ?></label> 

  </p>
  <?php 
 }
 public function update( $new_instance, $old_instance ) {
  $instance = array();
  $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
  $instance['excludeTerms'] = ( ! empty( $new_instance['excludeTerms'] ) ) ?  $new_instance['excludeTerms'] : '';
  $instance['hideEmpty'] = ( ! empty( $new_instance['hideEmpty'] ) ) ?  $new_instance['hideEmpty'] : '';
  return $instance;
 }
}

/**

* Custom widget in available widgets

* @return [type] [description]

function dcs_load_widget() {

register_widget( 'dcs_widget' );

}

add_action( 'widgets_init', 'dcs_load_widget' );

class dcs_widget extends WP_Widget {

function __construct() {

parent::__construct(

'dcs_widget',

__('DCS Widget', 'dcs_widget_domain'),

array( 'description' => __( 'Sample widget based on DCS Tutorial', 'dcs_widget_domain' ), )

);

}

public function widget( $args, $instance ) {

$title = apply_filters( 'widget_title', $instance['title'] );

$excludeTerms = explode(",", $instance['excludeTerms']);

$hideEmpty = $instance['hideEmpty'];

echo $args['before_widget'];

if ( ! empty( $title ) )

echo $args['before_title'] . $title . $args['after_title'];

$terms = get_terms( array(

'taxonomy' => 'item',

'hide_empty' => ($hideEmpty=="on")?true:false,

'exclude' => $excludeTerms,

) );

foreach ($terms as $key => $value) {

echo "<br>".$value->name;

}

echo $args['after_widget'];

}

public function form( $instance ) {

if ( isset( $instance[ 'title' ] ) ) {

$title = $instance[ 'title' ];

}

else {

$title = __( 'New title', 'dcs_widget_domain' );

}

if ( isset( $instance[ 'excludeTerms' ] ) ) {

$excludeTerms = $instance[ 'excludeTerms' ];

}

if ( isset( $instance[ 'hideEmpty' ] ) ) {

$hideEmpty = $instance[ 'hideEmpty' ];

}

<p>

<label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>

<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />

<label for="<?php echo $this->get_field_id( 'excludeTerms' ); ?>"><?php _e( 'Exclude these terms (comma separated ids):' ); ?></label>

<input class="widefat" id="<?php echo $this->get_field_id( 'excludeTerms' ); ?>" name="<?php echo $this->get_field_name( 'excludeTerms' ); ?>" type="text" value="<?php echo $excludeTerms; ?>" />

<input class="widefat" id="<?php echo $this->get_field_id( 'hideEmpty' ); ?>" name="<?php echo $this->get_field_name( 'hideEmpty' ); ?>" type="checkbox" <?php echo $hideEmpty?"checked":''; ?> />

<label for="<?php echo $this->get_field_id( 'hideEmpty' ); ?>"><?php _e( 'Hide Empty' ); ?></label>

</p>

<?php

}

public function update( $new_instance, $old_instance ) {

$instance = array();

$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';

$instance['excludeTerms'] = ( ! empty( $new_instance['excludeTerms'] ) ) ? $new_instance['excludeTerms'] : '';

$instance['hideEmpty'] = ( ! empty( $new_instance['hideEmpty'] ) ) ? $new_instance['hideEmpty'] : '';

return $instance;

}