![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
Changeset 27903
- Timestamp:
- 04/02/2014 05:44:54 AM (12 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/wp-includes/class-wp-customize-widgets.php
r27860 r27903 10 10 */ 11 11 final class WP_Customize_Widgets { 12 /** 12 13 /** 14 * WP_Customize_Manager instance. 15 * 16 * @since 3.9.0 13 17 * @access public 14 18 * @var WP_Customize_Manager … … 17 21 18 22 /** 19 * All id_bases for widgets defined in core 23 * All id_bases for widgets defined in core. 20 24 * 21 25 * @since 3.9.0 … … 72 76 * @since 3.9.0 73 77 * @access public 78 * 79 * @param WP_Customize_Manager $manager Customize manager bootstrap instance. 74 80 */ 75 81 public function __construct( WP_Customize_Manager $manager ) { … … 108 114 109 115 /** 110 * 111 * 112 * Since the widgets get registered (widgets_init) before the customizer settings are set up (customize_register), 113 * we have to filter the options similarly to how the setting previewer will filter the options later. 114 * 115 * @since 3.9.0 116 * 117 * @access public 118 * @global WP_Customize_Manager $wp_customize 116 * Set up widget addition previews. 117 * 118 * Since the widgets get registered on 'widgets_init' before the customizer 119 * settings are set up on 'customize_register', we have to filter the options 120 * similarly to how the setting previewer will filter the options later. 121 * 122 * @since 3.9.0 123 * 124 * @access public 125 * @global WP_Customize_Manager $wp_customize Customizer instance. 119 126 */ 120 127 public function setup_widget_addition_previews() { … … 169 176 foreach ( $customized as $setting_id => $value ) { 170 177 if ( preg_match( '/^(widget_.+?)(\[(\d+)\])?$/', $setting_id, $matches ) ) { 178 179 /* 180 * @todo Replace the next two lines with the following once WordPress supports PHP 5.3. 181 * 182 * $self = $this; // not needed in PHP 5.4 183 * 184 * $function = function ( $value ) use ( $self, $setting_id ) { 185 * return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id ); 186 * }; 187 */ 171 188 $body = sprintf( 'global $wp_customize; return $wp_customize->widgets->prepreview_added_widget_instance( $value, %s );', var_export( $setting_id, true ) ); 172 189 $function = create_function( '$value', $body ); 173 // @todo replace above two lines with following once PHP 5.3 happens in WordPress 174 // $self = $this; // not needed in PHP 5.4 175 // $function = function ( $value ) use ( $self, $setting_id ) { 176 // return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id ); 177 //}; 178 179 $option = $matches[1]; 190 191 $option = $matches[1]; 180 192 181 193 $hook = sprintf( 'option_%s', $option ); … … 187 199 $this->_prepreview_added_filters[] = compact( 'hook', 'function' ); 188 200 189 /** 190 * Make sure the option is registered so that the update_option won't fail due to 191 * the filters providing a default value, which causes the update_option() to get confused. 201 /* 202 * Make sure the option is registered so that the update_option() 203 * won't fail due to the filters providing a default value, which 204 * causes the update_option() to get confused. 192 205 */ 193 206 add_option( $option, array() ); … … 199 212 200 213 /** 201 *202 *203 214 * Ensure that newly-added widgets will appear in the widgets_sidebars. 204 * This is necessary because the customizer's setting preview filters are added after the widgets_init action, 205 * which is too late for the widgets to be set up properly. 206 * 207 * @since 3.9.0 208 * @access public 209 * 210 * @param array $sidebars_widgets Array of 211 * @return array 215 * 216 * This is necessary because the customizer's setting preview filters 217 * are added after the widgets_init action, which is too late for the 218 * widgets to be set up properly. 219 * 220 * @since 3.9.0 221 * @access public 222 * 223 * @param array $sidebars_widgets Associative array of sidebars and their widgets. 224 * @return array Filtered array of sidebars and their widgets. 212 225 */ 213 226 public function prepreview_added_sidebars_widgets( $sidebars_widgets ) { … … 222 235 223 236 /** 224 * 225 * 226 * Ensure that newly-added widgets will have empty instances so that they will be recognized. 227 * This is necessary because the customizer's setting preview filters are added after the widgets_init action, 228 * which is too late for the widgets to be set up properly. 237 * Ensure newly-added widgets have empty instances so they 238 * will be recognized. 239 * 240 * This is necessary because the customizer's setting preview 241 * filters are added after the widgets_init action, which is 242 * too late for the widgets to be set up properly. 229 243 * 230 244 * @since 3.9.0 … … 240 254 $widget_number = $parsed_setting_id['number']; 241 255 242 // Single widget 256 // Single widget. 243 257 if ( is_null( $widget_number ) ) { 244 258 if ( false === $instance && empty( $value ) ) { … … 260 274 261 275 /** 262 * Remove filters added in setup_widget_addition_previews() which ensure that 263 * widgets are populating the options during widgets_init 276 * Remove pre-preview filters. 277 * 278 * Removes filters added in setup_widget_addition_previews() 279 * to ensure widgets are populating the options during 280 * 'widgets_init'. 264 281 * 265 282 * @since 3.9.0 … … 274 291 275 292 /** 276 * Make sure that all widgets get loaded into customizer; these actions are also done in the wp_ajax_save_widget() 293 * Make sure all widgets get loaded into the Customizer. 294 * 295 * Note: these actions are also fired in wp_ajax_update_widget(). 277 296 * 278 297 * @since 3.9.0 … … 280 299 */ 281 300 public function customize_controls_init() { 301 /** This action is documented in wp-admin/includes/ajax-actions.php */ 282 302 do_action( 'load-widgets.php' ); 303 304 /** This action is documented in wp-admin/includes/ajax-actions.php */ 283 305 do_action( 'widgets.php' ); 284 306 … … 288 310 289 311 /** 290 * When in preview, invoke customize_register for settings after WordPress is 291 * loaded so that all filters have been initialized (e.g. Widget Visibility) 312 * Ensure widgets are available for all types of previews. 313 * 314 * When in preview, hook to 'customize_register' for settings 315 * after WordPress is loaded so that all filters have been 316 * initialized (e.g. Widget Visibility). 292 317 * 293 318 * @since 3.9.0 … … 303 328 304 329 /** 305 * Register customizer settings and controls for all sidebars and widgets 330 * Register customizer settings and controls for all sidebars and widgets. 306 331 * 307 332 * @since 3.9.0 … … 320 345 321 346 /* 322 * Register a setting for all widgets, including those which are active, inactive, and orphaned 323 * since a widget may get suppressed from a sidebar via a plugin (like Widget Visibility). 347 * Register a setting for all widgets, including those which are active, 348 * inactive, and orphaned since a widget may get suppressed from a sidebar 349 * via a plugin (like Widget Visibility). 324 350 */ 325 351 foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) { … … 340 366 $is_active_sidebar = ( $is_registered_sidebar && ! $is_inactive_widgets ); 341 367 342 /** 343 * Add setting for managing the sidebar's widgets 344 */ 368 // Add setting for managing the sidebar's widgets. 345 369 if ( $is_registered_sidebar || $is_inactive_widgets ) { 346 370 $setting_id = sprintf( 'sidebars_widgets[%s]', $sidebar_id ); … … 351 375 $new_setting_ids[] = $setting_id; 352 376 353 /** 354 * Add section to contain controls 355 */ 377 // Add section to contain controls. 356 378 $section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id ); 357 379 if ( $is_active_sidebar ) { … … 423 445 424 446 /** 425 * Covert a widget_id into its corresponding customizer setting id (option name)447 * Covert a widget_id into its corresponding customizer setting ID (option name). 426 448 * 427 449 * @since 3.9.0 … … 441 463 442 464 /** 443 * Core widgets which may have controls wider than 250, but can still be 444 * shown in the narrow customizer panel. The RSS and Text widgets in Core, 445 * for example, have widths of 400 and yet they still render fine in the 446 * customizer panel. This method will return all Core widgets as being 447 * not wide, but this can be overridden with the is_wide_widget_in_customizer 448 * filter. 465 * Determine whether the widget is considered "wide". 466 * 467 * Core widgets which may have controls wider than 250, but can 468 * still be shown in the narrow customizer panel. The RSS and Text 469 * widgets in Core, for example, have widths of 400 and yet they 470 * still render fine in the customizer panel. This method will 471 * return all Core widgets as being not wide, but this can be 472 * overridden with the is_wide_widget_in_customizer filter. 449 473 * 450 474 * @since 3.9.0 … … 469 493 * @param string $widget_id Widget ID. 470 494 */ 471 $is_wide = apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id ); 472 return $is_wide; 495 return apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id ); 473 496 } 474 497 … … 504 527 * 505 528 * @param string $setting_id Widget setting ID. 506 * @return WP_Error|array Array contain a widget's id_base and number components,529 * @return WP_Error|array Array containing a widget's id_base and number components, 507 530 * or a WP_Error object. 508 531 */ … … 518 541 519 542 /** 520 * Enqueue scripts and styles for customizer panel and export data to J S.543 * Enqueue scripts and styles for customizer panel and export data to JavaScript. 521 544 * 522 545 * @since 3.9.0 … … 527 550 wp_enqueue_script( 'customize-widgets' ); 528 551 529 // Export available widgets with control_tpl removed from model 530 // since plugins need templates to be in the DOM 552 /* 553 * Export available widgets with control_tpl removed from model 554 * since plugins need templates to be in the DOM. 555 */ 531 556 $available_widgets = array(); 532 557 foreach ( $this->get_available_widgets() as $available_widget ) { … … 563 588 ); 564 589 565 // Why not wp_localize_script? Because we're not localizing, and it forces values into strings. 590 /* 591 * Why not wp_localize_script? Because we're not localizing, 592 * and it forces values into strings. 593 */ 566 594 global $wp_scripts; 567 595 $exports = array( … … 595 623 596 624 /** 597 * Render the widget form control templates into the DOM so that plugin scripts can manipulate them625 * Render the widget form control templates into the DOM. 598 626 * 599 627 * @since 3.9.0 … … 619 647 620 648 /** 621 * Get common arguments to supply when constructing a customizer setting649 * Get common arguments to supply when constructing a Customizer setting. 622 650 * 623 651 * @since 3.9.0 … … 636 664 ); 637 665 $args = array_merge( $args, $overrides ); 638 $args = apply_filters( 'widget_customizer_setting_args', $args, $id ); 639 return $args; 640 } 641 642 /** 643 * Make sure that a sidebars_widgets[x] only ever consists of actual widget IDs. 644 * Used as sanitize_callback for each sidebars_widgets setting. 666 667 /** 668 * Filter the common arguments supplied when constructing a Customizer setting. 669 * 670 * @since 3.9.0 671 * 672 * @see WP_Customize_Setting 673 * 674 * @param array $args Array of Customizer setting arguments. 675 * @param string $id Widget setting ID. 676 */ 677 return apply_filters( 'widget_customizer_setting_args', $args, $id ); 678 } 679 680 /** 681 * Make sure that sidebar widget arrays only ever contain widget IDS. 682 * 683 * Used as the 'sanitize_callback' for each $sidebars_widgets setting. 645 684 * 646 685 * @since 3.9.0 … … 669 708 * 670 709 * @see wp_list_widgets() 671 * @return array 710 * 711 * @return array List of available widgets. 672 712 */ 673 713 public function get_available_widgets() { … … 727 767 $control_tpl = $this->get_widget_control( $list_widget_controls_args ); 728 768 729 // The properties here are mapped to the Backbone Widget model 769 // The properties here are mapped to the Backbone Widget model. 730 770 $available_widget = array_merge( 731 771 $available_widget, … … 765 805 766 806 /** 767 * Invoke wp_widget_control() but capture the output buffer and transform the markup 768 * so that it can be used in the customizer. 807 * Get the widget control markup. 769 808 * 770 809 * @since 3.9.0 … … 787 826 788 827 /** 789 * Add hooks for the customizer preview 828 * Add hooks for the customizer preview. 790 829 * 791 830 * @since 3.9.0 … … 800 839 801 840 /** 802 * 803 * 804 * When previewing, make sure the proper previewing widgets are used. Because wp_get_sidebars_widgets() 805 * gets called early at init (via wp_convert_widget_settings()) and can set global variable 806 * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' ) before the customizer 807 * preview filter is added, we have to reset it after the filter has been added. 841 * When previewing, make sure the proper previewing widgets are used. 842 * 843 * Because wp_get_sidebars_widgets() gets called early at init 844 * (via wp_convert_widget_settings()) and can set global variable 845 * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' ) 846 * before the customizer preview filter is added, we have to reset 847 * it after the filter has been added. 808 848 * 809 849 * @since 3.9.0 … … 814 854 public function preview_sidebars_widgets( $sidebars_widgets ) { 815 855 $sidebars_widgets = get_option( 'sidebars_widgets' ); 856 816 857 unset( $sidebars_widgets['array_version'] ); 817 858 return $sidebars_widgets; … … 819 860 820 861 /** 821 * Enqueue scripts for the customizer preview862 * Enqueue scripts for the Customizer preview. 822 863 * 823 864 * @since 3.9.0 … … 852 893 853 894 /** 854 * At the very end of the page, at the very end of the wp_footer, communicate the sidebars that appeared on the page. 895 * At the very end of the page, at the very end of the wp_footer, 896 * communicate the sidebars that appeared on the page. 855 897 * 856 898 * @since 3.9.0 … … 880 922 881 923 /** 882 * Keep track of the widgets that were rendered 924 * Keep track of the widgets that were rendered. 883 925 * 884 926 * @since 3.9.0 … … 892 934 893 935 /** 894 * Keep track of the times that is_active_sidebar() is called in the template, and assume that this 895 * means that the sidebar would be rendered on the template if there were widgets populating it. 936 * Tally the sidebars rendered via is_active_sidebar(). 937 * 938 * Keep track of the times that is_active_sidebar() is called 939 * in the template, and assume that this means that the sidebar 940 * would be rendered on the template if there were widgets 941 * populating it. 896 942 * 897 943 * @since 3.9.0 … … 905 951 $this->rendered_sidebars[] = $sidebar_id; 906 952 } 907 // We may need to force this to true, and also force-true the value for dynamic_sidebar_has_widgets 908 // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty. 953 /* 954 * We may need to force this to true, and also force-true the value 955 * for 'dynamic_sidebar_has_widgets' if we want to ensure that there 956 * is an area to drop widgets into, if the sidebar is empty. 957 */ 909 958 return $is_active; 910 959 } 911 960 912 961 /** 913 * Keep track of the times that dynamic_sidebar() is called in the template, and assume that this 914 * means that the sidebar would be rendered on the template if there were widgets populating it. 962 * Tally the sidebars rendered via dynamic_sidebar(). 963 * 964 * Keep track of the times that dynamic_sidebar() is called in the template, 965 * and assume this means the sidebar would be rendered on the template if 966 * there were widgets populating it. 915 967 * 916 968 * @since 3.9.0 … … 924 976 $this->rendered_sidebars[] = $sidebar_id; 925 977 } 978 926 979 /* 927 * We may need to force this to true, and also force-true the value for is_active_sidebar 928 * if we want to ensure that there is an area to drop widgets into, if the sidebar is empty. 980 * We may need to force this to true, and also force-true the value 981 * for 'is_active_sidebar' if we want to ensure there is an area to 982 * drop widgets into, if the sidebar is empty. 929 983 */ 930 984 return $has_widgets; … … 958 1012 * @since 3.9.0 959 1013 * @access public 960 *961 * @see Widget_Customizer::sanitize_widget_js_instance()962 1014 * 963 1015 * @param array $value Widget instance to sanitize. … … 998 1050 * @access public 999 1051 * 1000 * @see Widget_Customizer::sanitize_widget_instance()1001 *1002 1052 * @param array $value Widget instance to convert to JSON. 1003 1053 * @return array JSON-converted widget instance. … … 1017 1067 1018 1068 /** 1019 * Strip out widget IDs for widgets which are no longer registered, such 1020 * as the case when a plugin orphans a widget in a sidebar when it is deactivated. 1069 * Strip out widget IDs for widgets which are no longer registered. 1070 * 1071 * One example where this might happen is when a plugin orphans a widget 1072 * in a sidebar upon deactivation. 1021 1073 * 1022 1074 * @since 3.9.0 … … 1041 1093 * 1042 1094 * @param string $widget_id Widget ID. 1043 * @return WP_Error|array Array containing the updated widget information. WP_Error, otherwise. 1095 * @return WP_Error|array Array containing the updated widget information. 1096 * A WP_Error object, otherwise. 1044 1097 */ 1045 1098 public function call_widget_update( $widget_id ) { … … 1133 1186 1134 1187 /** 1135 * Allow customizer to update a widget using its form, but return the new 1188 * Update widget settings asynchronously. 1189 * 1190 * Allows the Customizer to update a widget using its form, but return the new 1136 1191 * instance info via Ajax instead of saving it to the options table. 1192 * 1137 1193 * Most code here copied from wp_ajax_save_widget() 1138 1194 * … … 1140 1196 * @access public 1141 1197 * 1142 * @see wp_ajax_save_widget 1198 * @see wp_ajax_save_widget() 1199 * 1143 1200 * @todo Reuse wp_ajax_save_widget now that we have option transactions? 1144 * @action wp_ajax_update_widget1145 1201 */ 1146 1202 public function wp_ajax_update_widget() { … … 1160 1216 } 1161 1217 1218 /** This action is documented in wp-admin/includes/ajax-actions.php */ 1162 1219 do_action( 'load-widgets.php' ); 1220 1221 /** This action is documented in wp-admin/includes/ajax-actions.php */ 1163 1222 do_action( 'widgets.php' ); 1164 1223 … … 1190 1249 1191 1250 /** 1192 * @var array $_captured_options values updated while capturing is happening 1251 * List of captured widget option updates. 1252 * 1253 * @since 3.9.0 1254 * @access protected 1255 * @var array $_captured_options Values updated while option capture is happening. 1193 1256 */ 1194 1257 protected $_captured_options = array(); 1195 1258 1196 1259 /** 1197 * @var bool $_is_current whether capturing is currently happening or not 1260 * Whether option capture is currently happening. 1261 * 1262 * @since 3.9.0 1263 * @access protected 1264 * @var bool $_is_current Whether option capture is currently happening or not. 1198 1265 */ 1199 1266 protected $_is_capturing_option_updates = false; 1200 1267 1201 1268 /** 1202 * @param $option_name 1203 * @return boolean 1269 * Determine whether the captured option update should be ignored. 1270 * 1271 * @since 3.9.0 1272 * @access protected 1273 * 1274 * @param string $option_name Option name. 1275 * @return boolean Whether the option capture is ignored. 1204 1276 */ 1205 1277 protected function is_option_capture_ignored( $option_name ) { … … 1208 1280 1209 1281 /** 1210 * Get options updated 1211 * @return array 1282 * Retrieve captured widget option updates. 1283 * 1284 * @since 3.9.0 1285 * @access protected 1286 * 1287 * @return array Array of captured options. 1212 1288 */ 1213 1289 protected function get_captured_options() { … … 1216 1292 1217 1293 /** 1218 * Get the number of options updated 1219 * @return bool 1294 * Get the number of captured widget option updates. 1295 * 1296 * @since 3.9.0 1297 * @access protected 1298 * 1299 * @return int Number of updated options. 1220 1300 */ 1221 1301 protected function count_captured_options() { … … 1224 1304 1225 1305 /** 1226 * Start keeping track of changes to options, and cache their new values 1306 * Start keeping track of changes to widget options, caching new values. 1307 * 1308 * @since 3.9.0 1309 * @access protected 1227 1310 */ 1228 1311 protected function start_capturing_option_updates() { … … 1236 1319 1237 1320 /** 1321 * Pre-filter captured option values before updating. 1322 * 1238 1323 * @access private 1239 1324 * @param mixed $new_value … … 1242 1327 * @return mixed 1243 1328 */ 1244 p ublicfunction _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {1329 private function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) { 1245 1330 if ( $this->is_option_capture_ignored( $option_name ) ) { 1246 1331 return; … … 1257 1342 1258 1343 /** 1344 * Pre-filter captured option values before retrieving. 1345 * 1259 1346 * @access private 1260 * @param mixed $value 1347 * @param mixed $value Option 1261 1348 * @return mixed 1262 1349 */ 1263 p ublicfunction _capture_filter_pre_get_option( $value ) {1350 private function _capture_filter_pre_get_option( $value ) { 1264 1351 $option_name = preg_replace( '/^pre_option_/', '', current_filter() ); 1265 1352 if ( isset( $this->_captured_options[$option_name] ) ) { … … 1272 1359 1273 1360 /** 1274 * Undo any changes to the options since start_capturing_option_updates() was called 1361 * Undo any changes to the options since options capture began. 1362 * 1363 * @since 3.9.0 1364 * @access protected 1275 1365 */ 1276 1366 protected function stop_capturing_option_updates() {
Note:
See TracChangeset
for help on using the changeset viewer.
