WordPress.org
Get WordPress

Make WordPress Core

Changeset 36842


Ignore:
Timestamp:
03/04/2016 02:01:15 AM (9 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.