wp-includes/functions.wp-styles.php

   1 <?php
   2 /**
   3  * BackPress styles procedural API.
   4  *
   5  * @package BackPress
   6  * @since r79
   7  */
   8
   9 /**
  10  * Display styles that are in the queue or part of $handles.
  11  *
  12  * @since r79
  13  * @uses do_action() Calls 'wp_print_styles' hook.
  14  * @global object $wp_styles The WP_Styles object for printing styles.
  15  *
  16  * @param array|bool $handles Styles to be printed. An empty array prints the queue,
  17  *  an array with one string prints that style, and an array of strings prints those styles.
  18  * @return bool True on success, false on failure.
  19  */
  20 function wp_print_styles( $handles = false ) {
  21         if ( '' === $handles ) // for wp_head
  22                 $handles = false;
  23
  24         if ( ! $handles )
  25                 do_action( 'wp_print_styles' );
  26
  27         global $wp_styles;
  28         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
  29                 if ( ! did_action( 'init' ) )
  30                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
  31                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
  32
  33                 if ( !$handles )
  34                         return array(); // No need to instantiate if nothing is there.
  35                 else
  36                         $wp_styles = new WP_Styles();
  37         }
  38
  39         return $wp_styles->do_items( $handles );
  40 }
  41
  42 /**
  43  * Adds extra CSS.
  44  *
  45  * Works only if the stylesheet has already been added.
  46  * Accepts a string $data containing the CSS. If two or more CSS code blocks are
  47  * added to the same stylesheet $handle, they will be printed in the order
  48  * they were added, i.e. the latter added styles can redeclare the previous.
  49  *
  50  * @since 3.3.0
  51  * @see WP_Scripts::add_inline_style()
  52  */
  53 function wp_add_inline_style( $handle, $data ) {
  54         global $wp_styles;
  55         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
  56                 if ( ! did_action( 'init' ) )
  57                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
  58                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
  59                 $wp_styles = new WP_Styles();
  60         }
  61
  62         return $wp_styles->add_inline_style( $handle, $data );
  63 }
  64
  65 /**
  66  * Register CSS style file.
  67  *
  68  * @since r79
  69  * @see WP_Styles::add() For additional information.
  70  * @global object $wp_styles The WP_Styles object for printing styles.
  71  * @link http://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
  72  *
  73  * @param string $handle Name of the stylesheet.
  74  * @param string|bool $src Path to the stylesheet from the root directory of WordPress. Example: '/css/mystyle.css'.
  75  * @param array $deps Array of handles of any stylesheet that this stylesheet depends on.
  76  *  (Stylesheets that must be loaded before this stylesheet.) Pass an empty array if there are no dependencies.
  77  * @param string|bool $ver String specifying the stylesheet version number. Set to null to disable.
  78  *  Used to ensure that the correct version is sent to the client regardless of caching.
  79  * @param string $media The media for which this stylesheet has been defined.
  80  */
  81 function wp_register_style( $handle, $src, $deps = array(), $ver = false, $media = 'all' ) {
  82         global $wp_styles;
  83         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
  84                 if ( ! did_action( 'init' ) )
  85                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
  86                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
  87                 $wp_styles = new WP_Styles();
  88         }
  89
  90         $wp_styles->add( $handle, $src, $deps, $ver, $media );
  91 }
  92
  93 /**
  94  * Remove a registered CSS file.
  95  *
  96  * @since r79
  97  * @see WP_Styles::remove() For additional information.
  98  * @global object $wp_styles The WP_Styles object for printing styles.
  99  *
 100  * @param string $handle Name of the stylesheet.
 101  */
 102 function wp_deregister_style( $handle ) {
 103         global $wp_styles;
 104         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
 105                 if ( ! did_action( 'init' ) )
 106                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
 107                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
 108                 $wp_styles = new WP_Styles();
 109         }
 110
 111         $wp_styles->remove( $handle );
 112 }
 113
 114 /**
 115  * Enqueue a CSS style file.
 116  *
 117  * Registers the style if src provided (does NOT overwrite) and enqueues.
 118  *
 119  * @since r79
 120  * @see WP_Styles::add(), WP_Styles::enqueue()
 121  * @global object $wp_styles The WP_Styles object for printing styles.
 122  * @link http://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
 123  *
 124  * @param string $handle Name of the stylesheet.
 125  * @param string|bool $src Path to the stylesheet from the root directory of WordPress. Example: '/css/mystyle.css'.
 126  * @param array $deps Array of handles (names) of any stylesheet that this stylesheet depends on.
 127  *  (Stylesheets that must be loaded before this stylesheet.) Pass an empty array if there are no dependencies.
 128  * @param string|bool $ver String specifying the stylesheet version number, if it has one. This parameter
 129  *  is used to ensure that the correct version is sent to the client regardless of caching, and so should be included
 130  *  if a version number is available and makes sense for the stylesheet.
 131  * @param string $media The media for which this stylesheet has been defined.
 132  */
 133 function wp_enqueue_style( $handle, $src = false, $deps = array(), $ver = false, $media = 'all' ) {
 134         global $wp_styles;
 135         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
 136                 if ( ! did_action( 'init' ) )
 137                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
 138                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
 139                 $wp_styles = new WP_Styles();
 140         }
 141
 142         if ( $src ) {
 143                 $_handle = explode('?', $handle);
 144                 $wp_styles->add( $_handle[0], $src, $deps, $ver, $media );
 145         }
 146         $wp_styles->enqueue( $handle );
 147 }
 148
 149 /**
 150  * Remove an enqueued style.
 151  *
 152  * @since WP 3.1
 153  * @see WP_Styles::dequeue() For parameter information.
 154  */
 155 function wp_dequeue_style( $handle ) {
 156         global $wp_styles;
 157         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
 158                 if ( ! did_action( 'init' ) )
 159                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
 160                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
 161                 $wp_styles = new WP_Styles();
 162         }
 163
 164         $wp_styles->dequeue( $handle );
 165 }
 166
 167 /**
 168  * Check whether style has been added to WordPress Styles.
 169  *
 170  * By default, checks if the style has been enqueued. You can also
 171  * pass 'registered' to $list, to see if the style is registered,
 172  * and you can check processing statuses with 'to_do' and 'done'.
 173  *
 174  * @since WP unknown; BP unknown
 175  * @global object $wp_styles The WP_Styles object for printing styles.
 176  *
 177  * @param string $handle Name of the stylesheet.
 178  * @param string $list Optional. Defaults to 'enqueued'. Values are
 179  *      'registered', 'enqueued' (or 'queue'), 'to_do', and 'done'.
 180  * @return bool Whether style is in the list.
 181  */
 182 function wp_style_is( $handle, $list = 'enqueued' ) {
 183         global $wp_styles;
 184         if ( ! is_a( $wp_styles, 'WP_Styles' ) ) {
 185                 if ( ! did_action( 'init' ) )
 186                         _doing_it_wrong( __FUNCTION__, sprintf( __( 'Scripts and styles should not be registered or enqueued until the %1$s, %2$s, or %3$s hooks.' ),
 187                                 '<code>wp_enqueue_scripts</code>', '<code>admin_enqueue_scripts</code>', '<code>login_enqueue_scripts</code>' ), '3.3' );
 188                 $wp_styles = new WP_Styles();
 189         }
 190
 191         return (bool) $wp_styles->query( $handle, $list );
 192 }
 193
 194 /**
 195  * Add metadata to CSS style files.
 196  *
 197  * Works only if the stylesheet has already been added.
 198  * Possible values for $key and $value:
 199  *
 200  * conditional string      comments for IE 6, lte IE 7 etc.
 201  * rtl         bool|string to declare an RTL stylesheet
 202  * suffix      string      optional suffix, used in combination with RTL
 203  * alt         bool        for rel="alternate stylesheet"
 204  * title       string      for preferred/alternate stylesheets
 205  *
 206  * @since 3.6.0
 207  * @see WP_Dependencies::add_data()
 208  *
 209  * @param string $handle Script name.
 210  * @param string $key Name of data point for which we're storing a value.
 211  *  Values are 'conditional', 'rtl', and 'suffix', and 'alt', 'title'.
 212  * @param mixed $data
 213  * @return bool True on success, false on failure.
 214  */
 215 function wp_style_add_data( $handle, $key, $value ) {
 216         global $wp_styles;
 217         return $wp_styles->add_data( $handle, $key, $value );
 218 }