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

144
wp-includes/widgets.php
View File

@ -34,34 +34,49 @@ class WP_Widget {
// 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.
*
* @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
* @since 2.8.0
* @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.');
}
/** Update a particular instance.
/**
* Update a particular instance.
*
* This function should check that $new_instance is set correctly.
* The newly calculated value of $instance should be returned.
* If "false" is returned, the instance won't be saved/updated.
* This function should check that $new_instance is set correctly. The newly-calculated
* value of `$instance` should be returned. If false is returned, the instance won't be
* saved/updated.
*
* @param array $new_instance New settings for this instance as input by the user via form()
* @param array $old_instance Old settings for this instance
* @return array Settings to save or bool false to cancel saving
* @since 2.8.0
* @access public
*
* @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;
}
/** 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) {
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.
/**
* PHP5 constructor
* PHP5 constructor.
*
* @param string $id_base Optional Base ID for the widget, lower case,
* 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 array $widget_options Optional Passed to wp_register_sidebar_widget()
* - description: shown on the configuration page
* - classname
* @param array $control_options Optional Passed to wp_register_widget_control()
* - width: required if more than 250px
* - height: currently not used but may be needed in the future
* @since 2.8.0
* @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 array $widget_options Optional. Widget options. See {@see wp_register_sidebar_widget()} for
* information on accepted arguments. Default empty array.
* @param array $control_options Optional. Widget control options. See {@see wp_register_widget_control()}
* for information on accepted arguments. Default empty 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);
@ -122,8 +138,12 @@ class WP_Widget {
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() {
$settings = $this->get_settings();
$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) {
$this->number = $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
* suspended and widgets should check this to decide whether they should
* store anything persistently to the object cache, to transients, or
* anywhere else.
* Determine whether the current request is inside the Customizer preview.
*
* If true -- the current request is inside the Customizer preview, then
* 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
* @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() {
global $wp_customize;
return ( isset( $wp_customize ) && $wp_customize->is_preview() ) ;
}
/** Generate the actual widget content.
* Just finds the instance and calls widget().
* Do NOT over-ride this function. */
/**
* Generate the actual widget content (Do NOT override).
*
* 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 ) {
if ( is_numeric($widget_args) )
$widget_args = array( 'number' => $widget_args );
@ -362,19 +407,44 @@ class WP_Widget {
return $return;
}
/** Helper function: Registers a single instance. */
public function _register_one($number = -1) {
/**
* 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 ) {
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_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
}
public function save_settings($settings) {
/**
* 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 ) {
$settings['_multiwidget'] = 1;
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() {
$settings = get_option($this->option_name);
if ( false === $settings && isset($this->alt_option_name) )