WordPress.org
Get WordPress

Make WordPress Core

Ticket #23914: 23914.diff

File 23914.diff, 11.9 KB (added by DrewAPicture, 12 years ago)

+ properties + _WP_Dependency + other stuff.

  • src/wp-includes/class.wp-dependencies.php

     
    11<?php
    22/**
    3  * BackPress Scripts enqueue.
     3 * BackPress Scripts enqueue
    44 *
    5  * These classes were refactored from the WordPress WP_Scripts and WordPress
    6  * script enqueue API.
     5 * Classes were refactored from the WP_Scripts and WordPress script enqueue API.
    76 *
    8  * @package BackPress
    97 * @since r74
    10  */
    11 
    12 /**
    13  * BackPress enqueued dependiences class.
    148 *
    159 * @package BackPress
    16  * @uses _WP_Dependency
    17  * @since r74
    1810 */
    1911class WP_Dependencies {
     12        /**
     13         * An array of registered handle objects.
     14         *
     15         * @access public
     16         * @since 2.6.8
     17         * @var array
     18         */
    2019        var $registered = array();
     20
     21        /**
     22         * An array of queued _WP_Dependency handle objects.
     23         *
     24         * @access public
     25         * @since 2.6.8
     26         * @var array
     27         */
    2128        var $queue = array();
     29
     30        /**
     31         * An array of _WP_Dependency handle objects to queue.
     32         *
     33         * @access public
     34         * @since 2.6.0
     35         * @var array
     36         */
    2237        var $to_do = array();
     38
     39        /**
     40         * An array of _WP_Dependency handle objects already queued.
     41         *
     42         * @access public
     43         * @since 2.6.0
     44         * @var array
     45         */
    2346        var $done = array();
     47
     48        /**
     49         * An array of additional arguments passed when a handle is registered.
     50         *
     51         * Arguments are appended to the item query string.
     52         *
     53         * @access public
     54         * @since 2.6.0
     55         * @var array
     56         */
    2457        var $args = array();
     58
     59        /**
     60         * An array of handle groups to enqueue.
     61         *
     62         * @access public
     63         * @since 2.8.0
     64         * @var array
     65         */
    2566        var $groups = array();
     67
     68        /**
     69         * A handle group to enqueue.
     70         *
     71         * @access public
     72         * @since 2.8.0
     73         * @var int
     74         */
    2675        var $group = 0;
    2776
    2877        /**
    29          * Do the dependencies
     78         * Do the dependencies.
    3079         *
    31          * Process the items passed to it or the queue. Processes all dependencies.
     80         * Processes the items passed to it or the queue. Processes all dependencies.
    3281         *
    33          * @param mixed $handles (optional) items to be processed. (void) processes queue, (string) process that item, (array of strings) process those items
    34          * @return array Items that have been processed
     82         * @since Unknown
     83         *
     84         * @param mixed $handles (optional) Items to be processed: (false) Process queue, (string) process item, (array of strings) process items.
     85         * @param mixed $group   Group level: (int) level, (false) no groups.
     86         * @return array Handles of items that have been processed.
    3587         */
    3688        function do_items( $handles = false, $group = false ) {
    37                 // Print the queue if nothing is passed. If a string is passed, print that script. If an array is passed, print those scripts.
     89                // Print the queue if nothing is passed. If a string is passed, print that item. If an array is passed, print those items.
    3890                $handles = false === $handles ? $this->queue : (array) $handles;
    3991                $this->all_deps( $handles );
    4092
    4193                foreach( $this->to_do as $key => $handle ) {
    4294                        if ( !in_array($handle, $this->done, true) && isset($this->registered[$handle]) ) {
    4395
    44                                 if ( ! $this->registered[$handle]->src ) { // Defines a group.
     96                                /**
     97                                 * A single item may alias a set of items, by having dependencies but no src.
     98                                 * Queuing the item queues the dependencies.
     99                                 * Example: the extending class WP_Scripts is used to register 'scriptaculous' as a set of registered handles:
     100                                 *   <code>add( 'scriptaculous', false, array( 'scriptaculous-dragdrop', 'scriptaculous-slider', 'scriptaculous-controls' ) );</code>
     101                                 * The src property is false.
     102                                **/
     103                                if ( ! $this->registered[$handle]->src ) {
    45104                                        $this->done[] = $handle;
    46105                                        continue;
    47106                                }
    … …  
    56115                return $this->done;
    57116        }
    58117
     118        /**
     119         * Do a single dependency.
     120         *
     121         * Processes one item for dependencies.
     122         *
     123         * @since Unknown
     124         *
     125         * @param string $handle Unique item name.
     126         * @return bool True on success, false on failure.
     127         */
    59128        function do_item( $handle ) {
    60129                return isset($this->registered[$handle]);
    61130        }
    62131
    63132        /**
    64          * Determines dependencies
     133         * Determine dependencies.
    65134         *
    66          * Recursively builds array of items to process taking dependencies into account. Does NOT catch infinite loops.
     135         * Recursively builds array of items to process taking dependencies into account.
     136         * Does NOT catch infinite loops.
    67137         *
     138         * @since Unknown
    68139         *
    69          * @param mixed $handles Accepts (string) dep name or (array of strings) dep names
    70          * @param bool $recursion Used internally when function calls itself
     140         * @param mixed $handles   (string) Dependency handle and argument or (array of strings) Dependency handles and arguments.
     141         * @param bool  $recursion Internal flag that function is calling itself.
     142         * @param mixed $group     Group level: (int) level, (false) no groups.
     143         * @return bool Success
    71144         */
    72145        function all_deps( $handles, $recursion = false, $group = false ) {
    73146                if ( !$handles = (array) $handles )
    … …  
    88161
    89162                        $keep_going = true;
    90163                        if ( !isset($this->registered[$handle]) )
    91                                 $keep_going = false; // Script doesn't exist
     164                                $keep_going = false; // Item doesn't exist
    92165                        elseif ( $this->registered[$handle]->deps && array_diff($this->registered[$handle]->deps, array_keys($this->registered)) )
    93                                 $keep_going = false; // Script requires deps which don't exist (not a necessary check. efficiency?)
     166                                $keep_going = false; // Item requires deps which don't exist (not a necessary check. efficiency?)
    94167                        elseif ( $this->registered[$handle]->deps && !$this->all_deps( $this->registered[$handle]->deps, true, $group ) )
    95                                 $keep_going = false; // Script requires deps which don't exist
     168                                $keep_going = false; // Item requires deps which don't exist
    96169
    97                         if ( !$keep_going ) { // Either script or its deps don't exist.
     170                        if ( ! $keep_going ) { // Either item or its deps don't exist.
    98171                                if ( $recursion )
    99172                                        return false; // Abort this branch.
    100173                                else
    101174                                        continue; // We're at the top level. Move on to the next one.
    102175                        }
    103176
    104                         if ( $queued ) // Already grobbed it and its deps
     177                        if ( $queued ) // Already grabbed it and its deps
    105178                                continue;
    106179
    107180                        if ( isset($handle_parts[1]) )
    … …  
    114187        }
    115188
    116189        /**
    117          * Adds item
     190         * Register an item.
    118191         *
    119          * Adds the item only if no item of that name already exists
     192         * Registers the item if no item of that name already exists.
    120193         *
    121          * @param string $handle Script name
    122          * @param string $src Script url
    123          * @param array $deps (optional) Array of script names on which this script depends
    124          * @param string $ver (optional) Script version (used for cache busting)
    125          * @return array Hierarchical array of dependencies
     194         * @since Unknown
     195         *
     196         * @param string $handle Unique item name.
     197         * @param string $src    The item url.
     198         * @param array  $deps   (optional) An array of item handle strings on which this item depends.
     199         * @param string $ver    (optional) Version (used for cache busting).
     200         * @param mixed  $args   (optional) Custom property of the item. NOT the class property $args. Examples: $media, $in_footer.
     201         * @return bool True on success, false on failure.
    126202         */
    127203        function add( $handle, $src, $deps = array(), $ver = false, $args = null ) {
    128204                if ( isset($this->registered[$handle]) )
    … …  
    132208        }
    133209
    134210        /**
    135          * Adds extra data
     211         * Add extra item data.
    136212         *
    137          * Adds data only if script has already been added.
     213         * Adds data to a registered item.
    138214         *
    139          * @param string $handle Script name
    140          * @param string $key
    141          * @param mixed $value
    142          * @return bool success
     215         * @param string $handle Unique item name.
     216         * @param string $key    Data key.
     217         * @param mixed  $value  Data value.
     218         * @return bool True on success, false on failure.
    143219         */
    144220        function add_data( $handle, $key, $value ) {
    145221                if ( !isset( $this->registered[$handle] ) )
    … …  
    149225        }
    150226
    151227        /**
    152          * Get extra data
     228         * Get extra item data.
    153229         *
    154          * Gets data associated with a certain handle.
     230         * Gets data associated with a registered item.
    155231         *
    156          * @since WP 3.3
     232         * @since 3.3.0
    157233         *
    158          * @param string $handle Script name
    159          * @param string $key
    160          * @return mixed
     234         * @param string $handle Unique item name.
     235         * @param string $key    Data key.
     236         * @return mixed (string) Extra item data, false otherwise.
    161237         */
    162238        function get_data( $handle, $key ) {
    163239                if ( !isset( $this->registered[$handle] ) )
    … …  
    169245                return $this->registered[$handle]->extra[$key];
    170246        }
    171247
     248        /**
     249         * Unregister and item or items.
     250         *
     251         * @since Unknown
     252         *
     253         * @param mixed $handles (string) Item handle or (array of strings) Item handles.
     254         * @return void
     255         */
    172256        function remove( $handles ) {
    173257                foreach ( (array) $handles as $handle )
    174258                        unset($this->registered[$handle]);
    175259        }
    176260
     261        /**
     262         * Queue an item or items.
     263         *
     264         * Decodes handles and arguments, then queues handles and stores
     265         * arguments in the class property $args. For example in extending
     266         * classes, $args is appended to the item url as a query string.
     267         * Note $args is NOT the $args property of items in the $registered array.
     268         *
     269         * @since Unknown
     270         *
     271         * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments
     272         * @return void
     273         */
    177274        function enqueue( $handles ) {
    178275                foreach ( (array) $handles as $handle ) {
    179276                        $handle = explode('?', $handle);
    … …  
    185282                }
    186283        }
    187284
     285        /**
     286         * Dequeue an item or items.
     287         *
     288         * Decodes handles and arguments, then dequeues handles and removes arguments from the class property $args.
     289         *
     290         * @since Unknown
     291         *
     292         * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments
     293         * @return void
     294         */
    188295        function dequeue( $handles ) {
    189296                foreach ( (array) $handles as $handle ) {
    190297                        $handle = explode('?', $handle);
    … …  
    196303                }
    197304        }
    198305
    199 
     306        /**
     307         * Query list for an item.
     308         *
     309         * @since Unknown
     310         *
     311         * @param string $handle The item handle.
     312         * @param string $list   Property name of list array.
     313         * @return bool Found, or object Item data.
     314         */
    200315        function query( $handle, $list = 'registered' ) {
    201316                switch ( $list ) {
    202317                        case 'registered' :
    … …  
    220335                return false;
    221336        }
    222337
     338        /**
     339         * Set item group, unless already in a lower group.
     340         *
     341         * @since Unknown
     342         *
     343         * @param string $handle    The item handle.
     344         * @param bool   $recursion Internal flag that calling function was called recursively.
     345         * @param mixed  $group     Group level.
     346         * @return bool Not already in the group or a lower group
     347         */
    223348        function set_group( $handle, $recursion, $group ) {
    224349                $group = (int) $group;
    225350
    … …  
    237362
    238363}
    239364
     365/**
     366 * Class _WP_Dependency
     367 *
     368 * Registers a handle and associated data.
     369 *
     370 * @access private
     371 * @since 2.6.0
     372 */
    240373class _WP_Dependency {
     374        /**
     375         * The handle name.
     376         *
     377         * @access public
     378         * @since 2.6.0
     379         * @var null
     380         */
    241381        var $handle;
     382
     383        /**
     384         * The handle source.
     385         *
     386         * @access public
     387         * @since 2.6.0
     388         * @var null
     389         */
    242390        var $src;
     391
     392        /**
     393         * An array of handle dependencies.
     394         *
     395         * @access public
     396         * @since 2.6.0
     397         * @var array
     398         */
    243399        var $deps = array();
     400
     401        /**
     402         * The handle version.
     403         *
     404         * Used for cache-busting.
     405         *
     406         * @access public
     407         * @since 2.6.0
     408         * @var bool|string
     409         */
    244410        var $ver = false;
    245         var $args = null;
    246411
     412        /**
     413         * Additional arguments for the handle.
     414         *
     415         * @access public
     416         * @since 2.6.0
     417         * @var null
     418         */
     419        var $args = null;  // Custom property, such as $in_footer or $media.
     420
     421        /**
     422         * Extra data to supply to the handle.
     423         *
     424         * @access public
     425         * @since 2.6.0
     426         * @var array
     427         */
    247428        var $extra = array();
    248429
     430        /**
     431         * Setup dependencies.
     432         *
     433         * @since 2.6.0
     434         */
    249435        function __construct() {
    250436                @list( $this->handle, $this->src, $this->deps, $this->ver, $this->args ) = func_get_args();
    251437                if ( ! is_array($this->deps) )
    252438                        $this->deps = array();
    253439        }
    254440
     441        /**
     442         * Add handle data.
     443         *
     444         * @param string $name The data key to add.
     445         * @param mixed  $data The data value to add.
     446         * @return bool False if not scalar, true otherwise.
     447         */
    255448        function add_data( $name, $data ) {
    256449                if ( !is_scalar($name) )
    257450                        return false;