[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Dependencies API: Styles functions
   4   *
   5   * @since 2.6.0
   6   *
   7   * @package WordPress
   8   * @subpackage Dependencies
   9   */
  10  
  11  /**
  12   * Initializes $wp_styles if it has not been set.
  13   *
  14   * @since 4.2.0
  15   *
  16   * @global WP_Styles $wp_styles
  17   *
  18   * @return WP_Styles WP_Styles instance.
  19   */
  20  function wp_styles() {
  21      global $wp_styles;
  22  
  23      if ( ! ( $wp_styles instanceof WP_Styles ) ) {
  24          $wp_styles = new WP_Styles();
  25      }
  26  
  27      return $wp_styles;
  28  }
  29  
  30  /**
  31   * Displays styles that are in the $handles queue.
  32   *
  33   * Passing an empty array to $handles prints the queue,
  34   * passing an array with one string prints that style,
  35   * and passing an array of strings prints those styles.
  36   *
  37   * @since 2.6.0
  38   *
  39   * @global WP_Styles $wp_styles The WP_Styles object for printing styles.
  40   *
  41   * @param string|bool|array $handles Styles to be printed. Default 'false'.
  42   * @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array.
  43   */
  44  function wp_print_styles( $handles = false ) {
  45      global $wp_styles;
  46  
  47      if ( '' === $handles ) { // For 'wp_head'.
  48          $handles = false;
  49      }
  50  
  51      if ( ! $handles ) {
  52          /**
  53           * Fires before styles in the $handles queue are printed.
  54           *
  55           * @since 2.6.0
  56           */
  57          do_action( 'wp_print_styles' );
  58      }
  59  
  60      _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ );
  61  
  62      if ( ! ( $wp_styles instanceof WP_Styles ) ) {
  63          if ( ! $handles ) {
  64              return array(); // No need to instantiate if nothing is there.
  65          }
  66      }
  67  
  68      return wp_styles()->do_items( $handles );
  69  }
  70  
  71  /**
  72   * Adds extra CSS styles to a registered stylesheet.
  73   *
  74   * Styles will only be added if the stylesheet is already in the queue.
  75   * Accepts a string $data containing the CSS. If two or more CSS code blocks
  76   * are added to the same stylesheet $handle, they will be printed in the order
  77   * they were added, i.e. the latter added styles can redeclare the previous.
  78   *
  79   * @see WP_Styles::add_inline_style()
  80   *
  81   * @since 3.3.0
  82   *
  83   * @param string $handle Name of the stylesheet to add the extra styles to.
  84   * @param string $data   String containing the CSS styles to be added.
  85   * @return bool True on success, false on failure.
  86   */
  87  function wp_add_inline_style( $handle, $data ) {
  88      _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
  89  
  90      if ( false !== stripos( $data, '</style>' ) ) {
  91          _doing_it_wrong(
  92              __FUNCTION__,
  93              sprintf(
  94                  /* translators: 1: <style>, 2: wp_add_inline_style() */
  95                  __( 'Do not pass %1$s tags to %2$s.' ),
  96                  '<code>&lt;style&gt;</code>',
  97                  '<code>wp_add_inline_style()</code>'
  98              ),
  99              '3.7.0'
 100          );
 101          $data = trim( preg_replace( '#<style[^>]*>(.*)</style>#is', '$1', $data ) );
 102      }
 103  
 104      return wp_styles()->add_inline_style( $handle, $data );
 105  }
 106  
 107  /**
 108   * Registers a CSS stylesheet.
 109   *
 110   * @see WP_Dependencies::add()
 111   * @link https://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
 112   *
 113   * @since 2.6.0
 114   * @since 4.3.0 A return value was added.
 115   *
 116   * @param string           $handle Name of the stylesheet. Should be unique.
 117   * @param string|false     $src    Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory.
 118   *                                 If source is set to false, stylesheet is an alias of other stylesheets it depends on.
 119   * @param string[]         $deps   Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array.
 120   * @param string|bool|null $ver    Optional. String specifying stylesheet version number, if it has one, which is added to the URL
 121   *                                 as a query string for cache busting purposes. If version is set to false, a version
 122   *                                 number is automatically added equal to current installed WordPress version.
 123   *                                 If set to null, no version is added.
 124   * @param string           $media  Optional. The media for which this stylesheet has been defined.
 125   *                                 Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like
 126   *                                 '(orientation: portrait)' and '(max-width: 640px)'.
 127   * @return bool Whether the style has been registered. True on success, false on failure.
 128   */
 129  function wp_register_style( $handle, $src, $deps = array(), $ver = false, $media = 'all' ) {
 130      _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
 131  
 132      return wp_styles()->add( $handle, $src, $deps, $ver, $media );
 133  }
 134  
 135  /**
 136   * Removes a registered stylesheet.
 137   *
 138   * @see WP_Dependencies::remove()
 139   *
 140   * @since 2.1.0
 141   *
 142   * @param string $handle Name of the stylesheet to be removed.
 143   */
 144  function wp_deregister_style( $handle ) {
 145      _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
 146  
 147      wp_styles()->remove( $handle );
 148  }
 149  
 150  /**
 151   * Enqueues a CSS stylesheet.
 152   *
 153   * Registers the style if source provided (does NOT overwrite) and enqueues.
 154   *
 155   * @see WP_Dependencies::add()
 156   * @see WP_Dependencies::enqueue()
 157   * @link https://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types.
 158   *
 159   * @since 2.6.0
 160   *
 161   * @param string           $handle Name of the stylesheet. Should be unique.
 162   * @param string           $src    Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory.
 163   *                                 Default empty.
 164   * @param string[]         $deps   Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array.
 165   * @param string|bool|null $ver    Optional. String specifying stylesheet version number, if it has one, which is added to the URL
 166   *                                 as a query string for cache busting purposes. If version is set to false, a version
 167   *                                 number is automatically added equal to current installed WordPress version.
 168   *                                 If set to null, no version is added.
 169   * @param string           $media  Optional. The media for which this stylesheet has been defined.
 170   *                                 Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like
 171   *                                 '(orientation: portrait)' and '(max-width: 640px)'.
 172   */
 173  function wp_enqueue_style( $handle, $src = '', $deps = array(), $ver = false, $media = 'all' ) {
 174      _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
 175  
 176      $wp_styles = wp_styles();
 177  
 178      if ( $src ) {
 179          $_handle = explode( '?', $handle );
 180          $wp_styles->add( $_handle[0], $src, $deps, $ver, $media );
 181      }
 182  
 183      $wp_styles->enqueue( $handle );
 184  }
 185  
 186  /**
 187   * Removes a previously enqueued CSS stylesheet.
 188   *
 189   * @see WP_Dependencies::dequeue()
 190   *
 191   * @since 3.1.0
 192   *
 193   * @param string $handle Name of the stylesheet to be removed.
 194   */
 195  function wp_dequeue_style( $handle ) {
 196      _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
 197  
 198      wp_styles()->dequeue( $handle );
 199  }
 200  
 201  /**
 202   * Checks whether a CSS stylesheet has been added to the queue.
 203   *
 204   * @since 2.8.0
 205   *
 206   * @param string $handle Name of the stylesheet.
 207   * @param string $status Optional. Status of the stylesheet to check. Default 'enqueued'.
 208   *                       Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'.
 209   * @return bool Whether style is queued.
 210   */
 211  function wp_style_is( $handle, $status = 'enqueued' ) {
 212      _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
 213  
 214      return (bool) wp_styles()->query( $handle, $status );
 215  }
 216  
 217  /**
 218   * Adds metadata to a CSS stylesheet.
 219   *
 220   * Works only if the stylesheet has already been registered.
 221   *
 222   * Possible values for $key and $value:
 223   * 'conditional' string      Comments for IE 6, lte IE 7 etc.
 224   * 'rtl'         bool|string To declare an RTL stylesheet.
 225   * 'suffix'      string      Optional suffix, used in combination with RTL.
 226   * 'alt'         bool        For rel="alternate stylesheet".
 227   * 'title'       string      For preferred/alternate stylesheets.
 228   * 'path'        string      The absolute path to a stylesheet. Stylesheet will
 229   *                           load inline when 'path' is set.
 230   *
 231   * @see WP_Dependencies::add_data()
 232   *
 233   * @since 3.6.0
 234   * @since 5.8.0 Added 'path' as an official value for $key.
 235   *              See {@see wp_maybe_inline_styles()}.
 236   *
 237   * @param string $handle Name of the stylesheet.
 238   * @param string $key    Name of data point for which we're storing a value.
 239   *                       Accepts 'conditional', 'rtl' and 'suffix', 'alt', 'title' and 'path'.
 240   * @param mixed  $value  String containing the CSS data to be added.
 241   * @return bool True on success, false on failure.
 242   */
 243  function wp_style_add_data( $handle, $key, $value ) {
 244      return wp_styles()->add_data( $handle, $key, $value );
 245  }