WordPress.org
Get WordPress

Make WordPress Core

Changeset 36842


Ignore:
Timestamp:
03/04/2016 02:01:15 AM (11 years ago)
Author:
DrewAPicture
Message:

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

See #32246. See #35986.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-customize-widgets.php

    r36841 r36842  
    113113
    114114        /**
    115          * Get the widget setting type given a setting ID.
     115         * Retrieves the widget setting type given a setting ID.
    116116         *
    117117         * @since 4.2.0
    … …  
    137137
    138138        /**
    139          * Inspect the incoming customized data for any widget settings, and dynamically add them up-front so widgets will be initialized properly.
     139         * Inspects the incoming customized data for any widget settings, and dynamically adds
     140         * them up-front so widgets will be initialized properly.
    140141         *
    141142         * @since 4.2.0
    … …  
    169170
    170171        /**
    171          * Determine the arguments for a dynamically-created setting.
     172         * Determines the arguments for a dynamically-created setting.
    172173         *
    173174         * @since 4.2.0
    … …  
    186187
    187188        /**
    188          * Get an unslashed post value or return a default.
    189          *
    190          * @since 3.9.0
    191          *
     189         * Retrieves an unslashed post value or return a default.
     190         *
     191         * @since 3.9.0
    192192         * @access protected
    193193         *
    … …  
    238238
    239239        /**
    240          * Filter old_sidebars_widgets_data Customizer setting.
    241          *
    242          * When switching themes, filter the Customizer setting
    243          * old_sidebars_widgets_data to supply initial $sidebars_widgets before they
    244          * were overridden by retrieve_widgets(). The value for
    245          * old_sidebars_widgets_data gets set in the old theme's sidebars_widgets
     240         * Filters old_sidebars_widgets_data Customizer setting.
     241         *
     242         * When switching themes, filter the Customizer setting old_sidebars_widgets_data
     243         * to supply initial $sidebars_widgets before they were overridden by retrieve_widgets().
     244         * The value for old_sidebars_widgets_data gets set in the old theme's sidebars_widgets
    246245         * theme_mod.
    247246         *
     247         * @since 3.9.0
     248         * @access public
     249         *
    248250         * @see WP_Customize_Widgets::handle_theme_switch()
    249          * @since 3.9.0
    250          * @access public
    251251         *
    252252         * @param array $old_sidebars_widgets
    … …  
    258258
    259259        /**
    260          * Filter sidebars_widgets option for theme switch.
    261          *
    262          * When switching themes, the retrieve_widgets() function is run when the
    263          * Customizer initializes, and then the new sidebars_widgets here get
    264          * supplied as the default value for the sidebars_widgets option.
     260         * Filters sidebars_widgets option for theme switch.
     261         *
     262         * When switching themes, the retrieve_widgets() function is run when the Customizer initializes,
     263         * and then the new sidebars_widgets here get supplied as the default value for the sidebars_widgets
     264         * option.
     265         *
     266         * @since 3.9.0
     267         * @access public
    265268         *
    266269         * @see WP_Customize_Widgets::handle_theme_switch()
    267          * @since 3.9.0
    268          * @access public
    269          *
    270270         * @global array $sidebars_widgets
    271271         *
    … …  
    280280
    281281        /**
    282          * Make sure all widgets get loaded into the Customizer.
     282         * Ensures all widgets get loaded into the Customizer.
    283283         *
    284284         * Note: these actions are also fired in wp_ajax_update_widget().
    … …  
    299299
    300300        /**
    301          * Ensure widgets are available for all types of previews.
    302          *
    303          * When in preview, hook to 'customize_register' for settings
    304          * after WordPress is loaded so that all filters have been
    305          * initialized (e.g. Widget Visibility).
     301         * Ensures widgets are available for all types of previews.
     302         *
     303         * When in preview, hook to 'customize_register' for settings after WordPress is loaded
     304         * so that all filters have been initialized (e.g. Widget Visibility).
    306305         *
    307306         * @since 3.9.0
    … …  
    317316
    318317        /**
    319          * Register Customizer settings and controls for all sidebars and widgets.
     318         * Registers Customizer settings and controls for all sidebars and widgets.
    320319         *
    321320         * @since 3.9.0
    … …  
    467466
    468467        /**
    469          * Return whether the widgets panel is active, based on whether there are sidebars registered.
     468         * Determines whether the widgets panel is active, based on whether there are sidebars registered.
    470469         *
    471470         * @since 4.4.0
    … …  
    483482
    484483        /**
    485          * Covert a widget_id into its corresponding Customizer setting ID (option name).
     484         * Converts a widget_id into its corresponding Customizer setting ID (option name).
    486485         *
    487486         * @since 3.9.0
    … …  
    502501
    503502        /**
    504          * Determine whether the widget is considered "wide".
    505          *
    506          * Core widgets which may have controls wider than 250, but can
    507          * still be shown in the narrow Customizer panel. The RSS and Text
    508          * widgets in Core, for example, have widths of 400 and yet they
    509          * still render fine in the Customizer panel. This method will
    510          * return all Core widgets as being not wide, but this can be
     503         * Determines whether the widget is considered "wide".
     504         *
     505         * Core widgets which may have controls wider than 250, but can still be shown
     506         * in the narrow Customizer panel. The RSS and Text widgets in Core, for example,
     507         * have widths of 400 and yet they still render fine in the Customizer panel.
     508         *
     509         * This method will return all Core widgets as being not wide, but this can be
    511510         * overridden with the is_wide_widget_in_customizer filter.
    512511         *
    … …  
    539538
    540539        /**
    541          * Covert a widget ID into its id_base and number components.
     540         * Converts a widget ID into its id_base and number components.
    542541         *
    543542         * @since 3.9.0
    … …  
    564563
    565564        /**
    566          * Convert a widget setting ID (option path) to its id_base and number components.
     565         * Converts a widget setting ID (option path) to its id_base and number components.
    567566         *
    568567         * @since 3.9.0
    … …  
    585584
    586585        /**
    587          * Call admin_print_styles-widgets.php and admin_print_styles hooks to
     586         * Calls admin_print_styles-widgets.php and admin_print_styles hooks to
    588587         * allow custom styles from plugins.
    589588         *
    … …  
    600599
    601600        /**
    602          * Call admin_print_scripts-widgets.php and admin_print_scripts hooks to
     601         * Calls admin_print_scripts-widgets.php and admin_print_scripts hooks to
    603602         * allow custom scripts from plugins.
    604603         *
    … …  
    615614
    616615        /**
    617          * Enqueue scripts and styles for Customizer panel and export data to JavaScript.
     616         * Enqueues scripts and styles for Customizer panel and export data to JavaScript.
    618617         *
    619618         * @since 3.9.0
    … …  
    707706
    708707        /**
    709          * Render the widget form control templates into the DOM.
     708         * Renders the widget form control templates into the DOM.
    710709         *
    711710         * @since 3.9.0
    … …  
    745744
    746745        /**
    747          * Call admin_print_footer_scripts and admin_print_scripts hooks to
     746         * Calls admin_print_footer_scripts and admin_print_scripts hooks to
    748747         * allow custom scripts from plugins.
    749748         *
    … …  
    760759
    761760        /**
    762          * Get common arguments to supply when constructing a Customizer setting.
     761         * Retrieves common arguments to supply when constructing a Customizer setting.
    763762         *
    764763         * @since 3.9.0
    … …  
    801800
    802801        /**
    803          * Make sure that sidebar widget arrays only ever contain widget IDS.
     802         * Ensures sidebar widget arrays only ever contain widget IDS.
    804803         *
    805804         * Used as the 'sanitize_callback' for each $sidebars_widgets setting.
    … …  
    821820
    822821        /**
    823          * Build up an index of all available widgets for use in Backbone models.
     822         * Builds up an index of all available widgets for use in Backbone models.
    824823         *
    825824         * @since 3.9.0
    … …  
    908907
    909908        /**
    910          * Naturally order available widgets by name.
     909         * Naturally orders available widgets by name.
    911910         *
    912911         * @since 3.9.0
    … …  
    922921
    923922        /**
    924          * Get the widget control markup.
     923         * Retrieves the widget control markup.
    925924         *
    926925         * @since 3.9.0
    … …  
    942941
    943942        /**
    944          * Get the widget control markup parts.
     943         * Retrieves the widget control markup parts.
    945944         *
    946945         * @since 4.4.0
    … …  
    949948         * @param array $args Widget control arguments.
    950949         * @return array {
    951          *     @type string $control  Markup for widget control wrapping form.
    952          *     @type string $content  The contents of the widget form itself.
     950         *     @type string $control Markup for widget control wrapping form.
     951         *     @type string $content The contents of the widget form itself.
    953952         * }
    954953         */
    … …  
    973972
    974973        /**
    975          * Add hooks for the Customizer preview.
     974         * Adds hooks for the Customizer preview.
    976975         *
    977976         * @since 3.9.0
    … …  
    985984
    986985        /**
    987          * Refresh nonce for widget updates.
     986         * Refreshes the nonce for widget updates.
    988987         *
    989988         * @since 4.2.0
    … …  
    999998
    1000999        /**
    1001          * When previewing, make sure the proper previewing widgets are used.
    1002          *
    1003          * Because wp_get_sidebars_widgets() gets called early at init
    1004          * (via wp_convert_widget_settings()) and can set global variable
    1005          * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' )
    1006          * before the Customizer preview filter is added, we have to reset
    1007          * it after the filter has been added.
     1000         * When previewing, ensures the proper previewing widgets are used.
     1001         *
     1002         * Because wp_get_sidebars_widgets() gets called early at {@see 'init' } (via
     1003         * wp_convert_widget_settings()) and can set global variable `$_wp_sidebars_widgets`
     1004         * to the value of `get_option( 'sidebars_widgets' )` before the Customizer preview
     1005         * filter is added, it has to be reset after the filter has been added.
    10081006         *
    10091007         * @since 3.9.0
    … …  
    10211019
    10221020        /**
    1023          * Enqueue scripts for the Customizer preview.
     1021         * Enqueues scripts for the Customizer preview.
    10241022         *
    10251023         * @since 3.9.0
    … …  
    10311029
    10321030        /**
    1033          * Insert default style for highlighted widget at early point so theme
     1031         * Inserts default style for highlighted widget at early point so theme
    10341032         * stylesheet can override.
    10351033         *
    10361034         * @since 3.9.0
    10371035         * @access public
    1038          *
    1039          * @action wp_print_styles
    10401036         */
    10411037        public function print_preview_css() {
    … …  
    10541050
    10551051        /**
    1056          * At the very end of the page, at the very end of the wp_footer,
    1057          * communicate the sidebars that appeared on the page.
     1052         * Communicates the sidebars that appeared on the page at the very end of the page,
     1053         * and at the very end of the wp_footer,
    10581054         *
    10591055         * @since 3.9.0
    … …  
    10881084
    10891085        /**
    1090          * Keep track of the widgets that were rendered.
     1086         * Tracks the widgets that were rendered.
    10911087         *
    10921088         * @since 3.9.0
    … …  
    11131109
    11141110        /**
    1115          * Determine if a sidebar is rendered on the page.
     1111         * Determines if a sidebar is rendered on the page.
    11161112         *
    11171113         * @since 4.0.0
    … …  
    11261122
    11271123        /**
    1128          * Tally the sidebars rendered via is_active_sidebar().
    1129          *
    1130          * Keep track of the times that is_active_sidebar() is called
    1131          * in the template, and assume that this means that the sidebar
    1132          * would be rendered on the template if there were widgets
    1133          * populating it.
     1124         * Tallies the sidebars rendered via is_active_sidebar().
     1125         *
     1126         * Keep track of the times that is_active_sidebar() is called in the template,
     1127         * and assume that this means that the sidebar would be rendered on the template
     1128         * if there were widgets populating it.
    11341129         *
    11351130         * @since 3.9.0
    … …  
    11381133         * @param bool   $is_active  Whether the sidebar is active.
    11391134         * @param string $sidebar_id Sidebar ID.
    1140          * @return bool
     1135         * @return bool Whether the sidebar is active.
    11411136         */
    11421137        public function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) {
    … …  
    11531148
    11541149        /**
    1155          * Tally the sidebars rendered via dynamic_sidebar().
     1150         * Tallies the sidebars rendered via dynamic_sidebar().
    11561151         *
    11571152         * Keep track of the times that dynamic_sidebar() is called in the template,
    … …  
    11641159         * @param bool   $has_widgets Whether the current sidebar has widgets.
    11651160         * @param string $sidebar_id  Sidebar ID.
    1166          * @return bool
     1161         * @return bool Whether the current sidebar has widgets.
    11671162         */
    11681163        public function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) {
    … …  
    11801175
    11811176        /**
    1182          * Get MAC for a serialized widget instance string.
     1177         * Retrieves MAC for a serialized widget instance string.
    11831178         *
    11841179         * Allows values posted back from JS to be rejected if any tampering of the
    … …  
    11961191
    11971192        /**
    1198          * Sanitize a widget instance.
    1199          *
    1200          * Unserialize the JS-instance for storing in the options. It's important
    1201          * that this filter only get applied to an instance once.
     1193         * Sanitizes a widget instance.
     1194         *
     1195         * Unserialize the JS-instance for storing in the options. It's important that this filter
     1196         * only get applied to an instance *once*.
    12021197         *
    12031198         * @since 3.9.0
    … …  
    12371232
    12381233        /**
    1239          * Convert widget instance into JSON-representable format.
     1234         * Converts a widget instance into JSON-representable format.
    12401235         *
    12411236         * @since 3.9.0
    … …  
    12601255
    12611256        /**
    1262          * Strip out widget IDs for widgets which are no longer registered.
     1257         * Strips out widget IDs for widgets which are no longer registered.
    12631258         *
    12641259         * One example where this might happen is when a plugin orphans a widget
    … …  
    12801275
    12811276        /**
    1282          * Find and invoke the widget update and control callbacks.
    1283          *
    1284          * Requires that $_POST be populated with the instance data.
     1277         * Finds and invokes the widget update and control callbacks.
     1278         *
     1279         * Requires that `$_POST` be populated with the instance data.
    12851280         *
    12861281         * @since 3.9.0
    … …  
    14071402
    14081403        /**
    1409          * Update widget settings asynchronously.
     1404         * Updates widget settings asynchronously.
    14101405         *
    14111406         * Allows the Customizer to update a widget using its form, but return the new
    14121407         * instance info via Ajax instead of saving it to the options table.
    14131408         *
    1414          * Most code here copied from wp_ajax_save_widget()
     1409         * Most code here copied from wp_ajax_save_widget().
    14151410         *
    14161411         * @since 3.9.0
    … …  
    14181413         *
    14191414         * @see wp_ajax_save_widget()
    1420          *
    14211415         */
    14221416        public function wp_ajax_update_widget() {
    … …  
    15071501
    15081502        /**
    1509          * Add hooks for selective refresh.
     1503         * Adds hooks for selective refresh.
    15101504         *
    15111505         * @since 4.5.0
    … …  
    15251519
    15261520        /**
    1527          * Enqueue scripts for the Customizer preview.
     1521         * Enqueues scripts for the Customizer preview.
    15281522         *
    15291523         * @since 4.5.0
    … …  
    16001594         * List of the tag names seen for before_widget strings.
    16011595         *
    1602          * This is used in the filter_wp_kses_allowed_html filter to ensure that the
     1596         * This is used in the {@see 'filter_wp_kses_allowed_html'} filter to ensure that the
    16031597         * data-* attributes can be whitelisted.
    16041598         *
    16051599         * @since 4.5.0
    1606          * @access private
     1600         * @access protected
    16071601         * @var array
    16081602         */
    … …  
    16101604
    16111605        /**
    1612          * Ensure that the HTML data-* attributes for selective refresh are allowed by kses.
    1613          *
    1614          * This is needed in case the $before_widget is run through wp_kses() when printed.
     1606         * Ensures the HTML data-* attributes for selective refresh are allowed by kses.
     1607         *
     1608         * This is needed in case the `$before_widget` is run through wp_kses() when printed.
    16151609         *
    16161610         * @since 4.5.0
    … …  
    16181612         *
    16191613         * @param array $allowed_html Allowed HTML.
    1620          * @return array Allowed HTML.
     1614         * @return array (Maybe) modified allowed HTML.
    16211615         */
    16221616        public function filter_wp_kses_allowed_data_attributes( $allowed_html ) {
    … …  
    16451639         *
    16461640         * @since 4.5.0
    1647          * @access private
     1641         * @access protected
    16481642         * @var array
    16491643         */
    … …  
    16541648         *
    16551649         * @since 4.5.0
    1656          * @access private
     1650         * @access protected
    16571651         * @var int
    16581652         */
    … …  
    16631657         *
    16641658         * @since 4.5.0
    1665          * @access private
     1659         * @access protected
    16661660         * @var array
    16671661         */
    … …  
    16691663
    16701664        /**
    1671          * Start keeping track of the current sidebar being rendered.
     1665         * Begins keeping track of the current sidebar being rendered.
    16721666         *
    16731667         * Insert marker before widgets are rendered in a dynamic sidebar.
    16741668         *
    16751669         * @since 4.5.0
     1670         * @access public
    16761671         *
    16771672         * @param int|string $index Index, name, or ID of the dynamic sidebar.
    … …  
    16891684
    16901685        /**
    1691          * Finish keeping track of the current sidebar being rendered.
    1692          *
    1693          * Insert marker after widgets are rendered in a dynamic sidebar.
     1686         * Finishes keeping track of the current sidebar being rendered.
     1687         *
     1688         * Inserts a marker after widgets are rendered in a dynamic sidebar.
    16941689         *
    16951690         * @since 4.5.0
     1691         * @access public
    16961692         *
    16971693         * @param int|string $index Index, name, or ID of the dynamic sidebar.
    … …  
    17081704         *
    17091705         * @since 4.5.0
    1710          * @access private
     1706         * @access protected
    17111707         * @var string
    17121708         */
    … …  
    17171713         *
    17181714         * @since 4.5.0
    1719          * @access private
     1715         * @access protected
    17201716         * @var string
    17211717         */
    … …  
    17231719
    17241720        /**
    1725          * Filter sidebars_widgets to ensure the currently-rendered widget is the only widget in the current sidebar.
     1721         * Filters sidebars_widgets to ensure the currently-rendered widget is the only widget in the current sidebar.
    17261722         *
    17271723         * @since 4.5.0
    1728          * @access private
     1724         * @access protected
    17291725         *
    17301726         * @param array $sidebars_widgets Sidebars widgets.
    1731          * @return array Sidebars widgets.
     1727         * @return array Filtered sidebars widgets.
    17321728         */
    17331729        public function filter_sidebars_widgets_for_rendering_widget( $sidebars_widgets ) {
    … …  
    17371733
    17381734        /**
    1739          * Render a specific widget using the supplied sidebar arguments.
     1735         * Renders a specific widget using the supplied sidebar arguments.
    17401736         *
    17411737         * @since 4.5.0
    … …  
    17441740         * @see dynamic_sidebar()
    17451741         *
    1746          * @param WP_Customize_Partial $partial      Partial.
     1742         * @param WP_Customize_Partial $partial Partial.
    17471743         * @param array                $context {
    17481744         *     Sidebar args supplied as container context.
    17491745         *
    1750          *     @type string $sidebar_id                ID for sidebar for widget to render into.
    1751          *     @type int    [$sidebar_instance_number] Disambiguating instance number.
     1746         *     @type string $sidebar_id              ID for sidebar for widget to render into.
     1747         *     @type int    $sidebar_instance_number Disambiguating instance number.
    17521748         * }
    17531749         * @return string|false
    … …  
    18141810
    18151811        /**
    1816          * Determine whether the captured option update should be ignored.
     1812         * Determines whether the captured option update should be ignored.
    18171813         *
    18181814         * @since 3.9.0
    … …  
    18271823
    18281824        /**
    1829          * Retrieve captured widget option updates.
     1825         * Retrieves captured widget option updates.
    18301826         *
    18311827         * @since 3.9.0
    … …  
    18391835
    18401836        /**
    1841          * Get the option that was captured from being saved.
     1837         * Retrieves the option that was captured from being saved.
    18421838         *
    18431839         * @since 4.2.0
    … …  
    18451841         *
    18461842         * @param string $option_name Option name.
    1847          * @param mixed  $default     Optional. Default value to return if the option does not exist.
     1843         * @param mixed  $default     Optional. Default value to return if the option does not exist. Default false.
    18481844         * @return mixed Value set for the option.
    18491845         */
    … …  
    18581854
    18591855        /**
    1860          * Get the number of captured widget option updates.
     1856         * Retrieves the number of captured widget option updates.
    18611857         *
    18621858         * @since 3.9.0
    … …  
    18701866
    18711867        /**
    1872          * Start keeping track of changes to widget options, caching new values.
     1868         * Begins keeping track of changes to widget options, caching new values.
    18731869         *
    18741870         * @since 3.9.0
    … …  
    18861882
    18871883        /**
    1888          * Pre-filter captured option values before updating.
     1884         * Pre-filters captured option values before updating.
    18891885         *
    18901886         * @since 3.9.0
    … …  
    19111907
    19121908        /**
    1913          * Pre-filter captured option values before retrieving.
     1909         * Pre-filters captured option values before retrieving.
    19141910         *
    19151911         * @since 3.9.0
    … …  
    19331929
    19341930        /**
    1935          * Undo any changes to the options since options capture began.
     1931         * Undoes any changes to the options since options capture began.
    19361932         *
    19371933         * @since 3.9.0
Note: See TracChangeset for help on using the changeset viewer.