WordPress 3.8
[autoinstalls/wordpress.git] / wp-includes / functions.wp-styles.php
1 <?php
2 /**
3  * BackPress Styles Procedural API
4  *
5  * @since 2.6.0
6  *
7  * @package WordPress
8  * @subpackage BackPress
9  */
10
11 /**
12  * Display styles that are in the $handles queue.
13  *
14  * Passing an empty array to $handles prints the queue,
15  * passing an array with one string prints that style,
16  * and passing an array of strings prints those styles.
17  *
18  * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
19  *
20  * @since 2.6.0
21  *
22  * @param array|bool $handles Styles to be printed. Default 'false'.
23  * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
24  */
25 function wp_print_styles( $handles = false ) {
26         if ( '' === $handles ) // for wp_head
27                 $handles = false;
28         /**
29          * Fires before styles in the $handles queue are printed.
30          *
31          * @since 2.6.0
32          */
33         if ( ! $handles )
34                 do_action( 'wp_print_styles' );
35
36         global $wp_styles;
37         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
38                 if ( ! did_action( 'init' ) )
39                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
40                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
41
42                 if ( !$handles )
43                         return array(); // No need to instantiate if nothing is there.
44                 else
45                         $wp_styles = new WP_Styles();
46         }
47
48         return $wp_styles->do_items( $handles );
49 }
50
51 /**
52  * Add extra CSS styles to a registered stylesheet.
53  *
54  * Styles will only be added if the stylesheet in already in the queue.
55  * Accepts a string $data containing the CSS. If two or more CSS code blocks
56  * are added to the same stylesheet $handle, they will be printed in the order
57  * they were added, i.e. the latter added styles can redeclare the previous.
58  *
59  * @see WP_Styles::add_inline_style()
60  * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
61  *
62  * @since 3.3.0
63  *
64  * @param string $handle Name of the stylesheet to add the extra styles to. Must be lowercase.
65  * @param string $data   String containing the CSS styles to be added.
66  * @return bool True on success, false on failure.
67  */
68 function wp_add_inline_style( $handle, $data ) {
69         global $wp_styles;
70         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
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_styles = new WP_Styles();
75         }
76
77         if ( false !== stripos( $data, '</style>' ) ) {
78                 _doing_it_wrong( __FUNCTION__, 'Do not pass style tags to wp_add_inline_style().', '3.7' );
79                 $data = trim( preg_replace( '#<style[^>]*>(.*)</style>#is', '$1', $data ) );
80         }
81
82         return $wp_styles->add_inline_style( $handle, $data );
83 }
84
85 /**
86  * Register a CSS stylesheet.
87  *
88  * @see WP_Dependencies::add()
89  * @link http://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
90  * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
91  *
92  * @since 2.6.0
93  *
94  * @param string      $handle Name of the stylesheet.
95  * @param string|bool $src    Path to the stylesheet from the WordPress root directory. Example: '/css/mystyle.css'.
96  * @param array       $deps   An array of registered style handles this stylesheet depends on. Default empty array.
97  * @param string|bool $ver    String specifying the stylesheet version number. Used to ensure that the correct version
98  *                            is sent to the client regardless of caching. Default 'false'. Accepts 'false', 'null', or 'string'.
99  * @param string      $media  Optional. The media for which this stylesheet has been defined.
100  *                            Default 'all'. Accepts 'all', 'aural', 'braille', 'handheld', 'projection', 'print',
101  *                            'screen', 'tty', or 'tv'.
102  */
103 function wp_register_style( $handle, $src, $deps = array(), $ver = false, $media = 'all' ) {
104         global $wp_styles;
105         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
106                 if ( ! did_action( 'init' ) )
107                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
108                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
109                 $wp_styles = new WP_Styles();
110         }
111
112         $wp_styles->add( $handle, $src, $deps, $ver, $media );
113 }
114
115 /**
116  * Remove a registered stylesheet.
117  *
118  * @see WP_Dependencies::remove()
119  * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
120  *
121  * @since 2.1.0
122  *
123  * @param string $handle Name of the stylesheet to be removed.
124  */
125 function wp_deregister_style( $handle ) {
126         global $wp_styles;
127         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
128                 if ( ! did_action( 'init' ) )
129                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
130                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
131                 $wp_styles = new WP_Styles();
132         }
133
134         $wp_styles->remove( $handle );
135 }
136
137 /**
138  * Enqueue a CSS stylesheet.
139  *
140  * Registers the style if source provided (does NOT overwrite) and enqueues.
141  *
142  * @see WP_Dependencies::add(), WP_Dependencies::enqueue()
143  * @link http://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
144  * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
145  *
146  * @since 2.6.0
147  *
148  * @param string      $handle Name of the stylesheet.
149  * @param string|bool $src    Path to the stylesheet from the root directory of WordPress. Example: '/css/mystyle.css'.
150  * @param array       $deps   An array of registered style handles this stylesheet depends on. Default empty array.
151  * @param string|bool $ver    String specifying the stylesheet version number, if it has one. This parameter is used
152  *                            to ensure that the correct version is sent to the client regardless of caching, and so
153  *                            should be included if a version number is available and makes sense for the stylesheet.
154  * @param string      $media  Optional. The media for which this stylesheet has been defined.
155  *                            Default 'all'. Accepts 'all', 'aural', 'braille', 'handheld', 'projection', 'print',
156  *                            'screen', 'tty', or 'tv'.
157  */
158 function wp_enqueue_style( $handle, $src = false, $deps = array(), $ver = false, $media = 'all' ) {
159         global $wp_styles;
160         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
161                 if ( ! did_action( 'init' ) )
162                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
163                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
164                 $wp_styles = new WP_Styles();
165         }
166
167         if ( $src ) {
168                 $_handle = explode('?', $handle);
169                 $wp_styles->add( $_handle[0], $src, $deps, $ver, $media );
170         }
171         $wp_styles->enqueue( $handle );
172 }
173
174 /**
175  * Remove a previously enqueued CSS stylesheet.
176  *
177  * @see WP_Dependencies::dequeue()
178  * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
179  *
180  * @since 3.1.0
181  *
182  * @param string $handle Name of the stylesheet to be removed.
183  */
184 function wp_dequeue_style( $handle ) {
185         global $wp_styles;
186         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
187                 if ( ! did_action( 'init' ) )
188                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
189                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
190                 $wp_styles = new WP_Styles();
191         }
192
193         $wp_styles->dequeue( $handle );
194 }
195
196 /**
197  * Check whether a CSS stylesheet has been added to the queue.
198  *
199  * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
200  *
201  * @since 2.8.0
202  *
203  * @param string $handle Name of the stylesheet.
204  * @param string $list   Optional. Status of the stylesheet to check. Default 'enqueued'.
205  *                       Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'.
206  * @return bool Whether style is queued.
207  */
208 function wp_style_is( $handle, $list = 'enqueued' ) {
209         global $wp_styles;
210         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
211                 if ( ! did_action( 'init' ) )
212                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
213                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
214                 $wp_styles = new WP_Styles();
215         }
216
217         return (bool) $wp_styles->query( $handle, $list );
218 }
219
220 /**
221  * Add metadata to a CSS stylesheet.
222  *
223  * Works only if the stylesheet has already been added.
224  *
225  * Possible values for $key and $value:
226  * 'conditional' string      Comments for IE 6, lte IE 7 etc.
227  * 'rtl'         bool|string To declare an RTL stylesheet.
228  * 'suffix'      string      Optional suffix, used in combination with RTL.
229  * 'alt'         bool        For rel="alternate stylesheet".
230  * 'title'       string      For preferred/alternate stylesheets.
231  *
232  * @see WP_Dependency::add_data()
233  *
234  * @since 3.6.0
235  *
236  * @param string $handle Name of the stylesheet.
237  * @param string $key    Name of data point for which we're storing a value.
238  *                       Accepts 'conditional', 'rtl' and 'suffix', 'alt' and 'title'.
239  * @param mixed  $data   String containing the CSS data to be added.
240  * @return bool True on success, false on failure.
241  */
242 function wp_style_add_data( $handle, $key, $value ) {
243         global $wp_styles;
244         return $wp_styles->add_data( $handle, $key, $value );
245 }