WordPress 4.3
[autoinstalls/wordpress.git] / wp-includes / functions.wp-scripts.php
index 6eb7a44f899868b167b35dd8b5e259090eafcbaf..01ad19b1c21d25a750a48dd938e0bf46ca37976e 100644 (file)
@@ -8,6 +8,44 @@
  * @subpackage BackPress
  */
 
+/**
+ * Initialize $wp_scripts if it has not been set.
+ *
+ * @global WP_Scripts $wp_scripts
+ *
+ * @since 4.2.0
+ *
+ * @return WP_Scripts WP_Scripts instance.
+ */
+function wp_scripts() {
+       global $wp_scripts;
+       if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
+               $wp_scripts = new WP_Scripts();
+       }
+       return $wp_scripts;
+}
+
+/**
+ * Helper function to output a _doing_it_wrong message when applicable.
+ *
+ * @ignore
+ * @since 4.2.0
+ *
+ * @param string $function Function name.
+ */
+function _wp_scripts_maybe_doing_it_wrong( $function ) {
+       if ( did_action( 'init' ) ) {
+               return;
+       }
+
+       _doing_it_wrong( $function, sprintf(
+               __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
+               '<code>wp_enqueue_scripts</code>',
+               '<code>admin_enqueue_scripts</code>',
+               '<code>login_enqueue_scripts</code>'
+       ), '3.3' );
+}
+
 /**
  * Print scripts in document head that are in the $handles queue.
  *
@@ -31,22 +69,20 @@ function wp_print_scripts( $handles = false ) {
         * @since 2.1.0
         */
        do_action( 'wp_print_scripts' );
-       if ( '' === $handles ) // for wp_head
+       if ( '' === $handles ) // for wp_head
                $handles = false;
+       }
 
-       global $wp_scripts;
-       if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
-               if ( ! did_action( 'init' ) )
-                       _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
-                               '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
+       _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
 
-               if ( !$handles )
+       global $wp_scripts;
+       if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
+               if ( ! $handles ) {
                        return array(); // No need to instantiate if nothing is there.
-               else
-                       $wp_scripts = new WP_Scripts();
+               }
        }
 
-       return $wp_scripts->do_items( $handles );
+       return wp_scripts()->do_items( $handles );
 }
 
 /**
@@ -55,9 +91,9 @@ function wp_print_scripts( $handles = false ) {
  * Registers a script to be linked later using the wp_enqueue_script() function.
  *
  * @see WP_Dependencies::add(), WP_Dependencies::add_data()
- * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
  *
  * @since 2.6.0
+ * @since 4.3.0 A return value was added.
  *
  * @param string      $handle    Name of the script. Should be unique.
  * @param string      $src       Path to the script from the WordPress root directory. Example: '/js/myscript.js'.
@@ -69,19 +105,18 @@ function wp_print_scripts( $handles = false ) {
  *                               If set to null, no version is added. Default 'false'. Accepts 'false', 'null', or 'string'.
  * @param bool        $in_footer Optional. Whether to enqueue the script before </head> or before </body>.
  *                               Default 'false'. Accepts 'false' or 'true'.
+ * @return bool Whether the script has been registered. True on success, false on failure.
  */
 function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false ) {
-       global $wp_scripts;
-       if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
-               if ( ! did_action( 'init' ) )
-                       _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
-                               '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
-               $wp_scripts = new WP_Scripts();
-       }
+       $wp_scripts = wp_scripts();
+       _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
 
-       $wp_scripts->add( $handle, $src, $deps, $ver );
-       if ( $in_footer )
+       $registered = $wp_scripts->add( $handle, $src, $deps, $ver );
+       if ( $in_footer ) {
                $wp_scripts->add_data( $handle, 'group', 1 );
+       }
+
+       return $registered;
 }
 
 /**
@@ -114,11 +149,8 @@ function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_f
  */
 function wp_localize_script( $handle, $object_name, $l10n ) {
        global $wp_scripts;
-       if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
-               if ( ! did_action( 'init' ) )
-                       _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
-                               '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
-
+       if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
+               _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
                return false;
        }
 
