WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP Styles

Description

WP_Styles is a class defined in wp-includes/class.wp-styles.php that helps developers interact with a theme. It ensures registered stylesheets are output in the proper order, with dependent stylesheets coming after their dependencies. While more than one instance can be created, typically the global $wp_styles is used to enqueue stylesheets, which are then output by wp_print_styles during the wp_head action. WP_Styles extends WP_Dependencies.

WP_Styles handles both external and embedded stylesheets (though the latter must be associated with one of the former), outputting a <link> or <style> element as appropriate.

Text direction

For any stylesheet, an additional stylesheet can be loaded for right-to-left text (triggered by setting $wp_styles->text_direction to 'rtl'). The URL for this stylesheet is built by inserting '-rtl' into the URL of the left-to-right stylesheet. Normally, '-rtl' is inserted before the '.css' extension. If 'suffix' is set in the stylesheet's extra data (using WP_Dependencies::add_data() or _WP_Dependency::add_data()), '-rtl' will be inserted before the suffix and '.css' extension ("${suffix}.css").

Concatenation vs Printing

When it comes time to output enqueued stylesheets, WP_Styles can print them, or accumulate them in instance variables ($print_html for external and $print_code for embedded). This behaviour is controlled by the boolean instance variable $do_concat. If true, output is concatenated to the appropriate instance variable; if false, it's printed.

Any unconditional, non-alternate stylesheet in a default directory (as determined by WP_Styles::in_default_dir()) isn't accumulated when $do_concat is true.

Media

The media for a stylesheet is passed via the $args argument to WP_Dependencies::add().

Methods and Properties

Properties

$base_url 
The base URL for the site, it gets prepended to the URL for an enqueued sheet in most cases (see $content_url for an exception). Set to the site URL (as determined by site_url() or wp_guess_url()) by default.
$content_url 
The URL for the wp-content directory. Set to WP_CONTENT_URL by default. If a stylesheet URL begins with the content URL, the base URL isn't prepended.
$default_version 
Default value used when a version isn't specified in a call to wp_enqueue_style() or wp_register_style().
$text_direction = 'ltr' 
If 'rtl', an addtional stylesheet will be loaded, allowing custom styling targeting right-to-left.
$do_concat = false 
If true, concatenate output to $print_html and $print_code member variables rather than printing it.
$print_html = "" 
holds accumulated HTML (<link> elements and conditional comments).
$print_code = "" 
holds accumulated embedded style rules.
$concat = "" 
list of item handles that were accumulated, separated by commas.
$concat_version = "" 
list of item handles & versions that were accumulated.
$default_dirs 
Path or array of paths. Used by WP_Styles::in_default_dir(). Compared directly to $src property of a stylesheet.

Methods

do_item( $handle ) 
process a stylesheet in the queue.
add_inline_style( $handle, $code ) 
add style rules ($code) to the given stylesheet to be output as embedded style (i.e. in a <style> element).
print_inline_style( $handle, $echo = true ) 
print (or return, if $do_concat is true) the embedded style rules for the given stylesheet.
all_deps( $handles, $recursion = false, $group = false ) 
Builds up array of stylesheets to output with dependencies coming before dependents.
in_default_dir( $src ) 
tell whether the given path is in one of the default directories ($default_dirs).
do_footer_items() 
output style sheets that were added to late to be placed in the <head>.
reset() 
clear instance variables related to accumulation.

Hooks

Actions

  • wp_default_styles - Invoked when a WP_Styles is created. The instance is passed to action hooks.

Filters

  • print_styles_array - Filters list of stylesheets to be output. Called from WP_Styles::all_deps().
  • style_loader_src - Filter a stylesheet URL in preparation for output. Happens after $base_url has been prepended (if warranted).
  • style_loader_tag - Filter the <link> element for a stylesheet.

Examples

Dependent Stylesheet

<?php 
   
global $wp_styles;
   
$wp_styles->add('example''/themes/example/example.css');
   
$wp_styles->add('example_ie7-''/themes/example/ie7-.css', array('example'));
   
$wp_styles->enqueue(array('example''example_ie7-'));
?>

Adding a Right-to-Left Stylesheet

To specify a stylesheet to add, set 'rtl' to the URL: <?php 
   
global $wp_styles;
   
$wp_styles->add('example''/themes/example/example.css');
   
$wp_styles->add_data('rtl''/themes/example/rtl.css');
   
$wp_styles->enqueue(array('example'));
?>
To have WordPress create the URL for the rtl stylesheet, set 'rtl' to TRUE and (optionally) set a suffix for the stylesheet in the extra data: <?php 
   
global $wp_styles;
   
$wp_styles->add('example''/themes/example/example-new.css');
   
$wp_styles->add_data('rtl'TRUE);
   
# URL for rtl stylesheet will be '/themes/example/example-rtl-new.css'
   
$wp_styles->add_data('suffix''-new');
   
$wp_styles->enqueue(array('example'));
?>

Embedded Style

An embedded stylesheet can be added to an external one, but sparingly: <?php
   
global $wp_styles;
   
$wp_styles->add('example''/themes/example/example.css');
   
$wp_styles->add_inline_style('example''* {margin: 0}');
   
$wp_styles->enqueue(array('example'));
?>

Conditional Styles

Conditional comments can be added around the <link> to a stylesheet by setting 'conditional' in a stylesheet's extra data: <?php
   
global $wp_styles;
   
$wp_styles->add('example_ie7-''/themes/example/ie7-.css');
   
$wp_styles->add_data('example_ie7-''conditional''lte IE 7');
   
$wp_styles->enqueue(array('example_ie7-'));
?>

Other Attributes

Other attributes include the stylesheet title, and wether it's an alternate stylesheet: <?php
   
global $wp_styles;
   
$wp_styles->add('example-alt''/themes/example/example-alt.css');
   
$wp_styles->add_data('example-alt''title''Example Alternate Stylesheet');
   
$wp_styles->add_data('example-alt''alt'TRUE);
   
$wp_styles->enqueue(array('example-alt'));
?>

Accumulation

Instead of printing style sheet elements, they can be gathered for other purposes: <?php
   
/* Create  */
   
$my_styles = new WP_Styles;
   
$my_styles->do_concat TRUE;

   
/* Add styles */
   
$my_styles->add('example''/themes/example/example.css');
   
$my_styles->add('example_ie7-''/themes/example/ie7-.css', array('example'));
   
$my_styles->add_data('example_ie7-''conditional''lte IE 7');
   
#...
   
$wp_styles->enqueue(array('example''example_ie7-', ...));

   
/* Output styles */
   
$my_styles->do_items();

   
/* */
   # 'example,example_ie7-,...'
   
$my_styles->concat;
   
# accumulated elements
   
$my_styles->print_html;
   
#...
   /* Clear  */
   
$my_styles->reset();
?>

Change Log

2.6 
Initial version: $base_url, $default_version, $text_direction, do_item(), all_deps(), conditional comments, right-to-left stylesheets, filter & action hooks.
2.8 
Added $content_url, $concat, $concat_version, $do_concat, $print_html, $default_dirs, in_default_dir(), 'alt' and 'title' attributes.
3.0 
Added 'suffix' extra data for rtl stylesheets.
3.3 
Addded support for embedded style sheets, $print_code, add_inline_style(), print_inline_style(), do_footer_items(), reset().

Source File

WP_Styles is located in wp-includes/class.wp-styles.php.

See also index of Class Reference and index of Function Reference.