[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Widget API: WP_Widget_Categories class
   4   *
   5   * @package WordPress
   6   * @subpackage Widgets
   7   * @since 4.4.0
   8   */
   9  
  10  /**
  11   * Core class used to implement a Categories widget.
  12   *
  13   * @since 2.8.0
  14   *
  15   * @see WP_Widget
  16   */
  17  class WP_Widget_Categories extends WP_Widget {
  18  
  19      /**
  20       * Sets up a new Categories widget instance.
  21       *
  22       * @since 2.8.0
  23       */
  24  	public function __construct() {
  25          $widget_ops = array(
  26              'classname'                   => 'widget_categories',
  27              'description'                 => __( 'A list or dropdown of categories.' ),
  28              'customize_selective_refresh' => true,
  29              'show_instance_in_rest'       => true,
  30          );
  31          parent::__construct( 'categories', __( 'Categories' ), $widget_ops );
  32      }
  33  
  34      /**
  35       * Outputs the content for the current Categories widget instance.
  36       *
  37       * @since 2.8.0
  38       * @since 4.2.0 Creates a unique HTML ID for the `<select>` element
  39       *              if more than one instance is displayed on the page.
  40       *
  41       * @param array $args {
  42       *     Display arguments.
  43       *
  44       *     @type string $before_widget HTML markup to prepend to each widget in the sidebar.
  45       *     @type string $after_widget  HTML markup to append to each widget in the sidebar.
  46       *     @type string $before_title  HTML markup to prepend to the widget title when displayed.
  47       *     @type string $after_title   HTML markup to append to the widget title when displayed.
  48       * }
  49       * @param array $instance {
  50       *     Settings for the current Categories widget instance.
  51       *
  52       *     @type string $title        Widget title.
  53       *     @type 0|1    $count        Whether to show post counts.
  54       *     @type 0|1    $hierarchical Whether to show the category hierarchy.
  55       *     @type 0|1    $dropdown     Whether to display the categories as a drop-down.
  56       * }
  57       */
  58  	public function widget( $args, $instance ) {
  59          static $first_dropdown = true;
  60  
  61          $default_title = __( 'Categories' );
  62          $title         = ! empty( $instance['title'] ) ? $instance['title'] : $default_title;
  63  
  64          /** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
  65          $title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
  66  
  67          /*
  68           * Although update() stores these flags as 0 or 1, they are checked loosely for back-compat:
  69           * the keys are absent for an instance that has not been saved yet, instances saved before
  70           * WordPress 2.8 stored booleans, and the_widget() passes along whatever values its caller
  71           * supplies.
  72           */
  73          $count        = ! empty( $instance['count'] );
  74          $hierarchical = ! empty( $instance['hierarchical'] );
  75          $dropdown     = ! empty( $instance['dropdown'] );
  76  
  77          echo $args['before_widget'];
  78  
  79          if ( $title ) {
  80              echo $args['before_title'] . $title . $args['after_title'];
  81          }
  82  
  83          $cat_args = array(
  84              'orderby'      => 'name',
  85              'show_count'   => $count,
  86              'hierarchical' => $hierarchical,
  87          );
  88  
  89          if ( $dropdown ) {
  90              printf( '<form action="%s" method="get">', esc_url( home_url() ) );
  91              $dropdown_id    = ( $first_dropdown ) ? 'cat' : "{$this->id_base}-dropdown-{$this->number}";
  92              $first_dropdown = false;
  93  
  94              echo '<label class="screen-reader-text" for="' . esc_attr( $dropdown_id ) . '">' . $title . '</label>';
  95  
  96              $cat_args['show_option_none'] = __( 'Select Category' );
  97              $cat_args['id']               = $dropdown_id;
  98  
  99              /**
 100               * Filters the arguments for the Categories widget drop-down.
 101               *
 102               * @since 2.8.0
 103               * @since 4.9.0 Added the `$instance` parameter.
 104               * @since 7.2.0 The `show_count` and `hierarchical` arguments in `$cat_args` are now booleans instead of the numeric strings '0' and '1'.
 105               *
 106               * @see wp_dropdown_categories()
 107               *
 108               * @param array $cat_args {
 109               *     An array of Categories widget drop-down arguments. See {@see wp_dropdown_categories()} for
 110               *     information on additional accepted arguments.
 111               *
 112               *     @type string $orderby          Which column to use for ordering categories. See {@see get_terms()}
 113               *                                    for a list of accepted values. Default 'name'.
 114               *     @type bool   $show_count       Whether to include post counts.
 115               *     @type bool   $hierarchical     Whether to traverse the taxonomy hierarchy.
 116               *     @type string $show_option_none Text to display for showing no categories. Set to 'Select Category'.
 117               *     @type string $id               Value for the 'id' attribute of the select element.
 118               * }
 119               * @param array $instance {
 120               *     Array of settings for the current widget.
 121               *
 122               *     @type string $title        Widget title.
 123               *     @type 0|1    $count        Whether to show post counts.
 124               *     @type 0|1    $hierarchical Whether to show the category hierarchy.
 125               *     @type 0|1    $dropdown     Whether to display the categories as a drop-down.
 126               * }
 127               */
 128              wp_dropdown_categories( apply_filters( 'widget_categories_dropdown_args', $cat_args, $instance ) );
 129  
 130              echo '</form>';
 131  
 132              ob_start();
 133              ?>
 134  
 135  <script>
 136  ( ( dropdownId ) => {
 137      const dropdown = document.getElementById( dropdownId );
 138  	function onSelectChange() {
 139          setTimeout( () => {
 140              if ( 'escape' === dropdown.dataset.lastkey ) {
 141                  return;
 142              }
 143              if ( dropdown.value && parseInt( dropdown.value ) > 0 && dropdown instanceof HTMLSelectElement ) {
 144                  dropdown.parentElement.submit();
 145              }
 146          }, 250 );
 147      }
 148  	function onKeyUp( event ) {
 149          if ( 'Escape' === event.key ) {
 150              dropdown.dataset.lastkey = 'escape';
 151          } else {
 152              delete dropdown.dataset.lastkey;
 153          }
 154      }
 155  	function onClick() {
 156          delete dropdown.dataset.lastkey;
 157      }
 158      dropdown.addEventListener( 'keyup', onKeyUp );
 159      dropdown.addEventListener( 'click', onClick );
 160      dropdown.addEventListener( 'change', onSelectChange );
 161  })( <?php echo wp_json_encode( $dropdown_id, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ); ?> );
 162  </script>
 163  
 164              <?php
 165              wp_print_inline_script_tag( wp_remove_surrounding_empty_script_tags( ob_get_clean() ) . "\n//# sourceURL=" . rawurlencode( __METHOD__ ) );
 166          } else {
 167              $format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
 168  
 169              /** This filter is documented in wp-includes/widgets/class-wp-nav-menu-widget.php */
 170              $format = apply_filters( 'navigation_widgets_format', $format );
 171  
 172              if ( 'html5' === $format ) {
 173                  // The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
 174                  $title      = trim( strip_tags( $title ) );
 175                  $aria_label = $title ? $title : $default_title;
 176                  echo '<nav aria-label="' . esc_attr( $aria_label ) . '">';
 177              }
 178              ?>
 179  
 180              <ul>
 181                  <?php
 182                  $cat_args['title_li'] = '';
 183  
 184                  /**
 185                   * Filters the arguments for the Categories widget.
 186                   *
 187                   * @since 2.8.0
 188                   * @since 4.9.0 Added the `$instance` parameter.
 189                   * @since 7.2.0 The `show_count` and `hierarchical` arguments in `$cat_args` are now booleans instead of the numeric strings '0' and '1'.
 190                   *
 191                   * @param array $cat_args {
 192                   *     An array of Categories widget options. See {@see wp_list_categories()} for information on
 193                   *     additional accepted arguments.
 194                   *
 195                   *     @type string $orderby      Which column to use for ordering categories. See {@see get_terms()}
 196                   *                                for a list of accepted values. Default 'name'.
 197                   *     @type bool   $show_count   Whether to include post counts.
 198                   *     @type bool   $hierarchical Whether to traverse the taxonomy hierarchy.
 199                   *     @type string $title_li     Text to use for the list title `<li>` element. Default empty string.
 200                   * }
 201                   * @param array $instance {
 202                   *     Array of settings for the current widget.
 203                   *
 204                   *     @type string $title        Widget title.
 205                   *     @type 0|1    $count        Whether to show post counts.
 206                   *     @type 0|1    $hierarchical Whether to show the category hierarchy.
 207                   *     @type 0|1    $dropdown     Whether to display the categories as a drop-down.
 208                   * }
 209                   */
 210                  wp_list_categories( apply_filters( 'widget_categories_args', $cat_args, $instance ) );
 211                  ?>
 212              </ul>
 213  
 214              <?php
 215              if ( 'html5' === $format ) {
 216                  echo '</nav>';
 217              }
 218          }
 219  
 220          echo $args['after_widget'];
 221      }
 222  
 223      /**
 224       * Handles updating settings for the current Categories widget instance.
 225       *
 226       * @since 2.8.0
 227       *
 228       * @param array $new_instance {
 229       *     New settings for this instance as input by the user via {@see WP_Widget::form()}. A checkbox
 230       *     submits 'on' when checked and is omitted when unchecked. A saved instance resubmitted
 231       *     through the REST API passes 0 or 1 instead.
 232       *
 233       *     @type string   $title        Widget title.
 234       *     @type 'on'|0|1 $count        Whether to show post counts.
 235       *     @type 'on'|0|1 $hierarchical Whether to show the category hierarchy.
 236       *     @type 'on'|0|1 $dropdown     Whether to display the categories as a drop-down.
 237       * }
 238       * @param array $old_instance {
 239       *     Old settings for this instance.
 240       *
 241       *     @type string $title        Widget title.
 242       *     @type 0|1    $count        Whether to show post counts.
 243       *     @type 0|1    $hierarchical Whether to show the category hierarchy.
 244       *     @type 0|1    $dropdown     Whether to display the categories as a drop-down.
 245       * }
 246       * @return array {
 247       *     Updated settings to save.
 248       *
 249       *     @type string $title        Widget title.
 250       *     @type 0|1    $count        Whether to show post counts.
 251       *     @type 0|1    $hierarchical Whether to show the category hierarchy.
 252       *     @type 0|1    $dropdown     Whether to display the categories as a drop-down.
 253       * }
 254       */
 255  	public function update( $new_instance, $old_instance ) {
 256          $instance                 = $old_instance;
 257          $instance['title']        = sanitize_text_field( $new_instance['title'] ?? '' );
 258          $instance['count']        = ! empty( $new_instance['count'] ) ? 1 : 0;
 259          $instance['hierarchical'] = ! empty( $new_instance['hierarchical'] ) ? 1 : 0;
 260          $instance['dropdown']     = ! empty( $new_instance['dropdown'] ) ? 1 : 0;
 261  
 262          return $instance;
 263      }
 264  
 265      /**
 266       * Outputs the settings form for the Categories widget.
 267       *
 268       * @since 2.8.0
 269       *
 270       * @param array $instance {
 271       *     Current settings.
 272       *
 273       *     @type string $title        Widget title.
 274       *     @type 0|1    $count        Whether to show post counts.
 275       *     @type 0|1    $hierarchical Whether to show the category hierarchy.
 276       *     @type 0|1    $dropdown     Whether to display the categories as a drop-down.
 277       * }
 278       */
 279  	public function form( $instance ) {
 280          // Defaults.
 281          $instance     = wp_parse_args( (array) $instance, array( 'title' => '' ) );
 282          $count        = isset( $instance['count'] ) ? (bool) $instance['count'] : false;
 283          $hierarchical = isset( $instance['hierarchical'] ) ? (bool) $instance['hierarchical'] : false;
 284          $dropdown     = isset( $instance['dropdown'] ) ? (bool) $instance['dropdown'] : false;
 285          ?>
 286          <p>
 287              <label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
 288              <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( $instance['title'] ); ?>" />
 289          </p>
 290  
 291          <p>
 292              <input type="checkbox" class="checkbox" id="<?php echo $this->get_field_id( 'dropdown' ); ?>" name="<?php echo $this->get_field_name( 'dropdown' ); ?>"<?php checked( $dropdown ); ?> />
 293              <label for="<?php echo $this->get_field_id( 'dropdown' ); ?>"><?php _e( 'Display as dropdown' ); ?></label>
 294              <br />
 295  
 296              <input type="checkbox" class="checkbox" id="<?php echo $this->get_field_id( 'count' ); ?>" name="<?php echo $this->get_field_name( 'count' ); ?>"<?php checked( $count ); ?> />
 297              <label for="<?php echo $this->get_field_id( 'count' ); ?>"><?php _e( 'Show post counts' ); ?></label>
 298              <br />
 299  
 300              <input type="checkbox" class="checkbox" id="<?php echo $this->get_field_id( 'hierarchical' ); ?>" name="<?php echo $this->get_field_name( 'hierarchical' ); ?>"<?php checked( $hierarchical ); ?> />
 301              <label for="<?php echo $this->get_field_id( 'hierarchical' ); ?>"><?php _e( 'Show hierarchy' ); ?></label>
 302          </p>
 303          <?php
 304      }
 305  }