@@ -132,20 +164,13 @@ function wp_localize_script( $handle, $object_name, $l10n ) {
  * such as jQuery core, from being unregistered.
  *
  * @see WP_Dependencies::remove()
- * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
  *
  * @since 2.6.0
  *
  * @param string $handle Name of the script to be removed.
  */
 function wp_deregister_script( $handle ) {
-       global $wp_scripts;
-       if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
-               if ( ! did_action( 'init' ) )
-                       _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
-                               '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
-               $wp_scripts = new WP_Scripts();
-       }
+       _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
 
        /**
         * Do not allow accidental or negligent de-registering of critical scripts in the admin.
@@ -172,7 +197,7 @@ function wp_deregister_script( $handle ) {
                }
        }
 
-       $wp_scripts->remove( $handle );
+       wp_scripts()->remove( $handle );
 }
 
 /**
@@ -181,10 +206,9 @@ function wp_deregister_script( $handle ) {
  * Registers the script if $src provided (does NOT overwrite), and enqueues it.
  *
  * @see WP_Dependencies::add(), WP_Dependencies::add_data(), WP_Dependencies::enqueue()
- * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
  *
  * @since 2.6.0
-
+ *
  * @param string      $handle    Name of the script.
  * @param string|bool $src       Path to the script from the root directory of WordPress. Example: '/js/myscript.js'.
  * @param array       $deps      An array of registered handles this script depends on. Default empty array.
@@ -195,20 +219,23 @@ function wp_deregister_script( $handle ) {
  *                               Default 'false'. Accepts 'false' or 'true'.
  */
 function wp_enqueue_script( $handle, $src = false, $deps = array(), $ver = false, $in_footer = false ) {
-       global $wp_scripts;
-       if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
-               if ( ! did_action( 'init' ) )
-                       _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
-                               '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
-               $wp_scripts = new WP_Scripts();
-       }
+       $wp_scripts = wp_scripts();
+
+       _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
+
+
+       if ( $src || $in_footer ) {
+               $_handle = explode( '?', $handle );
 
-       if ( $src ) {
-               $_handle = explode('?', $handle);
-               $wp_scripts->add( $_handle[0], $src, $deps, $ver );
-               if ( $in_footer )
+               if ( $src ) {
+                       $wp_scripts->add( $_handle[0], $src, $deps, $ver );
+               }
+
+               if ( $in_footer ) {
                        $wp_scripts->add_data( $_handle[0], 'group', 1 );
+               }
        }
+
        $wp_scripts->enqueue( $handle );
 }
 
@@ -216,29 +243,20 @@ function wp_enqueue_script( $handle, $src = false, $deps = array(), $ver = false
  * Remove a previously enqueued script.
  *
  * @see WP_Dependencies::dequeue()
- * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
  *
  * @since 3.1.0
  *
  * @param string $handle Name of the script to be removed.
  */
 function wp_dequeue_script( $handle ) {
-       global $wp_scripts;
-       if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
-               if ( ! did_action( 'init' ) )
-                       _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
-                               '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
-               $wp_scripts = new WP_Scripts();
-       }
+       _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
 
-       $wp_scripts->dequeue( $handle );
+       wp_scripts()->dequeue( $handle );
 }
 
 /**
  * Check whether a script has been added to the queue.
  *
- * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
- *
  * @since 2.8.0
  * @since 3.5.0 'enqueued' added as an alias of the 'queue' list.
  *
@@ -248,13 +266,28 @@ function wp_dequeue_script( $handle ) {
  * @return bool Whether the script script is queued.
  */
 function wp_script_is( $handle, $list = 'enqueued' ) {
-       global $wp_scripts;
-       if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) {
-               if ( ! did_action( 'init' ) )
-                       _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
-                               '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
-               $wp_scripts = new WP_Scripts();
-       }
+       _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
+
+       return (bool) wp_scripts()->query( $handle, $list );
+}
 
-       return (bool) $wp_scripts->query( $handle, $list );
+/**
+ * Add metadata to a script.
+ *
+ * Works only if the script has already been added.
+ *
+ * Possible values for $key and $value:
+ * 'conditional' string Comments for IE 6, lte IE 7, etc.
+ *
+ * @since 4.2.0
+ *
+ * @see WP_Dependency::add_data()
+ *
+ * @param string $handle Name of the script.
+ * @param string $key    Name of data point for which we're storing a value.
+ * @param mixed  $value  String containing the data to be added.
+ * @return bool True on success, false on failure.
+ */
+function wp_script_add_data( $handle, $key, $value ){
+       return wp_scripts()->add_data( $handle, $key, $value );
 }