Adds a cascading stylesheet to the stylesheet queue.
Calling drupal_static_reset('drupal_add_css') will clear all cascading stylesheets added so far.
If CSS aggregation/compression is enabled, all cascading style sheets added with $options['preprocess'] set to TRUE will be merged into one aggregate file and compressed by removing all extraneous white space. Preprocessed inline stylesheets will not be aggregated into this single file; instead, they are just compressed upon output on the page. Externally hosted stylesheets are never aggregated or compressed.
The reason for aggregating the files is outlined quite thoroughly here: http://www.die.net/musings/page_load_time/ "Load fewer external objects. Due to request overhead, one bigger file just loads faster than two smaller ones half its size."
$options['preprocess'] should be only set to TRUE when a file is required for all typical visitors and most pages of a site. It is critical that all preprocessed files are added unconditionally on every page, even if the files do not happen to be needed on a page. This is normally done by calling drupal_add_css() in a hook_page_build() implementation.
Non-preprocessed files should only be added to the page when they are actually needed.
$data: (optional) The stylesheet data to be added, depending on what is passed through to the $options['type'] parameter:
$options: (optional) A string defining the 'type' of CSS that is being added in the $data parameter ('file', 'inline', or 'external'), or an array which can have any or all of the following keys:
The aggregate group number affects load order and the CSS cascade. Stylesheets in an aggregate with a lower group number will be output to the page before stylesheets in an aggregate with a higher group number, so CSS within higher aggregate groups can take precendence over CSS within lower aggregate groups.
Available constants are:
The weight numbers follow the SMACSS convention of CSS categorization. See http://drupal.org/node/1887922
An array of queued cascading stylesheets.
function drupal_add_css($data = NULL, $options = NULL) {
$css =& drupal_static(__FUNCTION__, array());
// Construct the options, taking the defaults into consideration.
if (isset($options)) {
if (!is_array($options)) {
$options = array(
'type' => $options,
);
}
}
else {
$options = array();
}
// Create an array of CSS files for each media type first, since each type needs to be served
// to the browser differently.
if (isset($data)) {
$options += array(
'type' => 'file',
'group' => CSS_AGGREGATE_DEFAULT,
'weight' => 0,
'every_page' => FALSE,
'media' => 'all',
'preprocess' => TRUE,
'data' => $data,
'browsers' => array(),
);
$options['browsers'] += array(
'IE' => TRUE,
'!IE' => TRUE,
);
// Files with a query string cannot be preprocessed.
if ($options['type'] === 'file' && $options['preprocess'] && strpos($options['data'], '?') !== FALSE) {
$options['preprocess'] = FALSE;
}
// Always add a tiny value to the weight, to conserve the insertion order.
$options['weight'] += count($css) / 1000;
// Add the data to the CSS array depending on the type.
switch ($options['type']) {
case 'inline':
// For inline stylesheets, we don't want to use the $data as the array
// key as $data could be a very long string of CSS.
$css[] = $options;
break;
case 'file':
// Local CSS files are keyed by basename; if a file with the same
// basename is added more than once, it gets overridden.
// By default, take over the filename as basename.
if (!isset($options['basename'])) {
$options['basename'] = drupal_basename($data);
}
$css[$options['basename']] = $options;
break;
default:
// External files are keyed by their full URI, so the same CSS file is
// not added twice.
$css[$data] = $options;
}
}
return $css;
}