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

Docs: Improve syntax and correct documentation throughout a variety of methods in `WP_Customize_Widgets`. 

See #32246. See #35986.

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


git-svn-id: http://core.svn.wordpress.org/trunk@36809 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2016-03-04 02:02:26 +00:00
parent 66ec5425ea
commit 7696b79d0c
2 changed files with 108 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
wp-includes/class-wp-customize-widgets.php
View File

@ -112,7 +112,7 @@ final class WP_Customize_Widgets {
}
/**
* Get the widget setting type given a setting ID.
* Retrieves the widget setting type given a setting ID.
*
* @since 4.2.0
* @access protected
@ -136,7 +136,8 @@ final class WP_Customize_Widgets {
}
/**
* Inspect the incoming customized data for any widget settings, and dynamically add them up-front so widgets will be initialized properly.
* Inspects the incoming customized data for any widget settings, and dynamically adds
* them up-front so widgets will be initialized properly.
*
* @since 4.2.0
* @access public
@ -168,7 +169,7 @@ final class WP_Customize_Widgets {
}
/**
* Determine the arguments for a dynamically-created setting.
* Determines the arguments for a dynamically-created setting.
*
* @since 4.2.0
* @access public
@ -185,10 +186,9 @@ final class WP_Customize_Widgets {
}
/**
* Get an unslashed post value or return a default.
* Retrieves an unslashed post value or return a default.
*
* @since 3.9.0
*
* @access protected
*
* @param string $name Post value.
@ -237,18 +237,18 @@ final class WP_Customize_Widgets {
}
/**
* Filter old_sidebars_widgets_data Customizer setting.
* Filters old_sidebars_widgets_data Customizer setting.
*
* When switching themes, filter the Customizer setting
* old_sidebars_widgets_data to supply initial $sidebars_widgets before they
* were overridden by retrieve_widgets(). The value for
* old_sidebars_widgets_data gets set in the old theme's sidebars_widgets
* When switching themes, filter the Customizer setting old_sidebars_widgets_data
* to supply initial $sidebars_widgets before they were overridden by retrieve_widgets().
* The value for old_sidebars_widgets_data gets set in the old theme's sidebars_widgets
* theme_mod.
*
* @see WP_Customize_Widgets::handle_theme_switch()
* @since 3.9.0
* @access public
*
* @see WP_Customize_Widgets::handle_theme_switch()
*
* @param array $old_sidebars_widgets
* @return array
*/
@ -257,16 +257,16 @@ final class WP_Customize_Widgets {
}
/**
* Filter sidebars_widgets option for theme switch.
* Filters sidebars_widgets option for theme switch.
*
* When switching themes, the retrieve_widgets() function is run when the
* Customizer initializes, and then the new sidebars_widgets here get
* supplied as the default value for the sidebars_widgets option.
* When switching themes, the retrieve_widgets() function is run when the Customizer initializes,
* and then the new sidebars_widgets here get supplied as the default value for the sidebars_widgets
* option.
*
* @see WP_Customize_Widgets::handle_theme_switch()
* @since 3.9.0
* @access public
*
* @see WP_Customize_Widgets::handle_theme_switch()
* @global array $sidebars_widgets
*
* @param array $sidebars_widgets
@ -279,7 +279,7 @@ final class WP_Customize_Widgets {
}
/**
* Make sure all widgets get loaded into the Customizer.
* Ensures all widgets get loaded into the Customizer.
*
* Note: these actions are also fired in wp_ajax_update_widget().
*
@ -298,11 +298,10 @@ final class WP_Customize_Widgets {
}
/**
* Ensure widgets are available for all types of previews.
* Ensures widgets are available for all types of previews.
*
* When in preview, hook to 'customize_register' for settings
* after WordPress is loaded so that all filters have been
* initialized (e.g. Widget Visibility).
* When in preview, hook to 'customize_register' for settings after WordPress is loaded
* so that all filters have been initialized (e.g. Widget Visibility).
*
* @since 3.9.0
* @access public
@ -316,7 +315,7 @@ final class WP_Customize_Widgets {
}
/**
* Register Customizer settings and controls for all sidebars and widgets.
* Registers Customizer settings and controls for all sidebars and widgets.
*
* @since 3.9.0
* @access public
@ -466,7 +465,7 @@ final class WP_Customize_Widgets {
}
/**
* Return whether the widgets panel is active, based on whether there are sidebars registered.
* Determines whether the widgets panel is active, based on whether there are sidebars registered.
*
* @since 4.4.0
* @access public
@ -482,7 +481,7 @@ final class WP_Customize_Widgets {
}
/**
* Covert a widget_id into its corresponding Customizer setting ID (option name).
* Converts a widget_id into its corresponding Customizer setting ID (option name).
*
* @since 3.9.0
* @access public
@ -501,13 +500,13 @@ final class WP_Customize_Widgets {
}
/**
* Determine whether the widget is considered "wide".
* Determines whether the widget is considered "wide".
*
* Core widgets which may have controls wider than 250, but can
* still be shown in the narrow Customizer panel. The RSS and Text
* widgets in Core, for example, have widths of 400 and yet they
* still render fine in the Customizer panel. This method will
* return all Core widgets as being not wide, but this can be
* Core widgets which may have controls wider than 250, but can still be shown
* in the narrow Customizer panel. The RSS and Text widgets in Core, for example,
* have widths of 400 and yet they still render fine in the Customizer panel.
*
* This method will return all Core widgets as being not wide, but this can be
* overridden with the is_wide_widget_in_customizer filter.
*
* @since 3.9.0
@ -538,7 +537,7 @@ final class WP_Customize_Widgets {
}
/**
* Covert a widget ID into its id_base and number components.
* Converts a widget ID into its id_base and number components.
*
* @since 3.9.0
* @access public
@ -563,7 +562,7 @@ final class WP_Customize_Widgets {
}
/**
* Convert a widget setting ID (option path) to its id_base and number components.
* Converts a widget setting ID (option path) to its id_base and number components.
*
* @since 3.9.0
* @access public
@ -584,7 +583,7 @@ final class WP_Customize_Widgets {
}
/**
* Call admin_print_styles-widgets.php and admin_print_styles hooks to
* Calls admin_print_styles-widgets.php and admin_print_styles hooks to
* allow custom styles from plugins.
*
* @since 3.9.0
@ -599,7 +598,7 @@ final class WP_Customize_Widgets {
}
/**
* Call admin_print_scripts-widgets.php and admin_print_scripts hooks to
* Calls admin_print_scripts-widgets.php and admin_print_scripts hooks to
* allow custom scripts from plugins.
*
* @since 3.9.0
@ -614,7 +613,7 @@ final class WP_Customize_Widgets {
}
/**
* Enqueue scripts and styles for Customizer panel and export data to JavaScript.
* Enqueues scripts and styles for Customizer panel and export data to JavaScript.
*
* @since 3.9.0
* @access public
@ -706,7 +705,7 @@ final class WP_Customize_Widgets {
}
/**
* Render the widget form control templates into the DOM.
* Renders the widget form control templates into the DOM.
*
* @since 3.9.0
* @access public
@ -744,7 +743,7 @@ final class WP_Customize_Widgets {
}
/**
* Call admin_print_footer_scripts and admin_print_scripts hooks to
* Calls admin_print_footer_scripts and admin_print_scripts hooks to
* allow custom scripts from plugins.
*
* @since 3.9.0
@ -759,7 +758,7 @@ final class WP_Customize_Widgets {
}
/**
* Get common arguments to supply when constructing a Customizer setting.
* Retrieves common arguments to supply when constructing a Customizer setting.
*
* @since 3.9.0
* @access public
@ -800,7 +799,7 @@ final class WP_Customize_Widgets {
}
/**
* Make sure that sidebar widget arrays only ever contain widget IDS.
* Ensures sidebar widget arrays only ever contain widget IDS.
*
* Used as the 'sanitize_callback' for each $sidebars_widgets setting.
*
@ -820,7 +819,7 @@ final class WP_Customize_Widgets {
}
/**
* Build up an index of all available widgets for use in Backbone models.
* Builds up an index of all available widgets for use in Backbone models.
*
* @since 3.9.0
* @access public
@ -907,7 +906,7 @@ final class WP_Customize_Widgets {
}
/**
* Naturally order available widgets by name.
* Naturally orders available widgets by name.
*
* @since 3.9.0
* @access protected
@ -921,7 +920,7 @@ final class WP_Customize_Widgets {
}
/**
* Get the widget control markup.
* Retrieves the widget control markup.
*
* @since 3.9.0
* @access public
@ -941,15 +940,15 @@ final class WP_Customize_Widgets {
}
/**
* Get the widget control markup parts.
* Retrieves the widget control markup parts.
*
* @since 4.4.0
* @access public
*
* @param array $args Widget control arguments.
* @return array {
* @type string $control Markup for widget control wrapping form.
* @type string $content The contents of the widget form itself.
* @type string $control Markup for widget control wrapping form.
* @type string $content The contents of the widget form itself.
* }
*/
public function get_widget_control_parts( $args ) {
@ -972,7 +971,7 @@ final class WP_Customize_Widgets {
}
/**
* Add hooks for the Customizer preview.
* Adds hooks for the Customizer preview.
*
* @since 3.9.0
* @access public
@ -984,7 +983,7 @@ final class WP_Customize_Widgets {
}
/**
* Refresh nonce for widget updates.
* Refreshes the nonce for widget updates.
*
* @since 4.2.0
* @access public
@ -998,13 +997,12 @@ final class WP_Customize_Widgets {
}
/**
* When previewing, make sure the proper previewing widgets are used.
* When previewing, ensures the proper previewing widgets are used.
*
* Because wp_get_sidebars_widgets() gets called early at init
* (via wp_convert_widget_settings()) and can set global variable
* $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' )
* before the Customizer preview filter is added, we have to reset
* it after the filter has been added.
* Because wp_get_sidebars_widgets() gets called early at {@see 'init' } (via
* wp_convert_widget_settings()) and can set global variable `$_wp_sidebars_widgets`
* to the value of `get_option( 'sidebars_widgets' )` before the Customizer preview
* filter is added, it has to be reset after the filter has been added.
*
* @since 3.9.0
* @access public
@ -1020,7 +1018,7 @@ final class WP_Customize_Widgets {
}
/**
* Enqueue scripts for the Customizer preview.
* Enqueues scripts for the Customizer preview.
*
* @since 3.9.0
* @access public
@ -1030,13 +1028,11 @@ final class WP_Customize_Widgets {
}
/**
* Insert default style for highlighted widget at early point so theme
* Inserts default style for highlighted widget at early point so theme
* stylesheet can override.
*
* @since 3.9.0
* @access public
*
* @action wp_print_styles
*/
public function print_preview_css() {
?>
@ -1053,8 +1049,8 @@ final class WP_Customize_Widgets {
}
/**
* At the very end of the page, at the very end of the wp_footer,
* communicate the sidebars that appeared on the page.
* Communicates the sidebars that appeared on the page at the very end of the page,
* and at the very end of the wp_footer,
*
* @since 3.9.0
* @access public
@ -1087,7 +1083,7 @@ final class WP_Customize_Widgets {
}
/**
* Keep track of the widgets that were rendered.
* Tracks the widgets that were rendered.
*
* @since 3.9.0
* @access public
@ -1112,7 +1108,7 @@ final class WP_Customize_Widgets {
}
/**
* Determine if a sidebar is rendered on the page.
* Determines if a sidebar is rendered on the page.
*
* @since 4.0.0
* @access public
@ -1125,19 +1121,18 @@ final class WP_Customize_Widgets {
}
/**
* Tally the sidebars rendered via is_active_sidebar().
* Tallies the sidebars rendered via is_active_sidebar().
*
* Keep track of the times that is_active_sidebar() is called
* in the template, and assume that this means that the sidebar
* would be rendered on the template if there were widgets
* populating it.
* Keep track of the times that is_active_sidebar() is called in the template,
* and assume that this means that the sidebar would be rendered on the template
* if there were widgets populating it.
*
* @since 3.9.0
* @access public
*
* @param bool $is_active Whether the sidebar is active.
* @param string $sidebar_id Sidebar ID.
* @return bool
* @return bool Whether the sidebar is active.
*/
public function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) {
if ( is_registered_sidebar( $sidebar_id ) ) {
@ -1152,7 +1147,7 @@ final class WP_Customize_Widgets {
}
/**
* Tally the sidebars rendered via dynamic_sidebar().
* Tallies the sidebars rendered via dynamic_sidebar().
*
* Keep track of the times that dynamic_sidebar() is called in the template,
* and assume this means the sidebar would be rendered on the template if
@ -1163,7 +1158,7 @@ final class WP_Customize_Widgets {
*
* @param bool $has_widgets Whether the current sidebar has widgets.
* @param string $sidebar_id Sidebar ID.
* @return bool
* @return bool Whether the current sidebar has widgets.
*/
public function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) {
if ( is_registered_sidebar( $sidebar_id ) ) {
@ -1179,7 +1174,7 @@ final class WP_Customize_Widgets {
}
/**
* Get MAC for a serialized widget instance string.
* Retrieves MAC for a serialized widget instance string.
*
* Allows values posted back from JS to be rejected if any tampering of the
* data has occurred.
@ -1195,10 +1190,10 @@ final class WP_Customize_Widgets {
}
/**
* Sanitize a widget instance.
* Sanitizes a widget instance.
*
* Unserialize the JS-instance for storing in the options. It's important
* that this filter only get applied to an instance once.
* Unserialize the JS-instance for storing in the options. It's important that this filter
* only get applied to an instance *once*.
*
* @since 3.9.0
* @access public
@ -1236,7 +1231,7 @@ final class WP_Customize_Widgets {
}
/**
* Convert widget instance into JSON-representable format.
* Converts a widget instance into JSON-representable format.
*
* @since 3.9.0
* @access public
@ -1259,7 +1254,7 @@ final class WP_Customize_Widgets {
}
/**
* Strip out widget IDs for widgets which are no longer registered.
* Strips out widget IDs for widgets which are no longer registered.
*
* One example where this might happen is when a plugin orphans a widget
* in a sidebar upon deactivation.
@ -1279,9 +1274,9 @@ final class WP_Customize_Widgets {
}
/**
* Find and invoke the widget update and control callbacks.
* Finds and invokes the widget update and control callbacks.
*
* Requires that $_POST be populated with the instance data.
* Requires that `$_POST` be populated with the instance data.
*
* @since 3.9.0
* @access public
@ -1406,18 +1401,17 @@ final class WP_Customize_Widgets {
}
/**
* Update widget settings asynchronously.
* Updates widget settings asynchronously.
*
* Allows the Customizer to update a widget using its form, but return the new
* instance info via Ajax instead of saving it to the options table.
*
* Most code here copied from wp_ajax_save_widget()
* Most code here copied from wp_ajax_save_widget().
*
* @since 3.9.0
* @access public
*
* @see wp_ajax_save_widget()
*
*/
public function wp_ajax_update_widget() {
@ -1506,7 +1500,7 @@ final class WP_Customize_Widgets {
}
/**
* Add hooks for selective refresh.
* Adds hooks for selective refresh.
*
* @since 4.5.0
* @access public
@ -1524,7 +1518,7 @@ final class WP_Customize_Widgets {
}
/**
* Enqueue scripts for the Customizer preview.
* Enqueues scripts for the Customizer preview.
*
* @since 4.5.0
* @access public
@ -1599,25 +1593,25 @@ final class WP_Customize_Widgets {
/**
* List of the tag names seen for before_widget strings.
*
* This is used in the filter_wp_kses_allowed_html filter to ensure that the
* This is used in the {@see 'filter_wp_kses_allowed_html'} filter to ensure that the
* data-* attributes can be whitelisted.
*
* @since 4.5.0
* @access private
* @access protected
* @var array
*/
protected $before_widget_tags_seen = array();
/**
* Ensure that the HTML data-* attributes for selective refresh are allowed by kses.
* Ensures the HTML data-* attributes for selective refresh are allowed by kses.
*
* This is needed in case the $before_widget is run through wp_kses() when printed.
* This is needed in case the `$before_widget` is run through wp_kses() when printed.
*
* @since 4.5.0
* @access public
*
* @param array $allowed_html Allowed HTML.
* @return array Allowed HTML.
* @return array (Maybe) modified allowed HTML.
*/
public function filter_wp_kses_allowed_data_attributes( $allowed_html ) {
foreach ( array_keys( $this->before_widget_tags_seen ) as $tag_name ) {
@ -1644,7 +1638,7 @@ final class WP_Customize_Widgets {
* This helps facilitate the uncommon scenario where a single sidebar is rendered multiple times on a template.
*
* @since 4.5.0
* @access private
* @access protected
* @var array
*/
protected $sidebar_instance_count = array();
@ -1653,7 +1647,7 @@ final class WP_Customize_Widgets {
* The current request's sidebar_instance_number context.
*
* @since 4.5.0
* @access private
* @access protected
* @var int
*/
protected $context_sidebar_instance_number;
@ -1662,17 +1656,18 @@ final class WP_Customize_Widgets {
* Current sidebar ID being rendered.
*
* @since 4.5.0
* @access private
* @access protected
* @var array
*/
protected $current_dynamic_sidebar_id_stack = array();
/**
* Start keeping track of the current sidebar being rendered.
* Begins keeping track of the current sidebar being rendered.
*
* Insert marker before widgets are rendered in a dynamic sidebar.
*
* @since 4.5.0
* @access public
*
* @param int|string $index Index, name, or ID of the dynamic sidebar.
*/
@ -1688,11 +1683,12 @@ final class WP_Customize_Widgets {
}
/**
* Finish keeping track of the current sidebar being rendered.
* Finishes keeping track of the current sidebar being rendered.
*
* Insert marker after widgets are rendered in a dynamic sidebar.
* Inserts a marker after widgets are rendered in a dynamic sidebar.
*
* @since 4.5.0
* @access public
*
* @param int|string $index Index, name, or ID of the dynamic sidebar.
*/
@ -1707,7 +1703,7 @@ final class WP_Customize_Widgets {
* Current sidebar being rendered.
*
* @since 4.5.0
* @access private
* @access protected
* @var string
*/
protected $rendering_widget_id;
@ -1716,19 +1712,19 @@ final class WP_Customize_Widgets {
* Current widget being rendered.
*
* @since 4.5.0
* @access private
* @access protected
* @var string
*/
protected $rendering_sidebar_id;
/**
* Filter sidebars_widgets to ensure the currently-rendered widget is the only widget in the current sidebar.
* Filters sidebars_widgets to ensure the currently-rendered widget is the only widget in the current sidebar.
*
* @since 4.5.0
* @access private
* @access protected
*
* @param array $sidebars_widgets Sidebars widgets.
* @return array Sidebars widgets.
* @return array Filtered sidebars widgets.
*/
public function filter_sidebars_widgets_for_rendering_widget( $sidebars_widgets ) {
$sidebars_widgets[ $this->rendering_sidebar_id ] = array( $this->rendering_widget_id );
@ -1736,19 +1732,19 @@ final class WP_Customize_Widgets {
}
/**
* Render a specific widget using the supplied sidebar arguments.
* Renders a specific widget using the supplied sidebar arguments.
*
* @since 4.5.0
* @access public
*
* @see dynamic_sidebar()
*
* @param WP_Customize_Partial $partial Partial.
* @param WP_Customize_Partial $partial Partial.
* @param array $context {
* Sidebar args supplied as container context.
*
* @type string $sidebar_id ID for sidebar for widget to render into.
* @type int [$sidebar_instance_number] Disambiguating instance number.
* @type string $sidebar_id ID for sidebar for widget to render into.
* @type int $sidebar_instance_number Disambiguating instance number.
* }
* @return string|false
*/
@ -1813,7 +1809,7 @@ final class WP_Customize_Widgets {
protected $_is_capturing_option_updates = false;
/**
* Determine whether the captured option update should be ignored.
* Determines whether the captured option update should be ignored.
*
* @since 3.9.0
* @access protected
@ -1826,7 +1822,7 @@ final class WP_Customize_Widgets {
}
/**
* Retrieve captured widget option updates.
* Retrieves captured widget option updates.
*
* @since 3.9.0
* @access protected
@ -1838,13 +1834,13 @@ final class WP_Customize_Widgets {
}
/**
* Get the option that was captured from being saved.
* Retrieves the option that was captured from being saved.
*
* @since 4.2.0
* @access protected
*
* @param string $option_name Option name.
* @param mixed $default Optional. Default value to return if the option does not exist.
* @param mixed $default Optional. Default value to return if the option does not exist. Default false.
* @return mixed Value set for the option.
*/
protected function get_captured_option( $option_name, $default = false ) {
@ -1857,7 +1853,7 @@ final class WP_Customize_Widgets {
}
/**
* Get the number of captured widget option updates.
* Retrieves the number of captured widget option updates.
*
* @since 3.9.0
* @access protected
@ -1869,7 +1865,7 @@ final class WP_Customize_Widgets {
}
/**
* Start keeping track of changes to widget options, caching new values.
* Begins keeping track of changes to widget options, caching new values.
*
* @since 3.9.0
* @access protected
@ -1885,7 +1881,7 @@ final class WP_Customize_Widgets {
}
/**
* Pre-filter captured option values before updating.
* Pre-filters captured option values before updating.
*
* @since 3.9.0
* @access public
@ -1910,7 +1906,7 @@ final class WP_Customize_Widgets {
}
/**
* Pre-filter captured option values before retrieving.
* Pre-filters captured option values before retrieving.
*
* @since 3.9.0
* @access public
@ -1932,7 +1928,7 @@ final class WP_Customize_Widgets {
}
/**
* Undo any changes to the options since options capture began.
* Undoes any changes to the options since options capture began.
*
* @since 3.9.0
* @access protected

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '4.5-beta2-36841';
$wp_version = '4.5-beta2-36842';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.