wp-includes/class-wp-widget.php

   1 <?php
   2 /**
   3  * Widget API: WP_Widget base class
   4  *
   5  * @package WordPress
   6  * @subpackage Widgets
   7  * @since 4.4.0
   8  */
   9
  10 /**
  11  * Core base class extended to register widgets.
  12  *
  13  * This class must be extended for each widget and WP_Widget::widget(), WP_Widget::update()
  14  * and WP_Widget::form() need to be overridden.
  15  *
  16  * @since 2.8.0
  17  * @since 4.4.0 Moved to its own file from wp-includes/widgets.php
  18  */
  19 class WP_Widget {
  20
  21         /**
  22          * Root ID for all widgets of this type.
  23          *
  24          * @since 2.8.0
  25          * @access public
  26          * @var mixed|string
  27          */
  28         public $id_base;
  29
  30         /**
  31          * Name for this widget type.
  32          *
  33          * @since 2.8.0
  34          * @access public
  35          * @var string
  36          */
  37         public $name;
  38
  39         /**
  40          * Option array passed to wp_register_sidebar_widget().
  41          *
  42          * @since 2.8.0
  43          * @access public
  44          * @var array
  45          */
  46         public $widget_options;
  47
  48         /**
  49          * Option array passed to wp_register_widget_control().
  50          *
  51          * @since 2.8.0
  52          * @access public
  53          * @var array
  54          */
  55         public $control_options;
  56
  57         /**
  58          * Unique ID number of the current instance.
  59          *
  60          * @since 2.8.0
  61          * @access public
  62          * @var bool|int
  63          */
  64         public $number = false;
  65
  66         /**
  67          * Unique ID string of the current instance (id_base-number).
  68          *
  69          * @since 2.8.0
  70          * @access public
  71          * @var bool|string
  72          */
  73         public $id = false;
  74
  75         /**
  76          * Whether the widget data has been updated.
  77          *
  78          * Set to true when the data is updated after a POST submit - ensures it does
  79          * not happen twice.
  80          *
  81          * @since 2.8.0
  82          * @access public
  83          * @var bool
  84          */
  85         public $updated = false;
  86
  87         //
  88         // Member functions that must be overriden by subclasses.
  89         //
  90
  91         /**
  92          * Echoes the widget content.
  93          *
  94          * Sub-classes should over-ride this function to generate their widget code.
  95          *
  96          * @since 2.8.0
  97          * @access public
  98          *
  99          * @param array $args     Display arguments including 'before_title', 'after_title',
 100          *                        'before_widget', and 'after_widget'.
 101          * @param array $instance The settings for the particular instance of the widget.
 102          */
 103         public function widget( $args, $instance ) {
 104                 die('function WP_Widget::widget() must be over-ridden in a sub-class.');
 105         }
 106
 107         /**
 108          * Updates a particular instance of a widget.
 109          *
 110          * This function should check that `$new_instance` is set correctly. The newly-calculated
 111          * value of `$instance` should be returned. If false is returned, the instance won't be
 112          * saved/updated.
 113          *
 114          * @since 2.8.0
 115          * @access public
 116          *
 117          * @param array $new_instance New settings for this instance as input by the user via
 118          *                            WP_Widget::form().
 119          * @param array $old_instance Old settings for this instance.
 120          * @return array Settings to save or bool false to cancel saving.
 121          */
 122         public function update( $new_instance, $old_instance ) {
 123                 return $new_instance;
 124         }
 125
 126         /**
 127          * Outputs the settings update form.
 128          *
 129          * @since 2.8.0
 130          * @access public
 131          *
 132          * @param array $instance Current settings.
 133          * @return string Default return is 'noform'.
 134          */
 135         public function form( $instance ) {
 136                 echo '<p class="no-options-widget">' . __('There are no options for this widget.') . '</p>';
 137                 return 'noform';
 138         }
 139
 140         // Functions you'll need to call.
 141
 142         /**
 143          * PHP5 constructor.
 144          *
 145          * @since 2.8.0
 146          * @access public
 147          *
 148          * @param string $id_base         Optional Base ID for the widget, lowercase and unique. If left empty,
 149          *                                a portion of the widget's class name will be used Has to be unique.
 150          * @param string $name            Name for the widget displayed on the configuration page.
 151          * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for information
 152          *                                on accepted arguments. Default empty array.
 153          * @param array  $control_options Optional. Widget control options. See wp_register_widget_control() for
 154          *                                information on accepted arguments. Default empty array.
 155          */
 156         public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
 157                 $this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base);
 158                 $this->name = $name;
 159                 $this->option_name = 'widget_' . $this->id_base;
 160                 $this->widget_options = wp_parse_args( $widget_options, array( 'classname' => $this->option_name, 'customize_selective_refresh' => false ) );
 161                 $this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) );
 162         }
 163
 164         /**
 165          * PHP4 constructor.
 166          *
 167          * @since 2.8.0
 168          * @access public
 169          *
 170          * @see __construct()
 171          *
 172          * @param string $id_base         Optional Base ID for the widget, lowercase and unique. If left empty,
 173          *                                a portion of the widget's class name will be used Has to be unique.
 174          * @param string $name            Name for the widget displayed on the configuration page.
 175          * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for information
 176          *                                on accepted arguments. Default empty array.
 177          * @param array  $control_options Optional. Widget control options. See wp_register_widget_control() for
 178          *                                information on accepted arguments. Default empty array.
 179          */
 180         public function WP_Widget( $id_base, $name, $widget_options = array(), $control_options = array() ) {
 181                 _deprecated_constructor( 'WP_Widget', '4.3.0', get_class( $this ) );
 182                 WP_Widget::__construct( $id_base, $name, $widget_options, $control_options );
 183         }
 184
 185         /**
 186          * Constructs name attributes for use in form() fields
 187          *
 188          * This function should be used in form() methods to create name attributes for fields
 189          * to be saved by update()
 190          *
 191          * @since 2.8.0
 192          * @since 4.4.0 Array format field names are now accepted.
 193          * @access public
 194          *
 195          * @param string $field_name Field name
 196          * @return string Name attribute for $field_name
 197          */
 198         public function get_field_name($field_name) {
 199                 if ( false === $pos = strpos( $field_name, '[' ) ) {
 200                         return 'widget-' . $this->id_base . '[' . $this->number . '][' . $field_name . ']';
 201                 } else {
 202                         return 'widget-' . $this->id_base . '[' . $this->number . '][' . substr_replace( $field_name, '][', $pos, strlen( '[' ) );
 203                 }
 204         }
 205
 206         /**
 207          * Constructs id attributes for use in WP_Widget::form() fields.
 208          *
 209          * This function should be used in form() methods to create id attributes
 210          * for fields to be saved by WP_Widget::update().
 211          *
 212          * @since 2.8.0
 213          * @since 4.4.0 Array format field IDs are now accepted.
 214          * @access public
 215          *
 216          * @param string $field_name Field name.
 217          * @return string ID attribute for `$field_name`.
 218          */
 219         public function get_field_id( $field_name ) {
 220                 return 'widget-' . $this->id_base . '-' . $this->number . '-' . trim( str_replace( array( '[]', '[', ']' ), array( '', '-', '' ), $field_name ), '-' );
 221         }
 222
 223         /**
 224          * Register all widget instances of this widget class.
 225          *
 226          * @since 2.8.0
 227          * @access public
 228          */
 229         public function _register() {
 230                 $settings = $this->get_settings();
 231                 $empty = true;
 232
 233                 // When $settings is an array-like object, get an intrinsic array for use with array_keys().
 234                 if ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) {
 235                         $settings = $settings->getArrayCopy();
 236                 }
 237
 238                 if ( is_array( $settings ) ) {
 239                         foreach ( array_keys( $settings ) as $number ) {
 240                                 if ( is_numeric( $number ) ) {
 241                                         $this->_set( $number );
 242                                         $this->_register_one( $number );
 243                                         $empty = false;
 244                                 }
 245                         }
 246                 }
 247
 248                 if ( $empty ) {
 249                         // If there are none, we register the widget's existence with a generic template.
 250                         $this->_set( 1 );
 251                         $this->_register_one();
 252                 }
 253         }
 254
 255         /**
 256          * Sets the internal order number for the widget instance.
 257          *
 258          * @since 2.8.0
 259          * @access public
 260          *
 261          * @param int $number The unique order number of this widget instance compared to other
 262          *                    instances of the same class.
 263          */
 264         public function _set($number) {
 265                 $this->number = $number;
 266                 $this->id = $this->id_base . '-' . $number;
 267         }
 268
 269         /**
 270          * Retrieves the widget display callback.
 271          *
 272          * @since 2.8.0
 273          * @access public
 274          *
 275          * @return callable Display callback.
 276          */
 277         public function _get_display_callback() {
 278                 return array($this, 'display_callback');
 279         }
 280
 281         /**
 282          * Retrieves the widget update callback.
 283          *
 284          * @since 2.8.0
 285          * @access public
 286          *
 287          * @return callable Update callback.
 288          */
 289         public function _get_update_callback() {
 290                 return array($this, 'update_callback');
 291         }
 292
 293         /**
 294          * Retrieves the form callback.
 295          *
 296          * @since 2.8.0
 297          * @access public
 298          *
 299          * @return callable Form callback.
 300          */
 301         public function _get_form_callback() {
 302                 return array($this, 'form_callback');
 303         }
 304
 305         /**
 306          * Determines whether the current request is inside the Customizer preview.
 307          *
 308          * If true -- the current request is inside the Customizer preview, then
 309          * the object cache gets suspended and widgets should check this to decide
 310          * whether they should store anything persistently to the object cache,
 311          * to transients, or anywhere else.
 312          *
 313          * @since 3.9.0
 314          * @access public
 315          *
 316          * @global WP_Customize_Manager $wp_customize
 317          *
 318          * @return bool True if within the Customizer preview, false if not.
 319          */
 320         public function is_preview() {
 321                 global $wp_customize;
 322                 return ( isset( $wp_customize ) && $wp_customize->is_preview() ) ;
 323         }
 324
 325         /**
 326          * Generates the actual widget content (Do NOT override).
 327          *
 328          * Finds the instance and calls WP_Widget::widget().
 329          *
 330          * @since 2.8.0
 331          * @access public
 332          *
 333          * @param array     $args        Display arguments. See WP_Widget::widget() for information
 334          *                               on accepted arguments.
 335          * @param int|array $widget_args {
 336          *     Optional. Internal order number of the widget instance, or array of multi-widget arguments.
 337          *     Default 1.
 338          *
 339          *     @type int $number Number increment used for multiples of the same widget.
 340          * }
 341          */
 342         public function display_callback( $args, $widget_args = 1 ) {
 343                 if ( is_numeric( $widget_args ) ) {
 344                         $widget_args = array( 'number' => $widget_args );
 345                 }
 346
 347                 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
 348                 $this->_set( $widget_args['number'] );
 349                 $instances = $this->get_settings();
 350
 351                 if ( array_key_exists( $this->number, $instances ) ) {
 352                         $instance = $instances[ $this->number ];
 353
 354                         /**
 355                          * Filter the settings for a particular widget instance.
 356                          *
 357                          * Returning false will effectively short-circuit display of the widget.
 358                          *
 359                          * @since 2.8.0
 360                          *
 361                          * @param array     $instance The current widget instance's settings.
 362                          * @param WP_Widget $this     The current widget instance.
 363                          * @param array     $args     An array of default widget arguments.
 364                          */
 365                         $instance = apply_filters( 'widget_display_callback', $instance, $this, $args );
 366
 367                         if ( false === $instance ) {
 368                                 return;
 369                         }
 370
 371                         $was_cache_addition_suspended = wp_suspend_cache_addition();
 372                         if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
 373                                 wp_suspend_cache_addition( true );
 374                         }
 375
 376                         $this->widget( $args, $instance );
 377
 378                         if ( $this->is_preview() ) {
 379                                 wp_suspend_cache_addition( $was_cache_addition_suspended );
 380                         }
 381                 }
 382         }
 383
 384         /**
 385          * Handles changed settings (Do NOT override).
 386          *
 387          * @since 2.8.0
 388          * @access public
 389          *
 390          * @global array $wp_registered_widgets
 391          *
 392          * @param int $deprecated Not used.
 393          */
 394         public function update_callback( $deprecated = 1 ) {
 395                 global $wp_registered_widgets;
 396
 397                 $all_instances = $this->get_settings();
 398
 399                 // We need to update the data
 400                 if ( $this->updated )
 401                         return;
 402
 403                 if ( isset($_POST['delete_widget']) && $_POST['delete_widget'] ) {
 404                         // Delete the settings for this instance of the widget
 405                         if ( isset($_POST['the-widget-id']) )
 406                                 $del_id = $_POST['the-widget-id'];
 407                         else
 408                                 return;
 409
 410                         if ( isset($wp_registered_widgets[$del_id]['params'][0]['number']) ) {
 411                                 $number = $wp_registered_widgets[$del_id]['params'][0]['number'];
 412
 413                                 if ( $this->id_base . '-' . $number == $del_id )
 414                                         unset($all_instances[$number]);
 415                         }
 416                 } else {
 417                         if ( isset($_POST['widget-' . $this->id_base]) && is_array($_POST['widget-' . $this->id_base]) ) {
 418                                 $settings = $_POST['widget-' . $this->id_base];
 419                         } elseif ( isset($_POST['id_base']) && $_POST['id_base'] == $this->id_base ) {
 420                                 $num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number'];
 421                                 $settings = array( $num => array() );
 422                         } else {
 423                                 return;
 424                         }
 425
 426                         foreach ( $settings as $number => $new_instance ) {
 427                                 $new_instance = stripslashes_deep($new_instance);
 428                                 $this->_set($number);
 429
 430                                 $old_instance = isset($all_instances[$number]) ? $all_instances[$number] : array();
 431
 432                                 $was_cache_addition_suspended = wp_suspend_cache_addition();
 433                                 if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
 434                                         wp_suspend_cache_addition( true );
 435                                 }
 436
 437                                 $instance = $this->update( $new_instance, $old_instance );
 438
 439                                 if ( $this->is_preview() ) {
 440                                         wp_suspend_cache_addition( $was_cache_addition_suspended );
 441                                 }
 442
 443                                 /**
 444                                  * Filter a widget's settings before saving.
 445                                  *
 446                                  * Returning false will effectively short-circuit the widget's ability
 447                                  * to update settings.
 448                                  *
 449                                  * @since 2.8.0
 450                                  *
 451                                  * @param array     $instance     The current widget instance's settings.
 452                                  * @param array     $new_instance Array of new widget settings.
 453                                  * @param array     $old_instance Array of old widget settings.
 454                                  * @param WP_Widget $this         The current widget instance.
 455                                  */
 456                                 $instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this );
 457                                 if ( false !== $instance ) {
 458                                         $all_instances[$number] = $instance;
 459                                 }
 460
 461                                 break; // run only once
 462                         }
 463                 }
 464
 465                 $this->save_settings($all_instances);
 466                 $this->updated = true;
 467         }
 468
 469         /**
 470          * Generates the widget control form (Do NOT override).
 471          *
 472          * @since 2.8.0
 473          * @access public
 474          *
 475          * @param int|array $widget_args {
 476          *     Optional. Internal order number of the widget instance, or array of multi-widget arguments.
 477          *     Default 1.
 478          *
 479          *     @type int $number Number increment used for multiples of the same widget.
 480          * }
 481          * @return string|null
 482          */
 483         public function form_callback( $widget_args = 1 ) {
 484                 if ( is_numeric($widget_args) )
 485                         $widget_args = array( 'number' => $widget_args );
 486
 487                 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
 488                 $all_instances = $this->get_settings();
 489
 490                 if ( -1 == $widget_args['number'] ) {
 491                         // We echo out a form where 'number' can be set later
 492                         $this->_set('__i__');
 493                         $instance = array();
 494                 } else {
 495                         $this->_set($widget_args['number']);
 496                         $instance = $all_instances[ $widget_args['number'] ];
 497                 }
 498
 499                 /**
 500                  * Filter the widget instance's settings before displaying the control form.
 501                  *
 502                  * Returning false effectively short-circuits display of the control form.
 503                  *
 504                  * @since 2.8.0
 505                  *
 506                  * @param array     $instance The current widget instance's settings.
 507                  * @param WP_Widget $this     The current widget instance.
 508                  */
 509                 $instance = apply_filters( 'widget_form_callback', $instance, $this );
 510
 511                 $return = null;
 512                 if ( false !== $instance ) {
 513                         $return = $this->form($instance);
 514
 515                         /**
 516                          * Fires at the end of the widget control form.
 517                          *
 518                          * Use this hook to add extra fields to the widget form. The hook
 519                          * is only fired if the value passed to the 'widget_form_callback'
 520                          * hook is not false.
 521                          *
 522                          * Note: If the widget has no form, the text echoed from the default
 523                          * form method can be hidden using CSS.
 524                          *
 525                          * @since 2.8.0
 526                          *
 527                          * @param WP_Widget $this     The widget instance, passed by reference.
 528                          * @param null      $return   Return null if new fields are added.
 529                          * @param array     $instance An array of the widget's settings.
 530                          */
 531                         do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
 532                 }
 533                 return $return;
 534         }
 535
 536         /**
 537          * Registers an instance of the widget class.
 538          *
 539          * @since 2.8.0
 540          * @access public
 541          *
 542          * @param integer $number Optional. The unique order number of this widget instance
 543          *                        compared to other instances of the same class. Default -1.
 544          */
 545         public function _register_one( $number = -1 ) {
 546                 wp_register_sidebar_widget(     $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
 547                 _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
 548                 _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
 549         }
 550
 551         /**
 552          * Saves the settings for all instances of the widget class.
 553          *
 554          * @since 2.8.0
 555          * @access public
 556          *
 557          * @param array $settings Multi-dimensional array of widget instance settings.
 558          */
 559         public function save_settings( $settings ) {
 560                 $settings['_multiwidget'] = 1;
 561                 update_option( $this->option_name, $settings );
 562         }
 563
 564         /**
 565          * Retrieves the settings for all instances of the widget class.
 566          *
 567          * @since 2.8.0
 568          * @access public
 569          *
 570          * @return array Multi-dimensional array of widget instance settings.
 571          */
 572         public function get_settings() {
 573
 574                 $settings = get_option( $this->option_name );
 575
 576                 if ( false === $settings ) {
 577                         if ( isset( $this->alt_option_name ) ) {
 578                                 $settings = get_option( $this->alt_option_name );
 579                         } else {
 580                                 // Save an option so it can be autoloaded next time.
 581                                 $this->save_settings( array() );
 582                         }
 583                 }
 584
 585                 if ( ! is_array( $settings ) && ! ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) ) {
 586                         $settings = array();
 587                 }
 588
 589                 if ( ! empty( $settings ) && ! isset( $settings['_multiwidget'] ) ) {
 590                         // Old format, convert if single widget.
 591                         $settings = wp_convert_widget_settings( $this->id_base, $this->option_name, $settings );
 592                 }
 593
 594                 unset( $settings['_multiwidget'], $settings['__i__'] );
 595                 return $settings;
 596         }
 597 }