WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add some missing inline documentation for methods in the `WP_Widget` class in wp-includes/widgets.php. 

Props ericlewis, jazzs3quence.
See #30315.

Built from https://develop.svn.wordpress.org/trunk@30382


git-svn-id: http://core.svn.wordpress.org/trunk@30379 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2014-11-18 22:58:22 +00:00
parent f7648300c8
commit e34a587ea6
1 changed files with 107 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
wp-includes/widgets.php
View File

@ -34,34 +34,49 @@ class WP_Widget {
// Member functions that you must over-ride. // Member functions that you must over-ride.
/** Echo the widget content. /**
* Echo the widget content.
* *
* Subclasses should over-ride this function to generate their widget code. * Subclasses should over-ride this function to generate their widget code.
* *
* @param array $args Display arguments including before_title, after_title, before_widget, and after_widget. * @since 2.8.0
* @param array $instance The settings for the particular instance of the widget * @access public
*
* @param array $args Display arguments including before_title, after_title,
* before_widget, and after_widget.
* @param array $instance The settings for the particular instance of the widget.
*/ */
public function widget( $args, $instance ) { public function widget( $args, $instance ) {
die('function WP_Widget::widget() must be over-ridden in a sub-class.'); die('function WP_Widget::widget() must be over-ridden in a sub-class.');
} }
/** Update a particular instance. /**
* Update a particular instance.
* *
* This function should check that $new_instance is set correctly. * This function should check that $new_instance is set correctly. The newly-calculated
* The newly calculated value of $instance should be returned. * value of `$instance` should be returned. If false is returned, the instance won't be
* If "false" is returned, the instance won't be saved/updated. * saved/updated.
* *
* @param array $new_instance New settings for this instance as input by the user via form() * @since 2.8.0
* @param array $old_instance Old settings for this instance * @access public
* @return array Settings to save or bool false to cancel saving *
* @param array $new_instance New settings for this instance as input by the user via
* {@see WP_Widget::form()}.
* @param array $old_instance Old settings for this instance.
* @return array Settings to save or bool false to cancel saving.
*/ */
public function update( $new_instance, $old_instance ) { public function update( $new_instance, $old_instance ) {
return $new_instance; return $new_instance;
} }
/** Echo the settings update form /**
* Output the settings update form.
* *
* @param array $instance Current settings * @since 2.8.0
* @access public
*
* @param array $instance Current settings.
* @return string Default return is 'noform'.
*/ */
public function form($instance) { public function form($instance) {
echo '<p class="no-options-widget">' . __('There are no options for this widget.') . '</p>'; echo '<p class="no-options-widget">' . __('There are no options for this widget.') . '</p>';
@ -71,17 +86,18 @@ class WP_Widget {
// Functions you'll need to call. // Functions you'll need to call.
/** /**
* PHP5 constructor * PHP5 constructor.
* *
* @param string $id_base Optional Base ID for the widget, lower case, * @since 2.8.0
* if left empty a portion of the widget's class name will be used. Has to be unique. * @access public
*
* @param string $id_base Optional Base ID for the widget, lowercase and unique. If left empty,
* a portion of the widget's class name will be used Has to be unique.
* @param string $name Name for the widget displayed on the configuration page. * @param string $name Name for the widget displayed on the configuration page.
* @param array $widget_options Optional Passed to wp_register_sidebar_widget() * @param array $widget_options Optional. Widget options. See {@see wp_register_sidebar_widget()} for
* - description: shown on the configuration page * information on accepted arguments. Default empty array.
* - classname * @param array $control_options Optional. Widget control options. See {@see wp_register_widget_control()}
* @param array $control_options Optional Passed to wp_register_widget_control() * for information on accepted arguments. Default empty array.
* - width: required if more than 250px
* - height: currently not used but may be needed in the future
*/ */
public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) { public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
$this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base); $this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base);
@ -122,8 +138,12 @@ class WP_Widget {
return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name; return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
} }
// Private Functions. Don't worry about these. /**
* Register all widget instances of this widget class.
*
* @since 2.8.0
* @access private
*/
public function _register() { public function _register() {
$settings = $this->get_settings(); $settings = $this->get_settings();
$empty = true; $empty = true;
@ -146,6 +166,15 @@ class WP_Widget {
} }
} }
/**
* Set the internal order number for the widget instance.
*
* @since 2.8.0
* @access private
*
* @param int $number The unique order number of this widget instance compared to other
* instances of the same class.
*/
public function _set($number) { public function _set($number) {
$this->number = $number; $this->number = $number;
$this->id = $this->id_base . '-' . $number; $this->id = $this->id_base . '-' . $number;
@ -164,23 +193,39 @@ class WP_Widget {
} }
/** /**
* Determine if we're in the Customizer; if true, then the object cache gets * Determine whether the current request is inside the Customizer preview.
* suspended and widgets should check this to decide whether they should *
* store anything persistently to the object cache, to transients, or * If true -- the current request is inside the Customizer preview, then
* anywhere else. * the object cache gets suspended and widgets should check this to decide
* whether they should store anything persistently to the object cache,
* to transients, or anywhere else.
* *
* @since 3.9.0 * @since 3.9.0
* @access public
* *
* @return bool True if Customizer is on, false if not. * @return bool True if within the Customizer preview, false if not.
*/ */
public function is_preview() { public function is_preview() {
global $wp_customize; global $wp_customize;
return ( isset( $wp_customize ) && $wp_customize->is_preview() ) ; return ( isset( $wp_customize ) && $wp_customize->is_preview() ) ;
} }
/** Generate the actual widget content. /**
* Just finds the instance and calls widget(). * Generate the actual widget content (Do NOT override).
* Do NOT over-ride this function. */ *
* Finds the instance and calls {@see WP_Widget::widget()}.
*
* @access public
*
* @param array $args Display arguments. See {@see WP_Widget::widget()} for information
* on accepted arguments.
* @param int|array $widget_args {
* Optional. Internal order number of the widget instance, or array of multi-widget arguments.
* Default 1.
*
* @type int $number Number increment used for multiples of the same widget.
* }
*/
public function display_callback( $args, $widget_args = 1 ) { public function display_callback( $args, $widget_args = 1 ) {
if ( is_numeric($widget_args) ) if ( is_numeric($widget_args) )
$widget_args = array( 'number' => $widget_args ); $widget_args = array( 'number' => $widget_args );
@ -362,19 +407,44 @@ class WP_Widget {
return $return; return $return;
} }
/** Helper function: Registers a single instance. */ /**
* Register an instance of the widget class.
*
* @since 2.8.0
* @access private
*
* @param integer $number Optional. The unique order number of this widget instance
* compared to other instances of the same class. Default -1.
*/
public function _register_one( $number = -1 ) { public function _register_one( $number = -1 ) {
wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) ); wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
_register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) ); _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
_register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) ); _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
} }
/**
* Save the settings for all instances of the widget class.
*
* @since 2.8.0
* @access public
*
* @param array $settings Multi-dimensional array of widget instance settings.
*/
public function save_settings( $settings ) { public function save_settings( $settings ) {
$settings['_multiwidget'] = 1; $settings['_multiwidget'] = 1;
update_option( $this->option_name, $settings ); update_option( $this->option_name, $settings );
} }
/**
* Get the settings for all instances of the widget class.
*
* @since 2.8.0
* @access public
*
* @return array Multi-dimensional array of widget instance settings.
*/
public function get_settings() { public function get_settings() {
$settings = get_option($this->option_name); $settings = get_option($this->option_name);
if ( false === $settings && isset($this->alt_option_name) ) if ( false === $settings && isset($this->alt_option_name) )