108 * @param array $args Display arguments including 'before_title', 'after_title', |
108 * @param array $args Display arguments including 'before_title', 'after_title', |
109 * 'before_widget', and 'after_widget'. |
109 * 'before_widget', and 'after_widget'. |
110 * @param array $instance The settings for the particular instance of the widget. |
110 * @param array $instance The settings for the particular instance of the widget. |
111 */ |
111 */ |
112 public function widget( $args, $instance ) { |
112 public function widget( $args, $instance ) { |
113 die('function WP_Widget::widget() must be over-ridden in a sub-class.'); |
113 die( 'function WP_Widget::widget() must be over-ridden in a sub-class.' ); |
114 } |
114 } |
115 |
115 |
116 /** |
116 /** |
117 * Updates a particular instance of a widget. |
117 * Updates a particular instance of a widget. |
118 * |
118 * |
138 * |
138 * |
139 * @param array $instance Current settings. |
139 * @param array $instance Current settings. |
140 * @return string Default return is 'noform'. |
140 * @return string Default return is 'noform'. |
141 */ |
141 */ |
142 public function form( $instance ) { |
142 public function form( $instance ) { |
143 echo '<p class="no-options-widget">' . __('There are no options for this widget.') . '</p>'; |
143 echo '<p class="no-options-widget">' . __( 'There are no options for this widget.' ) . '</p>'; |
144 return 'noform'; |
144 return 'noform'; |
145 } |
145 } |
146 |
146 |
147 // Functions you'll need to call. |
147 // Functions you'll need to call. |
148 |
148 |
158 * on accepted arguments. Default empty array. |
158 * 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 $this->id_base = empty( $id_base ) ? preg_replace( '/(wp_)?widget_/', '', strtolower( get_class( $this ) ) ) : strtolower( $id_base ); |
164 $this->name = $name; |
164 $this->name = $name; |
165 $this->option_name = 'widget_' . $this->id_base; |
165 $this->option_name = 'widget_' . $this->id_base; |
166 $this->widget_options = wp_parse_args( $widget_options, array( 'classname' => $this->option_name, 'customize_selective_refresh' => false ) ); |
166 $this->widget_options = wp_parse_args( |
|
167 $widget_options, |
|
168 array( |
|
169 'classname' => $this->option_name, |
|
170 'customize_selective_refresh' => false, |
|
171 ) |
|
172 ); |
167 $this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) ); |
173 $this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) ); |
168 } |
174 } |
169 |
175 |
170 /** |
176 /** |
171 * PHP4 constructor. |
177 * PHP4 constructor. |
197 * @since 4.4.0 Array format field names are now accepted. |
203 * @since 4.4.0 Array format field names are now accepted. |
198 * |
204 * |
199 * @param string $field_name Field name |
205 * @param string $field_name Field name |
200 * @return string Name attribute for $field_name |
206 * @return string Name attribute for $field_name |
201 */ |
207 */ |
202 public function get_field_name($field_name) { |
208 public function get_field_name( $field_name ) { |
203 if ( false === $pos = strpos( $field_name, '[' ) ) { |
209 if ( false === $pos = strpos( $field_name, '[' ) ) { |
204 return 'widget-' . $this->id_base . '[' . $this->number . '][' . $field_name . ']'; |
210 return 'widget-' . $this->id_base . '[' . $this->number . '][' . $field_name . ']'; |
205 } else { |
211 } else { |
206 return 'widget-' . $this->id_base . '[' . $this->number . '][' . substr_replace( $field_name, '][', $pos, strlen( '[' ) ); |
212 return 'widget-' . $this->id_base . '[' . $this->number . '][' . substr_replace( $field_name, '][', $pos, strlen( '[' ) ); |
207 } |
213 } |
228 * |
234 * |
229 * @since 2.8.0 |
235 * @since 2.8.0 |
230 */ |
236 */ |
231 public function _register() { |
237 public function _register() { |
232 $settings = $this->get_settings(); |
238 $settings = $this->get_settings(); |
233 $empty = true; |
239 $empty = true; |
234 |
240 |
235 // When $settings is an array-like object, get an intrinsic array for use with array_keys(). |
241 // When $settings is an array-like object, get an intrinsic array for use with array_keys(). |
236 if ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) { |
242 if ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) { |
237 $settings = $settings->getArrayCopy(); |
243 $settings = $settings->getArrayCopy(); |
238 } |
244 } |
260 * @since 2.8.0 |
266 * @since 2.8.0 |
261 * |
267 * |
262 * @param int $number The unique order number of this widget instance compared to other |
268 * @param int $number The unique order number of this widget instance compared to other |
263 * instances of the same class. |
269 * instances of the same class. |
264 */ |
270 */ |
265 public function _set($number) { |
271 public function _set( $number ) { |
266 $this->number = $number; |
272 $this->number = $number; |
267 $this->id = $this->id_base . '-' . $number; |
273 $this->id = $this->id_base . '-' . $number; |
268 } |
274 } |
269 |
275 |
270 /** |
276 /** |
271 * Retrieves the widget display callback. |
277 * Retrieves the widget display callback. |
272 * |
278 * |
273 * @since 2.8.0 |
279 * @since 2.8.0 |
274 * |
280 * |
275 * @return callable Display callback. |
281 * @return callable Display callback. |
276 */ |
282 */ |
277 public function _get_display_callback() { |
283 public function _get_display_callback() { |
278 return array($this, 'display_callback'); |
284 return array( $this, 'display_callback' ); |
279 } |
285 } |
280 |
286 |
281 /** |
287 /** |
282 * Retrieves the widget update callback. |
288 * Retrieves the widget update callback. |
283 * |
289 * |
284 * @since 2.8.0 |
290 * @since 2.8.0 |
285 * |
291 * |
286 * @return callable Update callback. |
292 * @return callable Update callback. |
287 */ |
293 */ |
288 public function _get_update_callback() { |
294 public function _get_update_callback() { |
289 return array($this, 'update_callback'); |
295 return array( $this, 'update_callback' ); |
290 } |
296 } |
291 |
297 |
292 /** |
298 /** |
293 * Retrieves the form callback. |
299 * Retrieves the form callback. |
294 * |
300 * |
295 * @since 2.8.0 |
301 * @since 2.8.0 |
296 * |
302 * |
297 * @return callable Form callback. |
303 * @return callable Form callback. |
298 */ |
304 */ |
299 public function _get_form_callback() { |
305 public function _get_form_callback() { |
300 return array($this, 'form_callback'); |
306 return array( $this, 'form_callback' ); |
301 } |
307 } |
302 |
308 |
303 /** |
309 /** |
304 * Determines whether the current request is inside the Customizer preview. |
310 * Determines whether the current request is inside the Customizer preview. |
305 * |
311 * |
314 * |
320 * |
315 * @return bool True if within the Customizer preview, false if not. |
321 * @return bool True if within the Customizer preview, false if not. |
316 */ |
322 */ |
317 public function is_preview() { |
323 public function is_preview() { |
318 global $wp_customize; |
324 global $wp_customize; |
319 return ( isset( $wp_customize ) && $wp_customize->is_preview() ) ; |
325 return ( isset( $wp_customize ) && $wp_customize->is_preview() ); |
320 } |
326 } |
321 |
327 |
322 /** |
328 /** |
323 * Generates the actual widget content (Do NOT override). |
329 * Generates the actual widget content (Do NOT override). |
324 * |
330 * |
390 global $wp_registered_widgets; |
396 global $wp_registered_widgets; |
391 |
397 |
392 $all_instances = $this->get_settings(); |
398 $all_instances = $this->get_settings(); |
393 |
399 |
394 // We need to update the data |
400 // We need to update the data |
395 if ( $this->updated ) |
401 if ( $this->updated ) { |
396 return; |
402 return; |
397 |
403 } |
398 if ( isset($_POST['delete_widget']) && $_POST['delete_widget'] ) { |
404 |
|
405 if ( isset( $_POST['delete_widget'] ) && $_POST['delete_widget'] ) { |
399 // Delete the settings for this instance of the widget |
406 // Delete the settings for this instance of the widget |
400 if ( isset($_POST['the-widget-id']) ) |
407 if ( isset( $_POST['the-widget-id'] ) ) { |
401 $del_id = $_POST['the-widget-id']; |
408 $del_id = $_POST['the-widget-id']; |
402 else |
409 } else { |
403 return; |
410 return; |
404 |
411 } |
405 if ( isset($wp_registered_widgets[$del_id]['params'][0]['number']) ) { |
412 |
406 $number = $wp_registered_widgets[$del_id]['params'][0]['number']; |
413 if ( isset( $wp_registered_widgets[ $del_id ]['params'][0]['number'] ) ) { |
407 |
414 $number = $wp_registered_widgets[ $del_id ]['params'][0]['number']; |
408 if ( $this->id_base . '-' . $number == $del_id ) |
415 |
409 unset($all_instances[$number]); |
416 if ( $this->id_base . '-' . $number == $del_id ) { |
|
417 unset( $all_instances[ $number ] ); |
|
418 } |
410 } |
419 } |
411 } else { |
420 } else { |
412 if ( isset($_POST['widget-' . $this->id_base]) && is_array($_POST['widget-' . $this->id_base]) ) { |
421 if ( isset( $_POST[ 'widget-' . $this->id_base ] ) && is_array( $_POST[ 'widget-' . $this->id_base ] ) ) { |
413 $settings = $_POST['widget-' . $this->id_base]; |
422 $settings = $_POST[ 'widget-' . $this->id_base ]; |
414 } elseif ( isset($_POST['id_base']) && $_POST['id_base'] == $this->id_base ) { |
423 } elseif ( isset( $_POST['id_base'] ) && $_POST['id_base'] == $this->id_base ) { |
415 $num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number']; |
424 $num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number']; |
416 $settings = array( $num => array() ); |
425 $settings = array( $num => array() ); |
417 } else { |
426 } else { |
418 return; |
427 return; |
419 } |
428 } |
420 |
429 |
421 foreach ( $settings as $number => $new_instance ) { |
430 foreach ( $settings as $number => $new_instance ) { |
422 $new_instance = stripslashes_deep($new_instance); |
431 $new_instance = stripslashes_deep( $new_instance ); |
423 $this->_set($number); |
432 $this->_set( $number ); |
424 |
433 |
425 $old_instance = isset($all_instances[$number]) ? $all_instances[$number] : array(); |
434 $old_instance = isset( $all_instances[ $number ] ) ? $all_instances[ $number ] : array(); |
426 |
435 |
427 $was_cache_addition_suspended = wp_suspend_cache_addition(); |
436 $was_cache_addition_suspended = wp_suspend_cache_addition(); |
428 if ( $this->is_preview() && ! $was_cache_addition_suspended ) { |
437 if ( $this->is_preview() && ! $was_cache_addition_suspended ) { |
429 wp_suspend_cache_addition( true ); |
438 wp_suspend_cache_addition( true ); |
430 } |
439 } |
448 * @param array $old_instance Array of old widget settings. |
457 * @param array $old_instance Array of old widget settings. |
449 * @param WP_Widget $this The current widget instance. |
458 * @param WP_Widget $this The current widget instance. |
450 */ |
459 */ |
451 $instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this ); |
460 $instance = apply_filters( 'widget_update_callback', $instance, $new_instance, $old_instance, $this ); |
452 if ( false !== $instance ) { |
461 if ( false !== $instance ) { |
453 $all_instances[$number] = $instance; |
462 $all_instances[ $number ] = $instance; |
454 } |
463 } |
455 |
464 |
456 break; // run only once |
465 break; // run only once |
457 } |
466 } |
458 } |
467 } |
459 |
468 |
460 $this->save_settings($all_instances); |
469 $this->save_settings( $all_instances ); |
461 $this->updated = true; |
470 $this->updated = true; |
462 } |
471 } |
463 |
472 |
464 /** |
473 /** |
465 * Generates the widget control form (Do NOT override). |
474 * Generates the widget control form (Do NOT override). |
473 * @type int $number Number increment used for multiples of the same widget. |
482 * @type int $number Number increment used for multiples of the same widget. |
474 * } |
483 * } |
475 * @return string|null |
484 * @return string|null |
476 */ |
485 */ |
477 public function form_callback( $widget_args = 1 ) { |
486 public function form_callback( $widget_args = 1 ) { |
478 if ( is_numeric($widget_args) ) |
487 if ( is_numeric( $widget_args ) ) { |
479 $widget_args = array( 'number' => $widget_args ); |
488 $widget_args = array( 'number' => $widget_args ); |
480 |
489 } |
481 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) ); |
490 |
|
491 $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) ); |
482 $all_instances = $this->get_settings(); |
492 $all_instances = $this->get_settings(); |
483 |
493 |
484 if ( -1 == $widget_args['number'] ) { |
494 if ( -1 == $widget_args['number'] ) { |
485 // We echo out a form where 'number' can be set later |
495 // We echo out a form where 'number' can be set later |
486 $this->_set('__i__'); |
496 $this->_set( '__i__' ); |
487 $instance = array(); |
497 $instance = array(); |
488 } else { |
498 } else { |
489 $this->_set($widget_args['number']); |
499 $this->_set( $widget_args['number'] ); |
490 $instance = $all_instances[ $widget_args['number'] ]; |
500 $instance = $all_instances[ $widget_args['number'] ]; |
491 } |
501 } |
492 |
502 |
493 /** |
503 /** |
494 * Filters the widget instance's settings before displaying the control form. |
504 * Filters the widget instance's settings before displaying the control form. |
502 */ |
512 */ |
503 $instance = apply_filters( 'widget_form_callback', $instance, $this ); |
513 $instance = apply_filters( 'widget_form_callback', $instance, $this ); |
504 |
514 |
505 $return = null; |
515 $return = null; |
506 if ( false !== $instance ) { |
516 if ( false !== $instance ) { |
507 $return = $this->form($instance); |
517 $return = $this->form( $instance ); |
508 |
518 |
509 /** |
519 /** |
510 * Fires at the end of the widget control form. |
520 * Fires at the end of the widget control form. |
511 * |
521 * |
512 * Use this hook to add extra fields to the widget form. The hook |
522 * Use this hook to add extra fields to the widget form. The hook |
534 * |
544 * |
535 * @param integer $number Optional. The unique order number of this widget instance |
545 * @param integer $number Optional. The unique order number of this widget instance |
536 * compared to other instances of the same class. Default -1. |
546 * compared to other instances of the same class. Default -1. |
537 */ |
547 */ |
538 public function _register_one( $number = -1 ) { |
548 public function _register_one( $number = -1 ) { |
539 wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) ); |
549 wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) ); |
540 _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) ); |
550 _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) ); |
541 _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) ); |
551 _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) ); |
542 } |
552 } |
543 |
553 |
544 /** |
554 /** |
545 * Saves the settings for all instances of the widget class. |
555 * Saves the settings for all instances of the widget class. |
546 * |
556 * |