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 | * Initializes $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 | |
---|
23 | if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { |
---|
24 | $wp_scripts = new WP_Scripts(); |
---|
25 | } |
---|
26 | |
---|
27 | return $wp_scripts; |
---|
28 | } |
---|
29 | |
---|
30 | /** |
---|
31 | * Helper function to output a _doing_it_wrong message when applicable. |
---|
32 | * |
---|
33 | * @ignore |
---|
34 | * @since 4.2.0 |
---|
35 | * @since 5.5.0 Added the `$handle` parameter. |
---|
36 | * |
---|
37 | * @param string $function_name Function name. |
---|
38 | * @param string $handle Optional. Name of the script or stylesheet that was |
---|
39 | * registered or enqueued too early. Default empty. |
---|
40 | */ |
---|
41 | function _wp_scripts_maybe_doing_it_wrong( $function_name, $handle = '' ) { |
---|
42 | if ( did_action( 'init' ) || did_action( 'wp_enqueue_scripts' ) |
---|
43 | || did_action( 'admin_enqueue_scripts' ) || did_action( 'login_enqueue_scripts' ) |
---|
44 | ) { |
---|
45 | return; |
---|
46 | } |
---|
47 | |
---|
48 | $message = sprintf( |
---|
49 | /* translators: 1: wp_enqueue_scripts, 2: admin_enqueue_scripts, 3: login_enqueue_scripts */ |
---|
50 | __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
---|
51 | '<code>wp_enqueue_scripts</code>', |
---|
52 | '<code>admin_enqueue_scripts</code>', |
---|
53 | '<code>login_enqueue_scripts</code>' |
---|
54 | ); |
---|
55 | |
---|
56 | if ( $handle ) { |
---|
57 | $message .= ' ' . sprintf( |
---|
58 | /* translators: %s: Name of the script or stylesheet. */ |
---|
59 | __( 'This notice was triggered by the %s handle.' ), |
---|
60 | '<code>' . $handle . '</code>' |
---|
61 | ); |
---|
62 | } |
---|
63 | |
---|
64 | _doing_it_wrong( |
---|
65 | $function_name, |
---|
66 | $message, |
---|
67 | '3.3.0' |
---|
68 | ); |
---|
69 | } |
---|
70 | |
---|
71 | /** |
---|
72 | * Prints scripts in document head that are in the $handles queue. |
---|
73 | * |
---|
74 | * Called by admin-header.php and {@see 'wp_head'} hook. Since it is called by wp_head on every page load, |
---|
75 | * the function does not instantiate the WP_Scripts object unless script names are explicitly passed. |
---|
76 | * Makes use of already-instantiated `$wp_scripts` global if present. Use provided {@see 'wp_print_scripts'} |
---|
77 | * hook to register/enqueue new scripts. |
---|
78 | * |
---|
79 | * @see WP_Scripts::do_item() |
---|
80 | * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
---|
81 | * |
---|
82 | * @since 2.1.0 |
---|
83 | * |
---|
84 | * @param string|string[]|false $handles Optional. Scripts to be printed. Default 'false'. |
---|
85 | * @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array. |
---|
86 | */ |
---|
87 | function wp_print_scripts( $handles = false ) { |
---|
88 | global $wp_scripts; |
---|
89 | |
---|
90 | /** |
---|
91 | * Fires before scripts in the $handles queue are printed. |
---|
92 | * |
---|
93 | * @since 2.1.0 |
---|
94 | */ |
---|
95 | do_action( 'wp_print_scripts' ); |
---|
96 | |
---|
97 | if ( '' === $handles ) { // For 'wp_head'. |
---|
98 | $handles = false; |
---|
99 | } |
---|
100 | |
---|
101 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
---|
102 | |
---|
103 | if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { |
---|
104 | if ( ! $handles ) { |
---|
105 | return array(); // No need to instantiate if nothing is there. |
---|
106 | } |
---|
107 | } |
---|
108 | |
---|
109 | return wp_scripts()->do_items( $handles ); |
---|
110 | } |
---|
111 | |
---|
112 | /** |
---|
113 | * Adds extra code to a registered script. |
---|
114 | * |
---|
115 | * Code will only be added if the script is already in the queue. |
---|
116 | * Accepts a string `$data` containing the code. If two or more code blocks |
---|
117 | * are added to the same script `$handle`, they will be printed in the order |
---|
118 | * they were added, i.e. the latter added code can redeclare the previous. |
---|
119 | * |
---|
120 | * @since 4.5.0 |
---|
121 | * |
---|
122 | * @see WP_Scripts::add_inline_script() |
---|
123 | * |
---|
124 | * @param string $handle Name of the script to add the inline script to. |
---|
125 | * @param string $data String containing the JavaScript to be added. |
---|
126 | * @param string $position Optional. Whether to add the inline script before the handle |
---|
127 | * or after. Default 'after'. |
---|
128 | * @return bool True on success, false on failure. |
---|
129 | */ |
---|
130 | function wp_add_inline_script( $handle, $data, $position = 'after' ) { |
---|
131 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
132 | |
---|
133 | if ( false !== stripos( $data, '</script>' ) ) { |
---|
134 | _doing_it_wrong( |
---|
135 | __FUNCTION__, |
---|
136 | sprintf( |
---|
137 | /* translators: 1: <script>, 2: wp_add_inline_script() */ |
---|
138 | __( 'Do not pass %1$s tags to %2$s.' ), |
---|
139 | '<code><script></code>', |
---|
140 | '<code>wp_add_inline_script()</code>' |
---|
141 | ), |
---|
142 | '4.5.0' |
---|
143 | ); |
---|
144 | $data = trim( preg_replace( '#<script[^>]*>(.*)</script>#is', '$1', $data ) ); |
---|
145 | } |
---|
146 | |
---|
147 | return wp_scripts()->add_inline_script( $handle, $data, $position ); |
---|
148 | } |
---|
149 | |
---|
150 | /** |
---|
151 | * Registers a new script. |
---|
152 | * |
---|
153 | * Registers a script to be enqueued later using the wp_enqueue_script() function. |
---|
154 | * |
---|
155 | * @see WP_Dependencies::add() |
---|
156 | * @see WP_Dependencies::add_data() |
---|
157 | * |
---|
158 | * @since 2.1.0 |
---|
159 | * @since 4.3.0 A return value was added. |
---|
160 | * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array. |
---|
161 | * |
---|
162 | * @param string $handle Name of the script. Should be unique. |
---|
163 | * @param string|false $src Full URL of the script, or path of the script relative to the WordPress root directory. |
---|
164 | * If source is set to false, script is an alias of other scripts it depends on. |
---|
165 | * @param string[] $deps Optional. An array of registered script handles this script depends on. Default empty array. |
---|
166 | * @param string|bool|null $ver Optional. String specifying script version number, if it has one, which is added to the URL |
---|
167 | * as a query string for cache busting purposes. If version is set to false, a version |
---|
168 | * number is automatically added equal to current installed WordPress version. |
---|
169 | * If set to null, no version is added. |
---|
170 | * @param array|bool $args { |
---|
171 | * Optional. An array of additional script loading strategies. Default empty array. |
---|
172 | * Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false. |
---|
173 | * |
---|
174 | * @type string $strategy Optional. If provided, may be either 'defer' or 'async'. |
---|
175 | * @type bool $in_footer Optional. Whether to print the script in the footer. Default 'false'. |
---|
176 | * } |
---|
177 | * @return bool Whether the script has been registered. True on success, false on failure. |
---|
178 | */ |
---|
179 | function wp_register_script( $handle, $src, $deps = array(), $ver = false, $args = array() ) { |
---|
180 | if ( ! is_array( $args ) ) { |
---|
181 | $args = array( |
---|
182 | 'in_footer' => (bool) $args, |
---|
183 | ); |
---|
184 | } |
---|
185 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
186 | |
---|
187 | $wp_scripts = wp_scripts(); |
---|
188 | |
---|
189 | $registered = $wp_scripts->add( $handle, $src, $deps, $ver ); |
---|
190 | if ( ! empty( $args['in_footer'] ) ) { |
---|
191 | $wp_scripts->add_data( $handle, 'group', 1 ); |
---|
192 | } |
---|
193 | if ( ! empty( $args['strategy'] ) ) { |
---|
194 | $wp_scripts->add_data( $handle, 'strategy', $args['strategy'] ); |
---|
195 | } |
---|
196 | return $registered; |
---|
197 | } |
---|
198 | |
---|
199 | /** |
---|
200 | * Localizes a script. |
---|
201 | * |
---|
202 | * Works only if the script has already been registered. |
---|
203 | * |
---|
204 | * Accepts an associative array `$l10n` and creates a JavaScript object: |
---|
205 | * |
---|
206 | * "$object_name": { |
---|
207 | * key: value, |
---|
208 | * key: value, |
---|
209 | * ... |
---|
210 | * } |
---|
211 | * |
---|
212 | * @see WP_Scripts::localize() |
---|
213 | * @link https://core.trac.wordpress.org/ticket/11520 |
---|
214 | * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
---|
215 | * |
---|
216 | * @since 2.2.0 |
---|
217 | * |
---|
218 | * @todo Documentation cleanup |
---|
219 | * |
---|
220 | * @param string $handle Script handle the data will be attached to. |
---|
221 | * @param string $object_name Name for the JavaScript object. Passed directly, so it should be qualified JS variable. |
---|
222 | * Example: '/[a-zA-Z0-9_]+/'. |
---|
223 | * @param array $l10n The data itself. The data can be either a single or multi-dimensional array. |
---|
224 | * @return bool True if the script was successfully localized, false otherwise. |
---|
225 | */ |
---|
226 | function wp_localize_script( $handle, $object_name, $l10n ) { |
---|
227 | global $wp_scripts; |
---|
228 | |
---|
229 | if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { |
---|
230 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
231 | return false; |
---|
232 | } |
---|
233 | |
---|
234 | return $wp_scripts->localize( $handle, $object_name, $l10n ); |
---|
235 | } |
---|
236 | |
---|
237 | /** |
---|
238 | * Sets translated strings for a script. |
---|
239 | * |
---|
240 | * Works only if the script has already been registered. |
---|
241 | * |
---|
242 | * @see WP_Scripts::set_translations() |
---|
243 | * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
---|
244 | * |
---|
245 | * @since 5.0.0 |
---|
246 | * @since 5.1.0 The `$domain` parameter was made optional. |
---|
247 | * |
---|
248 | * @param string $handle Script handle the textdomain will be attached to. |
---|
249 | * @param string $domain Optional. Text domain. Default 'default'. |
---|
250 | * @param string $path Optional. The full file path to the directory containing translation files. |
---|
251 | * @return bool True if the text domain was successfully localized, false otherwise. |
---|
252 | */ |
---|
253 | function wp_set_script_translations( $handle, $domain = 'default', $path = '' ) { |
---|
254 | global $wp_scripts; |
---|
255 | |
---|
256 | if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { |
---|
257 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
258 | return false; |
---|
259 | } |
---|
260 | |
---|
261 | return $wp_scripts->set_translations( $handle, $domain, $path ); |
---|
262 | } |
---|
263 | |
---|
264 | /** |
---|
265 | * Removes a registered script. |
---|
266 | * |
---|
267 | * Note: there are intentional safeguards in place to prevent critical admin scripts, |
---|
268 | * such as jQuery core, from being unregistered. |
---|
269 | * |
---|
270 | * @see WP_Dependencies::remove() |
---|
271 | * |
---|
272 | * @since 2.1.0 |
---|
273 | * |
---|
274 | * @global string $pagenow The filename of the current screen. |
---|
275 | * |
---|
276 | * @param string $handle Name of the script to be removed. |
---|
277 | */ |
---|
278 | function wp_deregister_script( $handle ) { |
---|
279 | global $pagenow; |
---|
280 | |
---|
281 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
282 | |
---|
283 | /** |
---|
284 | * Do not allow accidental or negligent de-registering of critical scripts in the admin. |
---|
285 | * Show minimal remorse if the correct hook is used. |
---|
286 | */ |
---|
287 | $current_filter = current_filter(); |
---|
288 | if ( ( is_admin() && 'admin_enqueue_scripts' !== $current_filter ) || |
---|
289 | ( 'wp-login.php' === $pagenow && 'login_enqueue_scripts' !== $current_filter ) |
---|
290 | ) { |
---|
291 | $not_allowed = array( |
---|
292 | 'jquery', |
---|
293 | 'jquery-core', |
---|
294 | 'jquery-migrate', |
---|
295 | 'jquery-ui-core', |
---|
296 | 'jquery-ui-accordion', |
---|
297 | 'jquery-ui-autocomplete', |
---|
298 | 'jquery-ui-button', |
---|
299 | 'jquery-ui-datepicker', |
---|
300 | 'jquery-ui-dialog', |
---|
301 | 'jquery-ui-draggable', |
---|
302 | 'jquery-ui-droppable', |
---|
303 | 'jquery-ui-menu', |
---|
304 | 'jquery-ui-mouse', |
---|
305 | 'jquery-ui-position', |
---|
306 | 'jquery-ui-progressbar', |
---|
307 | 'jquery-ui-resizable', |
---|
308 | 'jquery-ui-selectable', |
---|
309 | 'jquery-ui-slider', |
---|
310 | 'jquery-ui-sortable', |
---|
311 | 'jquery-ui-spinner', |
---|
312 | 'jquery-ui-tabs', |
---|
313 | 'jquery-ui-tooltip', |
---|
314 | 'jquery-ui-widget', |
---|
315 | 'underscore', |
---|
316 | 'backbone', |
---|
317 | ); |
---|
318 | |
---|
319 | if ( in_array( $handle, $not_allowed, true ) ) { |
---|
320 | _doing_it_wrong( |
---|
321 | __FUNCTION__, |
---|
322 | sprintf( |
---|
323 | /* translators: 1: Script name, 2: wp_enqueue_scripts */ |
---|
324 | __( 'Do not deregister the %1$s script in the administration area. To target the front-end theme, use the %2$s hook.' ), |
---|
325 | "<code>$handle</code>", |
---|
326 | '<code>wp_enqueue_scripts</code>' |
---|
327 | ), |
---|
328 | '3.6.0' |
---|
329 | ); |
---|
330 | return; |
---|
331 | } |
---|
332 | } |
---|
333 | |
---|
334 | wp_scripts()->remove( $handle ); |
---|
335 | } |
---|
336 | |
---|
337 | /** |
---|
338 | * Enqueues a script. |
---|
339 | * |
---|
340 | * Registers the script if `$src` provided (does NOT overwrite), and enqueues it. |
---|
341 | * |
---|
342 | * @see WP_Dependencies::add() |
---|
343 | * @see WP_Dependencies::add_data() |
---|
344 | * @see WP_Dependencies::enqueue() |
---|
345 | * |
---|
346 | * @since 2.1.0 |
---|
347 | * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array. |
---|
348 | * |
---|
349 | * @param string $handle Name of the script. Should be unique. |
---|
350 | * @param string $src Full URL of the script, or path of the script relative to the WordPress root directory. |
---|
351 | * Default empty. |
---|
352 | * @param string[] $deps Optional. An array of registered script handles this script depends on. Default empty array. |
---|
353 | * @param string|bool|null $ver Optional. String specifying script version number, if it has one, which is added to the URL |
---|
354 | * as a query string for cache busting purposes. If version is set to false, a version |
---|
355 | * number is automatically added equal to current installed WordPress version. |
---|
356 | * If set to null, no version is added. |
---|
357 | * @param array|bool $args { |
---|
358 | * Optional. An array of additional script loading strategies. Default empty array. |
---|
359 | * Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false. |
---|
360 | * |
---|
361 | * @type string $strategy Optional. If provided, may be either 'defer' or 'async'. |
---|
362 | * @type bool $in_footer Optional. Whether to print the script in the footer. Default 'false'. |
---|
363 | * } |
---|
364 | */ |
---|
365 | function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $args = array() ) { |
---|
366 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
367 | |
---|
368 | $wp_scripts = wp_scripts(); |
---|
369 | |
---|
370 | if ( $src || ! empty( $args ) ) { |
---|
371 | $_handle = explode( '?', $handle ); |
---|
372 | if ( ! is_array( $args ) ) { |
---|
373 | $args = array( |
---|
374 | 'in_footer' => (bool) $args, |
---|
375 | ); |
---|
376 | } |
---|
377 | |
---|
378 | if ( $src ) { |
---|
379 | $wp_scripts->add( $_handle[0], $src, $deps, $ver ); |
---|
380 | } |
---|
381 | if ( ! empty( $args['in_footer'] ) ) { |
---|
382 | $wp_scripts->add_data( $_handle[0], 'group', 1 ); |
---|
383 | } |
---|
384 | if ( ! empty( $args['strategy'] ) ) { |
---|
385 | $wp_scripts->add_data( $_handle[0], 'strategy', $args['strategy'] ); |
---|
386 | } |
---|
387 | } |
---|
388 | |
---|
389 | $wp_scripts->enqueue( $handle ); |
---|
390 | } |
---|
391 | |
---|
392 | /** |
---|
393 | * Removes a previously enqueued script. |
---|
394 | * |
---|
395 | * @see WP_Dependencies::dequeue() |
---|
396 | * |
---|
397 | * @since 3.1.0 |
---|
398 | * |
---|
399 | * @param string $handle Name of the script to be removed. |
---|
400 | */ |
---|
401 | function wp_dequeue_script( $handle ) { |
---|
402 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
403 | |
---|
404 | wp_scripts()->dequeue( $handle ); |
---|
405 | } |
---|
406 | |
---|
407 | /** |
---|
408 | * Determines whether a script has been added to the queue. |
---|
409 | * |
---|
410 | * For more information on this and similar theme functions, check out |
---|
411 | * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ |
---|
412 | * Conditional Tags} article in the Theme Developer Handbook. |
---|
413 | * |
---|
414 | * @since 2.8.0 |
---|
415 | * @since 3.5.0 'enqueued' added as an alias of the 'queue' list. |
---|
416 | * |
---|
417 | * @param string $handle Name of the script. |
---|
418 | * @param string $status Optional. Status of the script to check. Default 'enqueued'. |
---|
419 | * Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'. |
---|
420 | * @return bool Whether the script is queued. |
---|
421 | */ |
---|
422 | function wp_script_is( $handle, $status = 'enqueued' ) { |
---|
423 | _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); |
---|
424 | |
---|
425 | return (bool) wp_scripts()->query( $handle, $status ); |
---|
426 | } |
---|
427 | |
---|
428 | /** |
---|
429 | * Adds metadata to a script. |
---|
430 | * |
---|
431 | * Works only if the script has already been registered. |
---|
432 | * |
---|
433 | * Possible values for $key and $value: |
---|
434 | * 'conditional' string Comments for IE 6, lte IE 7, etc. |
---|
435 | * |
---|
436 | * @since 4.2.0 |
---|
437 | * |
---|
438 | * @see WP_Dependencies::add_data() |
---|
439 | * |
---|
440 | * @param string $handle Name of the script. |
---|
441 | * @param string $key Name of data point for which we're storing a value. |
---|
442 | * @param mixed $value String containing the data to be added. |
---|
443 | * @return bool True on success, false on failure. |
---|
444 | */ |
---|
445 | function wp_script_add_data( $handle, $key, $value ) { |
---|
446 | return wp_scripts()->add_data( $handle, $key, $value ); |
---|
447 | } |
---|