5 * @since 2.6.0 |
5 * @since 2.6.0 |
6 * |
6 * |
7 * @package WordPress |
7 * @package WordPress |
8 * @subpackage BackPress |
8 * @subpackage BackPress |
9 */ |
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 } |
|
25 return $wp_scripts; |
|
26 } |
|
27 |
|
28 /** |
|
29 * Helper function to output a _doing_it_wrong message when applicable. |
|
30 * |
|
31 * @ignore |
|
32 * @since 4.2.0 |
|
33 * |
|
34 * @param string $function Function name. |
|
35 */ |
|
36 function _wp_scripts_maybe_doing_it_wrong( $function ) { |
|
37 if ( did_action( 'init' ) ) { |
|
38 return; |
|
39 } |
|
40 |
|
41 _doing_it_wrong( $function, sprintf( |
|
42 __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
|
43 '<code>wp_enqueue_scripts</code>', |
|
44 '<code>admin_enqueue_scripts</code>', |
|
45 '<code>login_enqueue_scripts</code>' |
|
46 ), '3.3' ); |
|
47 } |
10 |
48 |
11 /** |
49 /** |
12 * Print scripts in document head that are in the $handles queue. |
50 * Print scripts in document head that are in the $handles queue. |
13 * |
51 * |
14 * Called by admin-header.php and wp_head hook. Since it is called by wp_head on every page load, |
52 * Called by admin-header.php and wp_head hook. Since it is called by wp_head on every page load, |
19 * @see WP_Scripts::do_items() |
57 * @see WP_Scripts::do_items() |
20 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
58 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
21 * |
59 * |
22 * @since 2.6.0 |
60 * @since 2.6.0 |
23 * |
61 * |
24 * @param array|bool $handles Optional. Scripts to be printed. Default 'false'. |
62 * @param string|bool|array $handles Optional. Scripts to be printed. Default 'false'. |
25 * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array. |
63 * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array. |
26 */ |
64 */ |
27 function wp_print_scripts( $handles = false ) { |
65 function wp_print_scripts( $handles = false ) { |
|
66 /** |
|
67 * Fires before scripts in the $handles queue are printed. |
|
68 * |
|
69 * @since 2.1.0 |
|
70 */ |
28 do_action( 'wp_print_scripts' ); |
71 do_action( 'wp_print_scripts' ); |
29 if ( '' === $handles ) // for wp_head |
72 if ( '' === $handles ) { // for wp_head |
30 $handles = false; |
73 $handles = false; |
31 |
74 } |
32 global $wp_scripts; |
75 |
33 if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) { |
76 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
34 if ( ! did_action( 'init' ) ) |
77 |
35 _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
78 global $wp_scripts; |
36 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' ); |
79 if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { |
37 |
80 if ( ! $handles ) { |
38 if ( !$handles ) |
|
39 return array(); // No need to instantiate if nothing is there. |
81 return array(); // No need to instantiate if nothing is there. |
40 else |
82 } |
41 $wp_scripts = new WP_Scripts(); |
83 } |
42 } |
84 |
43 |
85 return wp_scripts()->do_items( $handles ); |
44 return $wp_scripts->do_items( $handles ); |
|
45 } |
86 } |
46 |
87 |
47 /** |
88 /** |
48 * Register a new script. |
89 * Register a new script. |
49 * |
90 * |
64 * If set to null, no version is added. Default 'false'. Accepts 'false', 'null', or 'string'. |
105 * If set to null, no version is added. Default 'false'. Accepts 'false', 'null', or 'string'. |
65 * @param bool $in_footer Optional. Whether to enqueue the script before </head> or before </body>. |
106 * @param bool $in_footer Optional. Whether to enqueue the script before </head> or before </body>. |
66 * Default 'false'. Accepts 'false' or 'true'. |
107 * Default 'false'. Accepts 'false' or 'true'. |
67 */ |
108 */ |
68 function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false ) { |
109 function wp_register_script( $handle, $src, $deps = array(), $ver = false, $in_footer = false ) { |
69 global $wp_scripts; |
110 $wp_scripts = wp_scripts(); |
70 if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) { |
111 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
71 if ( ! did_action( 'init' ) ) |
|
72 _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
|
73 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' ); |
|
74 $wp_scripts = new WP_Scripts(); |
|
75 } |
|
76 |
112 |
77 $wp_scripts->add( $handle, $src, $deps, $ver ); |
113 $wp_scripts->add( $handle, $src, $deps, $ver ); |
78 if ( $in_footer ) |
114 if ( $in_footer ) { |
79 $wp_scripts->add_data( $handle, 'group', 1 ); |
115 $wp_scripts->add_data( $handle, 'group', 1 ); |
|
116 } |
80 } |
117 } |
81 |
118 |
82 /** |
119 /** |
83 * Localize a script. |
120 * Localize a script. |
84 * |
121 * |
85 * Works only if the script has already been added. |
122 * Works only if the script has already been added. |
86 * |
123 * |
87 * Accepts an associative array $l10n and creates a JavaScript object: |
124 * Accepts an associative array $l10n and creates a JavaScript object: |
88 * <code> |
125 * |
89 * "$object_name" = { |
126 * "$object_name" = { |
90 * key: value, |
127 * key: value, |
91 * key: value, |
128 * key: value, |
92 * ... |
129 * ... |
93 * } |
130 * } |
94 * </code> |
131 * |
95 * |
132 * |
96 * @see WP_Dependencies::localize() |
133 * @see WP_Dependencies::localize() |
97 * @link http://core.trac.wordpress.org/ticket/11520 |
134 * @link https://core.trac.wordpress.org/ticket/11520 |
98 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
135 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
99 * |
136 * |
100 * @since 2.6.0 |
137 * @since 2.6.0 |
|
138 * |
|
139 * @todo Documentation cleanup |
101 * |
140 * |
102 * @param string $handle Script handle the data will be attached to. |
141 * @param string $handle Script handle the data will be attached to. |
103 * @param string $object_name Name for the JavaScript object. Passed directly, so it should be qualified JS variable. |
142 * @param string $object_name Name for the JavaScript object. Passed directly, so it should be qualified JS variable. |
104 * Example: '/[a-zA-Z0-9_]+/'. |
143 * Example: '/[a-zA-Z0-9_]+/'. |
105 * @param array $l10n The data itself. The data can be either a single or multi-dimensional array. |
144 * @param array $l10n The data itself. The data can be either a single or multi-dimensional array. |
106 * @return bool True if the script was successfully localized, false otherwise. |
145 * @return bool True if the script was successfully localized, false otherwise. |
107 */ |
146 */ |
108 function wp_localize_script( $handle, $object_name, $l10n ) { |
147 function wp_localize_script( $handle, $object_name, $l10n ) { |
109 global $wp_scripts; |
148 global $wp_scripts; |
110 if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) { |
149 if ( ! ( $wp_scripts instanceof WP_Scripts ) ) { |
111 if ( ! did_action( 'init' ) ) |
150 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
112 _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
|
113 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' ); |
|
114 |
|
115 return false; |
151 return false; |
116 } |
152 } |
117 |
153 |
118 return $wp_scripts->localize( $handle, $object_name, $l10n ); |
154 return wp_scripts()->localize( $handle, $object_name, $l10n ); |
119 } |
155 } |
120 |
156 |
121 /** |
157 /** |
122 * Remove a registered script. |
158 * Remove a registered script. |
123 * |
159 * |
130 * @since 2.6.0 |
166 * @since 2.6.0 |
131 * |
167 * |
132 * @param string $handle Name of the script to be removed. |
168 * @param string $handle Name of the script to be removed. |
133 */ |
169 */ |
134 function wp_deregister_script( $handle ) { |
170 function wp_deregister_script( $handle ) { |
135 global $wp_scripts; |
171 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
136 if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) { |
|
137 if ( ! did_action( 'init' ) ) |
|
138 _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
|
139 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' ); |
|
140 $wp_scripts = new WP_Scripts(); |
|
141 } |
|
142 |
172 |
143 /** |
173 /** |
144 * Do not allow accidental or negligent de-registering of critical scripts in the admin. |
174 * Do not allow accidental or negligent de-registering of critical scripts in the admin. |
145 * Show minimal remorse if the correct hook is used. |
175 * Show minimal remorse if the correct hook is used. |
146 */ |
176 */ |
175 * |
205 * |
176 * @see WP_Dependencies::add(), WP_Dependencies::add_data(), WP_Dependencies::enqueue() |
206 * @see WP_Dependencies::add(), WP_Dependencies::add_data(), WP_Dependencies::enqueue() |
177 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
207 * @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts. |
178 * |
208 * |
179 * @since 2.6.0 |
209 * @since 2.6.0 |
180 |
210 * |
181 * @param string $handle Name of the script. |
211 * @param string $handle Name of the script. |
182 * @param string|bool $src Path to the script from the root directory of WordPress. Example: '/js/myscript.js'. |
212 * @param string|bool $src Path to the script from the root directory of WordPress. Example: '/js/myscript.js'. |
183 * @param array $deps An array of registered handles this script depends on. Default empty array. |
213 * @param array $deps An array of registered handles this script depends on. Default empty array. |
184 * @param string|bool $ver Optional. String specifying the script version number, if it has one. This parameter |
214 * @param string|bool $ver Optional. String specifying the script version number, if it has one. This parameter |
185 * is used to ensure that the correct version is sent to the client regardless of caching, |
215 * is used to ensure that the correct version is sent to the client regardless of caching, |
186 * and so should be included if a version number is available and makes sense for the script. |
216 * and so should be included if a version number is available and makes sense for the script. |
187 * @param bool $in_footer Optional. Whether to enqueue the script before </head> or before </body>. |
217 * @param bool $in_footer Optional. Whether to enqueue the script before </head> or before </body>. |
188 * Default 'false'. Accepts 'false' or 'true'. |
218 * Default 'false'. Accepts 'false' or 'true'. |
189 */ |
219 */ |
190 function wp_enqueue_script( $handle, $src = false, $deps = array(), $ver = false, $in_footer = false ) { |
220 function wp_enqueue_script( $handle, $src = false, $deps = array(), $ver = false, $in_footer = false ) { |
191 global $wp_scripts; |
221 $wp_scripts = wp_scripts(); |
192 if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) { |
222 |
193 if ( ! did_action( 'init' ) ) |
223 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
194 _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
224 |
195 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' ); |
225 |
196 $wp_scripts = new WP_Scripts(); |
226 if ( $src || $in_footer ) { |
197 } |
227 $_handle = explode( '?', $handle ); |
198 |
228 |
199 if ( $src ) { |
229 if ( $src ) { |
200 $_handle = explode('?', $handle); |
230 $wp_scripts->add( $_handle[0], $src, $deps, $ver ); |
201 $wp_scripts->add( $_handle[0], $src, $deps, $ver ); |
231 } |
202 if ( $in_footer ) |
232 |
|
233 if ( $in_footer ) { |
203 $wp_scripts->add_data( $_handle[0], 'group', 1 ); |
234 $wp_scripts->add_data( $_handle[0], 'group', 1 ); |
204 } |
235 } |
|
236 } |
|
237 |
205 $wp_scripts->enqueue( $handle ); |
238 $wp_scripts->enqueue( $handle ); |
206 } |
239 } |
207 |
240 |
208 /** |
241 /** |
209 * Remove a previously enqueued script. |
242 * Remove a previously enqueued script. |
214 * @since 3.1.0 |
247 * @since 3.1.0 |
215 * |
248 * |
216 * @param string $handle Name of the script to be removed. |
249 * @param string $handle Name of the script to be removed. |
217 */ |
250 */ |
218 function wp_dequeue_script( $handle ) { |
251 function wp_dequeue_script( $handle ) { |
219 global $wp_scripts; |
252 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
220 if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) { |
253 |
221 if ( ! did_action( 'init' ) ) |
254 wp_scripts()->dequeue( $handle ); |
222 _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
|
223 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' ); |
|
224 $wp_scripts = new WP_Scripts(); |
|
225 } |
|
226 |
|
227 $wp_scripts->dequeue( $handle ); |
|
228 } |
255 } |
229 |
256 |
230 /** |
257 /** |
231 * Check whether a script has been added to the queue. |
258 * Check whether a script has been added to the queue. |
232 * |
259 * |
239 * @param string $list Optional. Status of the script to check. Default 'enqueued'. |
266 * @param string $list Optional. Status of the script to check. Default 'enqueued'. |
240 * Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'. |
267 * Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'. |
241 * @return bool Whether the script script is queued. |
268 * @return bool Whether the script script is queued. |
242 */ |
269 */ |
243 function wp_script_is( $handle, $list = 'enqueued' ) { |
270 function wp_script_is( $handle, $list = 'enqueued' ) { |
244 global $wp_scripts; |
271 _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); |
245 if ( ! is_a( $wp_scripts, 'WP_Scripts' ) ) { |
272 |
246 if ( ! did_action( 'init' ) ) |
273 return (bool) wp_scripts()->query( $handle, $list ); |
247 _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ), |
274 } |
248 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' ); |
275 |
249 $wp_scripts = new WP_Scripts(); |
276 /** |
250 } |
277 * Add metadata to a script. |
251 |
278 * |
252 return (bool) $wp_scripts->query( $handle, $list ); |
279 * Works only if the script has already been added. |
253 } |
280 * |
|
281 * Possible values for $key and $value: |
|
282 * 'conditional' string Comments for IE 6, lte IE 7, etc. |
|
283 * |
|
284 * @since 4.2.0 |
|
285 * |
|
286 * @see WP_Dependency::add_data() |
|
287 * |
|
288 * @param string $handle Name of the script. |
|
289 * @param string $key Name of data point for which we're storing a value. |
|
290 * @param mixed $value String containing the data to be added. |
|
291 * @return bool True on success, false on failure. |
|
292 */ |
|
293 function wp_script_add_data( $handle, $key, $value ){ |
|
294 global $wp_scripts; |
|
295 return $wp_scripts->add_data( $handle, $key, $value ); |
|
296 } |