Index: wp-includes/class.wp-dependencies.php =================================================================== --- wp-includes/class.wp-dependencies.php (revision 23883) +++ wp-includes/class.wp-dependencies.php (working copy) @@ -21,27 +21,35 @@ var $queue = array(); var $to_do = array(); var $done = array(); - var $args = array(); - var $groups = array(); - var $group = 0; + var $args = array(); // In extending classes, strings appended to item urls. + var $groups = array(); // In extending class WP_Scripts, header and footer groups. + var $group = 0; // Internal group state. /** * Do the dependencies * - * Process the items passed to it or the queue. Processes all dependencies. + * Processes the items passed to it or the queue. Processes all dependencies. * - * @param mixed $handles (optional) items to be processed. (void) processes queue, (string) process that item, (array of strings) process those items - * @return array Items that have been processed + * @param mixed $handles (optional) Items to be processed: (false) Process queue, (string) process item, (array of strings) process items + * @param mixed $group Group level: (int) level, (false) no groups + * @return array Handles of items that have been processed */ function do_items( $handles = false, $group = false ) { - // Print the queue if nothing is passed. If a string is passed, print that script. If an array is passed, print those scripts. + // Print the queue if nothing is passed. If a string is passed, print that item. If an array is passed, print those items. $handles = false === $handles ? $this->queue : (array) $handles; $this->all_deps( $handles ); foreach( $this->to_do as $key => $handle ) { if ( !in_array($handle, $this->done, true) && isset($this->registered[$handle]) ) { - if ( ! $this->registered[$handle]->src ) { // Defines a group. + /** + * A single item may alias a set of items, by having dependencies but no src. + * Queuing the item queues the dependencies. + * Example: the extending class WP_Scripts is used to register 'scriptaculous' as a set of registered handles: + * add( 'scriptaculous', false, array('scriptaculous-dragdrop', 'scriptaculous-slider', 'scriptaculous-controls') ); + * The src property is false. + **/ + if ( ! $this->registered[$handle]->src ) { $this->done[] = $handle; continue; } @@ -56,18 +64,28 @@ return $this->done; } + /** + * Do dependency + * + * Processes one item for dependencies. + * + * @param string $handle Unique item name + * @return bool Success + */ function do_item( $handle ) { return isset($this->registered[$handle]); } /** - * Determines dependencies + * Determine dependencies * - * Recursively builds array of items to process taking dependencies into account. Does NOT catch infinite loops. + * Recursively builds array of items to process taking dependencies into account. + * Does NOT catch infinite loops. * - * - * @param mixed $handles Accepts (string) dep name or (array of strings) dep names - * @param bool $recursion Used internally when function calls itself + * @param mixed $handles (string) Dependency handle and argument or (array of strings) Dependency handles and arguments + * @param bool $recursion Internal flag that function is calling itself + * @param mixed $group Group level: (int) level, (false) no groups + * @return bool Success */ function all_deps( $handles, $recursion = false, $group = false ) { if ( !$handles = (array) $handles ) @@ -88,13 +106,13 @@ $keep_going = true; if ( !isset($this->registered[$handle]) ) - $keep_going = false; // Script doesn't exist + $keep_going = false; // Item doesn't exist elseif ( $this->registered[$handle]->deps && array_diff($this->registered[$handle]->deps, array_keys($this->registered)) ) - $keep_going = false; // Script requires deps which don't exist (not a necessary check. efficiency?) + $keep_going = false; // Item requires deps which don't exist (not a necessary check. efficiency?) elseif ( $this->registered[$handle]->deps && !$this->all_deps( $this->registered[$handle]->deps, true, $group ) ) - $keep_going = false; // Script requires deps which don't exist + $keep_going = false; // Item requires deps which don't exist - if ( !$keep_going ) { // Either script or its deps don't exist. + if ( !$keep_going ) { // Either item or its deps don't exist. if ( $recursion ) return false; // Abort this branch. else @@ -114,15 +132,16 @@ } /** - * Adds item + * Register item * - * Adds the item only if no item of that name already exists + * Registers the item if no item of that name already exists. * - * @param string $handle Script name - * @param string $src Script url - * @param array $deps (optional) Array of script names on which this script depends - * @param string $ver (optional) Script version (used for cache busting) - * @return array Hierarchical array of dependencies + * @param string $handle Unique item name + * @param string $src Resource url + * @param array of strings $deps (optional) Item handles on which this item depends + * @param string $ver (optional) Version (used for cache busting) + * @param mixed $args (optional) Custom property of the item. NOT the class property $args. Examples: $media, $in_footer. + * @return bool Success */ function add( $handle, $src, $deps = array(), $ver = false, $args = null ) { if ( isset($this->registered[$handle]) ) @@ -132,14 +151,14 @@ } /** - * Adds extra data + * Add extra data * - * Adds data only if script has already been added. + * Adds data if item has been registered. * - * @param string $handle Script name - * @param string $key - * @param mixed $value - * @return bool success + * @param string $handle Unique item name + * @param string $key Data key + * @param mixed $value Data value + * @return bool Success */ function add_data( $handle, $key, $value ) { if ( !isset( $this->registered[$handle] ) ) @@ -151,13 +170,13 @@ /** * Get extra data * - * Gets data associated with a certain handle. + * Gets data associated with a registered item. * * @since WP 3.3 * - * @param string $handle Script name - * @param string $key - * @return mixed + * @param string $handle Unique item name + * @param string $key Data key + * @return mixed Data value */ function get_data( $handle, $key ) { if ( !isset( $this->registered[$handle] ) ) @@ -169,11 +188,27 @@ return $this->registered[$handle]->extra[$key]; } + /** + * Unregister items + * + * @param mixed $handles (string) Item handle or (array of strings) Item handles + * @return void + */ function remove( $handles ) { foreach ( (array) $handles as $handle ) unset($this->registered[$handle]); } + /** + * Queue items + * + * Decode handle and argument, then queue handle and store argument in the class property $args. + * For example, in extending classes, $args is appended to the item url. + * Note $args is NOT the $args property of items in the $registered array. + * + * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments + * @return void + */ function enqueue( $handles ) { foreach ( (array) $handles as $handle ) { $handle = explode('?', $handle); @@ -185,6 +220,14 @@ } } + /** + * Dequeue items + * + * Decode handle and argument, then dequeue handle and remove argument from the class property $args. + * + * @param mixed $handles (string) Item handle and argument or (array of strings) Item handles and arguments + * @return void + */ function dequeue( $handles ) { foreach ( (array) $handles as $handle ) { $handle = explode('?', $handle); @@ -196,7 +239,12 @@ } } - + /** + * Query list for item + * + * @param $handle (string) Item handle + * @return bool Found, or object Item data + */ function query( $handle, $list = 'registered' ) { switch ( $list ) { case 'registered' : @@ -220,6 +268,14 @@ return false; } + /** + * Set item group, unless already in a lower group + * + * @param $handle (string) Item handle + * @param bool $recursion Internal flag that calling function was called recusively + * @param mixed $group Group level + * @return bool Not already in the group or a lower group + */ function set_group( $handle, $recursion, $group ) { $group = (int) $group; @@ -242,8 +298,7 @@ var $src; var $deps = array(); var $ver = false; - var $args = null; - + var $args = null; // Custom property, such as $in_footer or $media. var $extra = array(); function __construct() {