wp/wp-includes/class-wp-widget.php
changeset 18 be944660c56a
parent 16 a86126ab1dd4
child 19 3d72ae0968f4
equal deleted inserted replaced
17:34716fd837a4 18:be944660c56a
   150 	 * PHP5 constructor.
   150 	 * PHP5 constructor.
   151 	 *
   151 	 *
   152 	 * @since 2.8.0
   152 	 * @since 2.8.0
   153 	 *
   153 	 *
   154 	 * @param string $id_base         Optional. Base ID for the widget, lowercase and unique. If left empty,
   154 	 * @param string $id_base         Optional. Base ID for the widget, lowercase and unique. If left empty,
   155 	 *                                a portion of the widget's class name will be used. Has to be unique.
   155 	 *                                a portion of the widget's PHP class name will be used. Has to be unique.
   156 	 * @param string $name            Name for the widget displayed on the configuration page.
   156 	 * @param string $name            Name for the widget displayed on the configuration page.
   157 	 * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for
   157 	 * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for
   158 	 *                                information on accepted arguments. Default empty array.
   158 	 *                                information on accepted arguments. Default empty array.
   159 	 * @param array  $control_options Optional. Widget control options. See wp_register_widget_control() for
   159 	 * @param array  $control_options Optional. Widget control options. See wp_register_widget_control() for
   160 	 *                                information on accepted arguments. Default empty array.
   160 	 *                                information on accepted arguments. Default empty array.
   161 	 */
   161 	 */
   162 	public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
   162 	public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
   163 		$this->id_base         = empty( $id_base ) ? preg_replace( '/(wp_)?widget_/', '', strtolower( get_class( $this ) ) ) : strtolower( $id_base );
   163 		if ( ! empty( $id_base ) ) {
       
   164 			$id_base = strtolower( $id_base );
       
   165 		} else {
       
   166 			$id_base = preg_replace( '/(wp_)?widget_/', '', strtolower( get_class( $this ) ) );
       
   167 		}
       
   168 
       
   169 		$this->id_base         = $id_base;
   164 		$this->name            = $name;
   170 		$this->name            = $name;
   165 		$this->option_name     = 'widget_' . $this->id_base;
   171 		$this->option_name     = 'widget_' . $this->id_base;
   166 		$this->widget_options  = wp_parse_args(
   172 		$this->widget_options  = wp_parse_args(
   167 			$widget_options,
   173 			$widget_options,
   168 			array(
   174 			array(
   169 				'classname'                   => $this->option_name,
   175 				'classname'                   => str_replace( '\\', '_', $this->option_name ),
   170 				'customize_selective_refresh' => false,
   176 				'customize_selective_refresh' => false,
   171 			)
   177 			)
   172 		);
   178 		);
   173 		$this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) );
   179 		$this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) );
   174 	}
   180 	}
   180 	 * @deprecated 4.3.0 Use __construct() instead.
   186 	 * @deprecated 4.3.0 Use __construct() instead.
   181 	 *
   187 	 *
   182 	 * @see WP_Widget::__construct()
   188 	 * @see WP_Widget::__construct()
   183 	 *
   189 	 *
   184 	 * @param string $id_base         Optional. Base ID for the widget, lowercase and unique. If left empty,
   190 	 * @param string $id_base         Optional. Base ID for the widget, lowercase and unique. If left empty,
   185 	 *                                a portion of the widget's class name will be used. Has to be unique.
   191 	 *                                a portion of the widget's PHP class name will be used. Has to be unique.
   186 	 * @param string $name            Name for the widget displayed on the configuration page.
   192 	 * @param string $name            Name for the widget displayed on the configuration page.
   187 	 * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for
   193 	 * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for
   188 	 *                                information on accepted arguments. Default empty array.
   194 	 *                                information on accepted arguments. Default empty array.
   189 	 * @param array  $control_options Optional. Widget control options. See wp_register_widget_control() for
   195 	 * @param array  $control_options Optional. Widget control options. See wp_register_widget_control() for
   190 	 *                                information on accepted arguments. Default empty array.
   196 	 *                                information on accepted arguments. Default empty array.
   201 	 * to be saved by update()
   207 	 * to be saved by update()
   202 	 *
   208 	 *
   203 	 * @since 2.8.0
   209 	 * @since 2.8.0
   204 	 * @since 4.4.0 Array format field names are now accepted.
   210 	 * @since 4.4.0 Array format field names are now accepted.
   205 	 *
   211 	 *
   206 	 * @param string $field_name Field name
   212 	 * @param string $field_name Field name.
   207 	 * @return string Name attribute for $field_name
   213 	 * @return string Name attribute for `$field_name`.
   208 	 */
   214 	 */
   209 	public function get_field_name( $field_name ) {
   215 	public function get_field_name( $field_name ) {
   210 		$pos = strpos( $field_name, '[' );
   216 		$pos = strpos( $field_name, '[' );
   211 		if ( false === $pos ) {
   217 
   212 			return 'widget-' . $this->id_base . '[' . $this->number . '][' . $field_name . ']';
   218 		if ( false !== $pos ) {
       
   219 			// Replace the first occurrence of '[' with ']['.
       
   220 			$field_name = '[' . substr_replace( $field_name, '][', $pos, strlen( '[' ) );
   213 		} else {
   221 		} else {
   214 			return 'widget-' . $this->id_base . '[' . $this->number . '][' . substr_replace( $field_name, '][', $pos, strlen( '[' ) );
   222 			$field_name = '[' . $field_name . ']';
   215 		}
   223 		}
       
   224 
       
   225 		return 'widget-' . $this->id_base . '[' . $this->number . ']' . $field_name;
   216 	}
   226 	}
   217 
   227 
   218 	/**
   228 	/**
   219 	 * Constructs id attributes for use in WP_Widget::form() fields.
   229 	 * Constructs id attributes for use in WP_Widget::form() fields.
   220 	 *
   230 	 *
   226 	 *
   236 	 *
   227 	 * @param string $field_name Field name.
   237 	 * @param string $field_name Field name.
   228 	 * @return string ID attribute for `$field_name`.
   238 	 * @return string ID attribute for `$field_name`.
   229 	 */
   239 	 */
   230 	public function get_field_id( $field_name ) {
   240 	public function get_field_id( $field_name ) {
   231 		return 'widget-' . $this->id_base . '-' . $this->number . '-' . trim( str_replace( array( '[]', '[', ']' ), array( '', '-', '' ), $field_name ), '-' );
   241 		$field_name = str_replace( array( '[]', '[', ']' ), array( '', '-', '' ), $field_name );
       
   242 		$field_name = trim( $field_name, '-' );
       
   243 
       
   244 		return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
   232 	}
   245 	}
   233 
   246 
   234 	/**
   247 	/**
   235 	 * Register all widget instances of this widget class.
   248 	 * Register all widget instances of this widget class.
   236 	 *
   249 	 *
   361 			 * Returning false will effectively short-circuit display of the widget.
   374 			 * Returning false will effectively short-circuit display of the widget.
   362 			 *
   375 			 *
   363 			 * @since 2.8.0
   376 			 * @since 2.8.0
   364 			 *
   377 			 *
   365 			 * @param array     $instance The current widget instance's settings.
   378 			 * @param array     $instance The current widget instance's settings.
   366 			 * @param WP_Widget $this     The current widget instance.
   379 			 * @param WP_Widget $widget   The current widget instance.
   367 			 * @param array     $args     An array of default widget arguments.
   380 			 * @param array     $args     An array of default widget arguments.
   368 			 */
   381 			 */
   369 			$instance = apply_filters( 'widget_display_callback', $instance, $this, $args );
   382 			$instance = apply_filters( 'widget_display_callback', $instance, $this, $args );
   370 
   383 
   371 			if ( false === $instance ) {
   384 			if ( false === $instance ) {
   455 				 * @since 2.8.0
   468 				 * @since 2.8.0
   456 				 *
   469 				 *
   457 				 * @param array     $instance     The current widget instance's settings.
   470 				 * @param array     $instance     The current widget instance's settings.
   458 				 * @param array     $new_instance Array of new widget settings.
   471 				 * @param array     $new_instance Array of new widget settings.
   459 				 * @param array     $old_instance Array of old widget settings.
   472 				 * @param array     $old_instance Array of old widget settings.
   460 				 * @param WP_Widget $this         The current widget instance.
   473 				 * @param WP_Widget $widget       The current widget instance.
   461 				 */
   474 				 */
   462 				$instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this );
   475 				$instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this );
       
   476 
   463 				if ( false !== $instance ) {
   477 				if ( false !== $instance ) {
   464 					$all_instances[ $number ] = $instance;
   478 					$all_instances[ $number ] = $instance;
   465 				}
   479 				}
   466 
   480 
   467 				break; // Run only once.
   481 				break; // Run only once.
   508 		 * Returning false effectively short-circuits display of the control form.
   522 		 * Returning false effectively short-circuits display of the control form.
   509 		 *
   523 		 *
   510 		 * @since 2.8.0
   524 		 * @since 2.8.0
   511 		 *
   525 		 *
   512 		 * @param array     $instance The current widget instance's settings.
   526 		 * @param array     $instance The current widget instance's settings.
   513 		 * @param WP_Widget $this     The current widget instance.
   527 		 * @param WP_Widget $widget   The current widget instance.
   514 		 */
   528 		 */
   515 		$instance = apply_filters( 'widget_form_callback', $instance, $this );
   529 		$instance = apply_filters( 'widget_form_callback', $instance, $this );
   516 
   530 
   517 		$return = null;
   531 		$return = null;
       
   532 
   518 		if ( false !== $instance ) {
   533 		if ( false !== $instance ) {
   519 			$return = $this->form( $instance );
   534 			$return = $this->form( $instance );
   520 
   535 
   521 			/**
   536 			/**
   522 			 * Fires at the end of the widget control form.
   537 			 * Fires at the end of the widget control form.
   528 			 * Note: If the widget has no form, the text echoed from the default
   543 			 * Note: If the widget has no form, the text echoed from the default
   529 			 * form method can be hidden using CSS.
   544 			 * form method can be hidden using CSS.
   530 			 *
   545 			 *
   531 			 * @since 2.8.0
   546 			 * @since 2.8.0
   532 			 *
   547 			 *
   533 			 * @param WP_Widget $this     The widget instance (passed by reference).
   548 			 * @param WP_Widget $widget   The widget instance (passed by reference).
   534 			 * @param null      $return   Return null if new fields are added.
   549 			 * @param null      $return   Return null if new fields are added.
   535 			 * @param array     $instance An array of the widget's settings.
   550 			 * @param array     $instance An array of the widget's settings.
   536 			 */
   551 			 */
   537 			do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
   552 			do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
   538 		}
   553 		}
       
   554 
   539 		return $return;
   555 		return $return;
   540 	}
   556 	}
   541 
   557 
   542 	/**
   558 	/**
   543 	 * Registers an instance of the widget class.
   559 	 * Registers an instance of the widget class.
   544 	 *
   560 	 *
   545 	 * @since 2.8.0
   561 	 * @since 2.8.0
   546 	 *
   562 	 *
   547 	 * @param integer $number Optional. The unique order number of this widget instance
   563 	 * @param int $number Optional. The unique order number of this widget instance
   548 	 *                        compared to other instances of the same class. Default -1.
   564 	 *                    compared to other instances of the same class. Default -1.
   549 	 */
   565 	 */
   550 	public function _register_one( $number = -1 ) {
   566 	public function _register_one( $number = -1 ) {
   551 		wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
   567 		wp_register_sidebar_widget(
   552 		_register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
   568 			$this->id,
   553 		_register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
   569 			$this->name,
       
   570 			$this->_get_display_callback(),
       
   571 			$this->widget_options,
       
   572 			array( 'number' => $number )
       
   573 		);
       
   574 
       
   575 		_register_widget_update_callback(
       
   576 			$this->id_base,
       
   577 			$this->_get_update_callback(),
       
   578 			$this->control_options,
       
   579 			array( 'number' => -1 )
       
   580 		);
       
   581 
       
   582 		_register_widget_form_callback(
       
   583 			$this->id,
       
   584 			$this->name,
       
   585 			$this->_get_form_callback(),
       
   586 			$this->control_options,
       
   587 			array( 'number' => $number )
       
   588 		);
   554 	}
   589 	}
   555 
   590 
   556 	/**
   591 	/**
   557 	 * Saves the settings for all instances of the widget class.
   592 	 * Saves the settings for all instances of the widget class.
   558 	 *
   593 	 *
   593 			// Old format, convert if single widget.
   628 			// Old format, convert if single widget.
   594 			$settings = wp_convert_widget_settings( $this->id_base, $this->option_name, $settings );
   629 			$settings = wp_convert_widget_settings( $this->id_base, $this->option_name, $settings );
   595 		}
   630 		}
   596 
   631 
   597 		unset( $settings['_multiwidget'], $settings['__i__'] );
   632 		unset( $settings['_multiwidget'], $settings['__i__'] );
       
   633 
   598 		return $settings;
   634 		return $settings;
   599 	}
   635 	}
   600 }
   636 }