WordPress.org

Make WordPress Core

Changeset 25597


Ignore:
Timestamp:
09/24/2013 02:57:56 AM (7 years ago)
Author:
DrewAPicture
Message:

Improve inline documentation for wp-includes/functions.wp-scripts.php.

Props kpdesign.
Fixes #25402.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/functions.wp-scripts.php

    r25449 r25597  
    11<?php
    22/**
    3  * BackPress script procedural API.
    4  *
    5  * @package BackPress
    6  * @since r16
    7  */
    8 
    9 /**
    10  * Prints script tags in document head.
    11  *
    12  * Called by admin-header.php and by wp_head hook. Since it is called by wp_head
    13  * on every page load, the function does not instantiate the WP_Scripts object
    14  * unless script names are explicitly passed. Does make use of already
    15  * instantiated $wp_scripts if present. Use provided wp_print_scripts hook to
    16  * register/enqueue new scripts.
    17  *
    18  * @since r16
    19  * @see WP_Dependencies::print_scripts()
     3 * BackPress Scripts Procedural API
     4 *
     5 * @since 2.6.0
     6 *
     7 * @package WordPress
     8 * @subpackage BackPress
     9 */
     10
     11/**
     12 * Print scripts in document head that are in the $handles queue.
     13 *
     14 * Called by admin-header.php and wp_head hook. Since it is called by wp_head on every page load,
     15 * the function does not instantiate the WP_Scripts object unless script names are explicitly passed.
     16 * Makes use of already-instantiated $wp_scripts global if present. Use provided wp_print_scripts
     17 * hook to register/enqueue new scripts.
     18 *
     19 * @see WP_Scripts::do_items()
     20 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
     21 *
     22 * @since 2.6.0
     23 *
     24 * @param array|bool $handles Optional. Scripts to be printed. Default 'false'.
     25 * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
    2026 */
    2127function wp_print_scripts( $handles = false ) {
     
    4046
    4147/**
    42  * Register new Javascript file.
    43  *
    44  * @since r16
    45  * @param string $handle Script name
    46  * @param string $src Script url
    47  * @param array $deps (optional) Array of script names on which this script depends
    48  * @param string|bool $ver (optional) Script version (used for cache busting), set to null to disable
    49  * @param bool $in_footer (optional) Whether to enqueue the script before </head> or before </body>
    50  * @return null
     48 * Register a new script.
     49 *
     50 * Registers a script to be linked later using the wp_enqueue_script() function.
     51 *
     52 * @see WP_Dependencies::add(), WP_Dependencies::add_data()
     53 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
     54 *
     55 * @since 2.6.0
     56 *
     57 * @param string      $handle    Name of the script. Should be unique.
     58 * @param string      $src       Path to the script from the WordPress root directory. Example: '/js/myscript.js'.
     59 * @param array       $deps      Optional. An array of registered script handles this script depends on. Set to false if there
     60 *                               are no dependencies. Default empty array.
     61 * @param string|bool $ver       Optional. String specifying script version number, if it has one, which is concatenated
     62 *                               to end of path as a query string. If no version is specified or set to false, a version
     63 *                               number is automatically added equal to current installed WordPress version.
     64 *                               If set to null, no version is added. Default 'false'. Accepts 'false', 'null', or 'string'.
     65 * @param bool        $in_footer Optional. Whether to enqueue the script before </head> or before </body>.
     66 *                               Default 'false'. Accepts 'false' or 'true'.
    5167 */
    5268function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false ) {
     
    6581
    6682/**
    67  * Wrapper for $wp_scripts->localize().
    68  *
    69  * Used to localize a script.
     83 * Localize a script.
     84 *
    7085 * Works only if the script has already been added.
    71  * Accepts an associative array $l10n and creates JS object:
     86 *
     87 * Accepts an associative array $l10n and creates a JavaScript object:
     88 * <code>
    7289 * "$object_name" = {
    73  *   key: value,
    74  *   key: value,
    75  *   ...
     90 *       key: value,
     91 *       key: value,
     92 *       ...
    7693 * }
    77  * See http://core.trac.wordpress.org/ticket/11520 for more information.
    78  *
    79  * @since r16
    80  *
    81  * @param string $handle The script handle that was registered or used in script-loader
    82  * @param string $object_name Name for the created JS object. This is passed directly so it should be qualified JS variable /[a-zA-Z0-9_]+/
    83  * @param array $l10n Associative PHP array containing the translated strings. HTML entities will be converted and the array will be JSON encoded.
    84  * @return bool Whether the localization was added successfully.
     94 * </code>
     95 *
     96 * @see WP_Dependencies::localize()
     97 * @link http://core.trac.wordpress.org/ticket/11520
     98 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
     99 *
     100 * @since 2.6.0
     101 *
     102 * @param string $handle      Script handle the data will be attached to.
     103 * @param string $object_name Name for the JavaScript object. Passed directly, so it should be qualified JS variable.
     104 *                            Example: '/[a-zA-Z0-9_]+/'.
     105 * @param array $l10n         The data itself. The data can be either a single or multi-dimensional array.
     106 * @return bool True if the script was successfully localized, false otherwise.
    85107 */
    86108function wp_localize_script( $handle, $object_name, $l10n ) {
     
    100122 * Remove a registered script.
    101123 *
    102  * @since r16
    103  * @see WP_Scripts::remove() For parameter information.
     124 * Note: there are intentional safeguards in place to prevent critical admin scripts,
     125 * such as jQuery core, from being unregistered.
     126 *
     127 * @see WP_Dependencies::remove()
     128 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
     129 *
     130 * @since 2.6.0
     131 *
     132 * @param string $handle Name of the script to be removed.
    104133 */
    105134function wp_deregister_script( $handle ) {
     
    112141    }
    113142
    114     // Do not allow accidental or negligent deregistering of critical scripts in the admin.
    115     // Show minimal remorse if the correct hook is used.
     143    /**
     144     * Do not allow accidental or negligent de-registering of critical scripts in the admin.
     145     * Show minimal remorse if the correct hook is used.
     146     */
    116147    $current_filter = current_filter();
    117148    if ( ( is_admin() && 'admin_enqueue_scripts' !== $current_filter ) ||
     
    124155            'jquery-ui-position', 'jquery-ui-progressbar', 'jquery-ui-resizable', 'jquery-ui-selectable',
    125156            'jquery-ui-slider', 'jquery-ui-sortable', 'jquery-ui-spinner', 'jquery-ui-tabs',
    126             'jquery-ui-tooltip', 'jquery-ui-widget',
    127             'underscore', 'backbone',
     157            'jquery-ui-tooltip', 'jquery-ui-widget', 'underscore', 'backbone',
    128158        );
    129159
     
    140170
    141171/**
    142  * Enqueues script.
    143  *
    144  * Registers the script if src provided (does NOT overwrite) and enqueues.
    145  *
    146  * @since r16
    147  * @see wp_register_script() For parameter information.
     172 * Enqueue a script.
     173 *
     174 * Registers the script if $src provided (does NOT overwrite), and enqueues it.
     175 *
     176 * @see WP_Dependencies::add(), WP_Dependencies::add_data(), WP_Dependencies::enqueue()
     177 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
     178 *
     179 * @since 2.6.0
     180
     181 * @param string      $handle    Name of the script.
     182 * @param string|bool $src       Path to the script from the root directory of WordPress. Example: '/js/myscript.js'.
     183 * @param array       $deps      An array of registered handles this script depends on. Default empty array.
     184 * @param string|bool $ver       Optional. String specifying the script version number, if it has one. This parameter
     185 *                               is used to ensure that the correct version is sent to the client regardless of caching,
     186 *                               and so should be included if a version number is available and makes sense for the script.
     187 * @param bool        $in_footer Optional. Whether to enqueue the script before </head> or before </body>.
     188 *                               Default 'false'. Accepts 'false' or 'true'.
    148189 */
    149190function wp_enqueue_script( $handle, $src = false, $deps = array(), $ver = false, $in_footer = false ) {
     
    166207
    167208/**
    168  * Remove an enqueued script.
     209 * Remove a previously enqueued script.
     210 *
     211 * @see WP_Dependencies::dequeue()
     212 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
    169213 *
    170214 * @since 3.1.0
    171  * @see WP_Scripts::dequeue() For parameter information.
     215 *
     216 * @param string $handle Name of the script to be removed.
    172217 */
    173218function wp_dequeue_script( $handle ) {
     
    184229
    185230/**
    186  * Check whether script has been added to WordPress Scripts.
    187  *
    188  * By default, checks if the script has been enqueued. You can also
    189  * pass 'registered' to $list, to see if the script is registered,
    190  * and you can check processing statuses with 'to_do' and 'done'.
     231 * Check whether a script has been added to the queue.
     232 *
     233 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
    191234 *
    192235 * @since 2.8.0
     236 * @since 3.5.0 'enqueued' added as an alias of the 'queue' list.
    193237 *
    194238 * @param string $handle Name of the script.
    195  * @param string $list Optional. Defaults to 'enqueued'. Values are
    196  *  'registered', 'enqueued' (or 'queue'), 'to_do', and 'done'.
    197  * @return bool Whether script is in the list.
     239 * @param string $list   Optional. Status of the script to check. Default 'enqueued'.
     240 *                       Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'.
     241 * @return bool Whether the script script is queued.
    198242 */
    199243function wp_script_is( $handle, $list = 'enqueued' ) {
Note: See TracChangeset for help on using the changeset viewer.