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.
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"
).
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.
The media for a stylesheet is passed via the $args argument to WP_Dependencies::add()
.
site_url()
or wp_guess_url()
) by default.WP_CONTENT_URL
by default. If a stylesheet URL begins with the content URL, the base URL isn't prepended.WP_Styles::in_default_dir()
. Compared directly to $src property of a stylesheet.WP_Styles::all_deps()
.
<?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-'));
?>
To specify a stylesheet to add, set 'rtl' to the URL:
<?php
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:
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'));
?>
<?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'));
?>
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 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 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'));
?>
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();
?>
do_item()
, all_deps()
, conditional comments, right-to-left stylesheets, filter & action hooks.in_default_dir()
, 'alt' and 'title' attributes.add_inline_style()
, print_inline_style()
, do_footer_items()
, reset()
.WP_Styles is located in wp-includes/class.wp-styles.php
.