/wp-includes/functions.wp-scripts.php

  1. <?php 
  2. /** 
  3. * Dependencies API: Scripts functions 
  4. * 
  5. * @since 2.6.0 
  6. * 
  7. * @package WordPress 
  8. * @subpackage Dependencies 
  9. */ 
  10.  
  11. /** 
  12. * Initialize $wp_scripts if it has not been set. 
  13. * 
  14. * @global WP_Scripts $wp_scripts 
  15. * 
  16. * @since 4.2.0 
  17. * 
  18. * @return WP_Scripts WP_Scripts instance. 
  19. */ 
  20. function wp_scripts() { 
  21. global $wp_scripts; 
  22. if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { 
  23. $wp_scripts = new WP_Scripts(); 
  24. return $wp_scripts; 
  25.  
  26. /** 
  27. * Helper function to output a _doing_it_wrong message when applicable. 
  28. * 
  29. * @ignore 
  30. * @since 4.2.0 
  31. * 
  32. * @param string $function Function name. 
  33. */ 
  34. function _wp_scripts_maybe_doing_it_wrong( $function ) { 
  35. if ( did_action( 'init' ) || did_action( 'admin_enqueue_scripts' ) || did_action( 'wp_enqueue_scripts' ) || did_action( 'login_enqueue_scripts' ) ) { 
  36. return; 
  37.  
  38. _doing_it_wrong( $function, sprintf( 
  39. /** translators: 1: wp_enqueue_scripts, 2: admin_enqueue_scripts, 3: login_enqueue_scripts */ 
  40. __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),  
  41. '<code>wp_enqueue_scripts</code>',  
  42. '<code>admin_enqueue_scripts</code>',  
  43. '<code>login_enqueue_scripts</code>' 
  44. ), '3.3.0' ); 
  45.  
  46. /** 
  47. * Prints scripts in document head that are in the $handles queue. 
  48. * 
  49. * Called by admin-header.php and {@see 'wp_head'} hook. Since it is called by wp_head on every page load,  
  50. * the function does not instantiate the WP_Scripts object unless script names are explicitly passed. 
  51. * Makes use of already-instantiated $wp_scripts global if present. Use provided {@see 'wp_print_scripts'} 
  52. * hook to register/enqueue new scripts. 
  53. * 
  54. * @see WP_Scripts::do_items() 
  55. * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. 
  56. * 
  57. * @since 2.1.0 
  58. * 
  59. * @param string|bool|array $handles Optional. Scripts to be printed. Default 'false'. 
  60. * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array. 
  61. */ 
  62. function wp_print_scripts( $handles = false ) { 
  63. /** 
  64. * Fires before scripts in the $handles queue are printed. 
  65. * 
  66. * @since 2.1.0 
  67. */ 
  68. do_action( 'wp_print_scripts' ); 
  69. if ( '' === $handles ) { // for wp_head 
  70. $handles = false; 
  71.  
  72. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  73.  
  74. global $wp_scripts; 
  75. if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { 
  76. if ( ! $handles ) { 
  77. return array(); // No need to instantiate if nothing is there. 
  78.  
  79. return wp_scripts()->do_items( $handles ); 
  80.  
  81. /** 
  82. * Adds extra code to a registered script. 
  83. * 
  84. * Code will only be added if the script in already in the queue. 
  85. * Accepts a string $data containing the Code. If two or more code blocks 
  86. * are added to the same script $handle, they will be printed in the order 
  87. * they were added, i.e. the latter added code can redeclare the previous. 
  88. * 
  89. * @since 4.5.0 
  90. * 
  91. * @see WP_Scripts::add_inline_script() 
  92. * 
  93. * @param string $handle Name of the script to add the inline script to. 
  94. * @param string $data String containing the javascript to be added. 
  95. * @param string $position Optional. Whether to add the inline script before the handle 
  96. * or after. Default 'after'. 
  97. * @return bool True on success, false on failure. 
  98. */ 
  99. function wp_add_inline_script( $handle, $data, $position = 'after' ) { 
  100. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  101.  
  102. if ( false !== stripos( $data, '</script>' ) ) { 
  103. _doing_it_wrong( __FUNCTION__, sprintf( 
  104. /** translators: 1: <script>, 2: wp_add_inline_script() */ 
  105. __( 'Do not pass %1$s tags to %2$s.' ),  
  106. '<code><script></code>',  
  107. '<code>wp_add_inline_script()</code>' 
  108. ), '4.5.0' ); 
  109. $data = trim( preg_replace( '#<script[^>]*>(.*)</script>#is', '$1', $data ) ); 
  110.  
  111. return wp_scripts()->add_inline_script( $handle, $data, $position ); 
  112.  
  113. /** 
  114. * Register a new script. 
  115. * 
  116. * Registers a script to be enqueued later using the wp_enqueue_script() function. 
  117. * 
  118. * @see WP_Dependencies::add() 
  119. * @see WP_Dependencies::add_data() 
  120. * 
  121. * @since 2.1.0 
  122. * @since 4.3.0 A return value was added. 
  123. * 
  124. * @param string $handle Name of the script. Should be unique. 
  125. * @param string $src Full URL of the script, or path of the script relative to the WordPress root directory. 
  126. * @param array $deps Optional. An array of registered script handles this script depends on. Default empty array. 
  127. * @param string|bool|null $ver Optional. String specifying script version number, if it has one, which is added to the URL 
  128. * as a query string for cache busting purposes. If version is set to false, a version 
  129. * number is automatically added equal to current installed WordPress version. 
  130. * If set to null, no version is added. 
  131. * @param bool $in_footer Optional. Whether to enqueue the script before </body> instead of in the <head>. 
  132. * Default 'false'. 
  133. * @return bool Whether the script has been registered. True on success, false on failure. 
  134. */ 
  135. function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false ) { 
  136. $wp_scripts = wp_scripts(); 
  137. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  138.  
  139. $registered = $wp_scripts->add( $handle, $src, $deps, $ver ); 
  140. if ( $in_footer ) { 
  141. $wp_scripts->add_data( $handle, 'group', 1 ); 
  142.  
  143. return $registered; 
  144.  
  145. /** 
  146. * Localize a script. 
  147. * 
  148. * Works only if the script has already been added. 
  149. * 
  150. * Accepts an associative array $l10n and creates a JavaScript object: 
  151. * 
  152. * "$object_name" = { 
  153. * key: value,  
  154. * key: value,  
  155. * ... 
  156. * } 
  157. * 
  158. * 
  159. * @see WP_Dependencies::localize() 
  160. * @link https://core.trac.wordpress.org/ticket/11520 
  161. * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. 
  162. * 
  163. * @since 2.2.0 
  164. * 
  165. * @todo Documentation cleanup 
  166. * 
  167. * @param string $handle Script handle the data will be attached to. 
  168. * @param string $object_name Name for the JavaScript object. Passed directly, so it should be qualified JS variable. 
  169. * Example: '/[a-zA-Z0-9_]+/'. 
  170. * @param array $l10n The data itself. The data can be either a single or multi-dimensional array. 
  171. * @return bool True if the script was successfully localized, false otherwise. 
  172. */ 
  173. function wp_localize_script( $handle, $object_name, $l10n ) { 
  174. global $wp_scripts; 
  175. if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { 
  176. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  177. return false; 
  178.  
  179. return $wp_scripts->localize( $handle, $object_name, $l10n ); 
  180.  
  181. /** 
  182. * Remove a registered script. 
  183. * 
  184. * Note: there are intentional safeguards in place to prevent critical admin scripts,  
  185. * such as jQuery core, from being unregistered. 
  186. * 
  187. * @see WP_Dependencies::remove() 
  188. * 
  189. * @since 2.1.0 
  190. * 
  191. * @param string $handle Name of the script to be removed. 
  192. */ 
  193. function wp_deregister_script( $handle ) { 
  194. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  195.  
  196. /** 
  197. * Do not allow accidental or negligent de-registering of critical scripts in the admin. 
  198. * Show minimal remorse if the correct hook is used. 
  199. */ 
  200. $current_filter = current_filter(); 
  201. if ( ( is_admin() && 'admin_enqueue_scripts' !== $current_filter ) || 
  202. ( 'wp-login.php' === $GLOBALS['pagenow'] && 'login_enqueue_scripts' !== $current_filter ) 
  203. ) { 
  204. $no = array( 
  205. 'jquery', 'jquery-core', 'jquery-migrate', 'jquery-ui-core', 'jquery-ui-accordion',  
  206. 'jquery-ui-autocomplete', 'jquery-ui-button', 'jquery-ui-datepicker', 'jquery-ui-dialog',  
  207. 'jquery-ui-draggable', 'jquery-ui-droppable', 'jquery-ui-menu', 'jquery-ui-mouse',  
  208. 'jquery-ui-position', 'jquery-ui-progressbar', 'jquery-ui-resizable', 'jquery-ui-selectable',  
  209. 'jquery-ui-slider', 'jquery-ui-sortable', 'jquery-ui-spinner', 'jquery-ui-tabs',  
  210. 'jquery-ui-tooltip', 'jquery-ui-widget', 'underscore', 'backbone',  
  211. ); 
  212.  
  213. if ( in_array( $handle, $no ) ) { 
  214. $message = sprintf( 
  215. /** translators: 1: script name, 2: wp_enqueue_scripts */ 
  216. __( 'Do not deregister the %1$s script in the administration area. To target the front-end theme, use the %2$s hook.' ),  
  217. "<code>$handle</code>",  
  218. '<code>wp_enqueue_scripts</code>' 
  219. ); 
  220. _doing_it_wrong( __FUNCTION__, $message, '3.6.0' ); 
  221. return; 
  222.  
  223. wp_scripts()->remove( $handle ); 
  224.  
  225. /** 
  226. * Enqueue a script. 
  227. * 
  228. * Registers the script if $src provided (does NOT overwrite), and enqueues it. 
  229. * 
  230. * @see WP_Dependencies::add() 
  231. * @see WP_Dependencies::add_data() 
  232. * @see WP_Dependencies::enqueue() 
  233. * 
  234. * @since 2.1.0 
  235. * 
  236. * @param string $handle Name of the script. Should be unique. 
  237. * @param string $src Full URL of the script, or path of the script relative to the WordPress root directory. 
  238. * Default empty. 
  239. * @param array $deps Optional. An array of registered script handles this script depends on. Default empty array. 
  240. * @param string|bool|null $ver Optional. String specifying script version number, if it has one, which is added to the URL 
  241. * as a query string for cache busting purposes. If version is set to false, a version 
  242. * number is automatically added equal to current installed WordPress version. 
  243. * If set to null, no version is added. 
  244. * @param bool $in_footer Optional. Whether to enqueue the script before </body> instead of in the <head>. 
  245. * Default 'false'. 
  246. */ 
  247. function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $in_footer = false ) { 
  248. $wp_scripts = wp_scripts(); 
  249.  
  250. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  251.  
  252.  
  253. if ( $src || $in_footer ) { 
  254. $_handle = explode( '?', $handle ); 
  255.  
  256. if ( $src ) { 
  257. $wp_scripts->add( $_handle[0], $src, $deps, $ver ); 
  258.  
  259. if ( $in_footer ) { 
  260. $wp_scripts->add_data( $_handle[0], 'group', 1 ); 
  261.  
  262. $wp_scripts->enqueue( $handle ); 
  263.  
  264. /** 
  265. * Remove a previously enqueued script. 
  266. * 
  267. * @see WP_Dependencies::dequeue() 
  268. * 
  269. * @since 3.1.0 
  270. * 
  271. * @param string $handle Name of the script to be removed. 
  272. */ 
  273. function wp_dequeue_script( $handle ) { 
  274. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  275.  
  276. wp_scripts()->dequeue( $handle ); 
  277.  
  278. /** 
  279. * Check whether a script has been added to the queue. 
  280. * 
  281. * @since 2.8.0 
  282. * @since 3.5.0 'enqueued' added as an alias of the 'queue' list. 
  283. * 
  284. * @param string $handle Name of the script. 
  285. * @param string $list Optional. Status of the script to check. Default 'enqueued'. 
  286. * Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'. 
  287. * @return bool Whether the script is queued. 
  288. */ 
  289. function wp_script_is( $handle, $list = 'enqueued' ) { 
  290. _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); 
  291.  
  292. return (bool) wp_scripts()->query( $handle, $list ); 
  293.  
  294. /** 
  295. * Add metadata to a script. 
  296. * 
  297. * Works only if the script has already been added. 
  298. * 
  299. * Possible values for $key and $value: 
  300. * 'conditional' string Comments for IE 6, lte IE 7, etc. 
  301. * 
  302. * @since 4.2.0 
  303. * 
  304. * @see WP_Dependency::add_data() 
  305. * 
  306. * @param string $handle Name of the script. 
  307. * @param string $key Name of data point for which we're storing a value. 
  308. * @param mixed $value String containing the data to be added. 
  309. * @return bool True on success, false on failure. 
  310. */ 
  311. function wp_script_add_data( $handle, $key, $value ) { 
  312. return wp_scripts()->add_data( $handle, $key, $value ); 
.