Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2025-01-05 16:08:12 +01:00
Code Issues Projects Releases Wiki Activity

Inline documentation for hooks in wp-includes/widgets.php.

Browse Source 
Props eliorivero and Nessworthy for the initial patches. Props kpdesign.
Fixes #27129.

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


git-svn-id: http://core.svn.wordpress.org/trunk@27701 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2014-03-31 07:30:16 +00:00
parent 01d2062af3
commit 7efc48c365
1 changed files with 102 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
wp-includes/widgets.php
View File

@ -176,7 +176,18 @@ class WP_Widget {
if ( array_key_exists( $this->number, $instance ) ) { if ( array_key_exists( $this->number, $instance ) ) {
$instance = $instance[$this->number]; $instance = $instance[$this->number];
// filters the widget's settings, return false to stop displaying the widget
/**
* Filter the settings for a particular widget instance.
*
* Returning false will effectively short-circuit display of the widget.
*
* @since 2.8.0
*
* @param array $instance The current widget instance's settings.
* @param WP_Widget $this The current widget instance.
* @param array $args An array of default widget arguments.
*/
$instance = apply_filters( 'widget_display_callback', $instance, $this, $args ); $instance = apply_filters( 'widget_display_callback', $instance, $this, $args );
if ( false !== $instance ) if ( false !== $instance )
$this->widget($args, $instance); $this->widget($args, $instance);
@ -232,7 +243,19 @@ class WP_Widget {
$instance = $this->update($new_instance, $old_instance); $instance = $this->update($new_instance, $old_instance);
// filters the widget's settings before saving, return false to cancel saving (keep the old settings if updating) /**
* Filter a widget's settings before saving.
*
* Returning false will effectively short-circuit the widget's ability
* to update settings.
*
* @since 2.8.0
*
* @param array $instance The current widget instance's settings.
* @param array $new_instance Array of new widget settings.
* @param array $old_instance Array of old widget settings.
* @param WP_Widget $this The current widget instance.
*/
$instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this ); $instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this );
if ( false !== $instance ) if ( false !== $instance )
$all_instances[$number] = $instance; $all_instances[$number] = $instance;
@ -245,8 +268,11 @@ class WP_Widget {
$this->updated = true; $this->updated = true;
} }
/** Generate the control form. /**
* Do NOT over-ride this function. */ * Generate the control form.
*
* Do NOT over-ride this function.
*/
function form_callback( $widget_args = 1 ) { function form_callback( $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 );
@ -263,14 +289,38 @@ class WP_Widget {
$instance = $all_instances[ $widget_args['number'] ]; $instance = $all_instances[ $widget_args['number'] ];
} }
// filters the widget admin form before displaying, return false to stop displaying it /**
* Filter the widget instance's settings before displaying the control form.
*
* Returning false effectively short-circuits display of the control form.
*
* @since 2.8.0
*
* @param array $instance The current widget instance's settings.
* @param WP_Widget $this The current widget instance.
*/
$instance = apply_filters( 'widget_form_callback', $instance, $this ); $instance = apply_filters( 'widget_form_callback', $instance, $this );
$return = null; $return = null;
if ( false !== $instance ) { if ( false !== $instance ) {
$return = $this->form($instance); $return = $this->form($instance);
// add extra fields in the widget form - be sure to set $return to null if you add any
// if the widget has no form the text echoed from the default form method can be hidden using css /**
* Fires at the end of the widget control form.
*
* Use this hook to add extra fields to the widget form. The hook
* is only fired if the value passed to the 'widget_form_callback'
* hook is not false.
*
* Note: If the widget has no form, the text echoed from the default
* form method can be hidden using CSS.
*
* @since 2.8.0
*
* @param WP_Widget $this The widget instance, passed by reference.
* @param null $return Return null if new fields are added.
* @param array $instance An array of the widget's settings.
*/
do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) ); do_action_ref_array( 'in_widget_form', array( &$this, &$return, $instance ) );
} }
return $return; return $return;
@ -572,6 +622,13 @@ function register_sidebar($args = array()) {
add_theme_support('widgets'); add_theme_support('widgets');
/**
* Fires once a sidebar has been registered.
*
* @since 3.0.0
*
* @param array $sidebar Parsed arguments for the registered sidebar.
*/
do_action( 'register_sidebar', $sidebar ); do_action( 'register_sidebar', $sidebar );
return $sidebar['id']; return $sidebar['id'];
@ -645,6 +702,14 @@ function wp_register_sidebar_widget($id, $name, $output_callback, $options = arr
$widget = array_merge($widget, $options); $widget = array_merge($widget, $options);
if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) ) { if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) ) {
/**
* Fires once for each registered widget.
*
* @since 3.0.0
*
* @param array $widget An array of default widget arguments.
*/
do_action( 'wp_register_sidebar_widget', $widget ); do_action( 'wp_register_sidebar_widget', $widget );
$wp_registered_widgets[$id] = $widget; $wp_registered_widgets[$id] = $widget;
} }
@ -701,6 +766,14 @@ function wp_sidebar_description( $id ) {
* @param int|string $id Widget ID. * @param int|string $id Widget ID.
*/ */
function wp_unregister_sidebar_widget($id) { function wp_unregister_sidebar_widget($id) {
/**
* Fires just before a widget is removed from a sidebar.
*
* @since 3.0.0
*
* @param int $id The widget ID.
*/
do_action( 'wp_unregister_sidebar_widget', $id ); do_action( 'wp_unregister_sidebar_widget', $id );
wp_register_sidebar_widget($id, '', ''); wp_register_sidebar_widget($id, '', '');
@ -1128,6 +1201,13 @@ function wp_get_sidebars_widgets($deprecated = true) {
if ( is_array( $sidebars_widgets ) && isset($sidebars_widgets['array_version']) ) if ( is_array( $sidebars_widgets ) && isset($sidebars_widgets['array_version']) )
unset($sidebars_widgets['array_version']); unset($sidebars_widgets['array_version']);
/**
* Filter the list of sidebars and their widgets.
*
* @since 2.7.0
*
* @param array $sidebars_widgets An associative array of sidebars and their widgets.
*/
$sidebars_widgets = apply_filters( 'sidebars_widgets', $sidebars_widgets ); $sidebars_widgets = apply_filters( 'sidebars_widgets', $sidebars_widgets );
return $sidebars_widgets; return $sidebars_widgets;
} }
@ -1224,7 +1304,7 @@ function wp_convert_widget_settings($base_name, $option_name, $settings) {
} }
/** /**
* Output an arbitrary widget as a template tag * Output an arbitrary widget as a template tag.
* *
* @since 2.8.0 * @since 2.8.0
* *
@ -1246,6 +1326,15 @@ function the_widget($widget, $instance = array(), $args = array()) {
$args = wp_parse_args($args, $default_args); $args = wp_parse_args($args, $default_args);
$instance = wp_parse_args($instance); $instance = wp_parse_args($instance);
/**
* Fires before rendering the requested widget.
*
* @since 3.0.0
*
* @param string $widget The widget's class name.
* @param array $instance The current widget instance's settings.
* @param array $args An array of the widget's sidebar arguments.
*/
do_action( 'the_widget', $widget, $instance, $args ); do_action( 'the_widget', $widget, $instance, $args );
$widget_obj->_set(-1); $widget_obj->_set(-1);