drupal_add_css

Versions

mediamosa-21

drupal_add_css($data = NULL, $options = NULL)

Adds a cascading stylesheet to the stylesheet queue.

Calling drupal_static_reset('drupal_add_css') will clear all cascading stylesheets added so far.

If preprocessing is turned on, the cascading style sheets added using this function will be preprocessed before they are added to the HTML header of the page. Preprocessing merges all the CSS files into one file, which is then compressed by removing all extraneous white space. Note that preprocessed inline stylesheets will not be aggregated into this single file; instead, they will just be compressed when being output on the page. External stylesheets will also not be aggregated.

The reason for merging the CSS 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."

However, you should *not* preprocess every file as this can lead to redundant caches. You should set $options['preprocess'] to FALSE when your styles are only used on a few pages of the site. This could be a special admin page, the homepage, or a handful of pages that does not represent the majority of the pages on your site.

Typical candidates for preprocessing are for example styles for nodes across the site, or styles used in the theme.

Parameters

$data (optional) The stylesheet data to be added, depending on what is passed through to the $options['type'] parameter:

• 'file': The path to the CSS file relative to the base_path(), e.g., "modules/devel/devel.css". Note that Modules should always prefix the names of their CSS files with the module name; for example, system-menus.css rather than simply menus.css. Themes can override module-supplied CSS files based on their filenames, and this prefixing helps prevent confusing name collisions for theme developers. See drupal_get_css() where the overrides are performed. Also, if the direction of the current language is right-to-left (Hebrew, Arabic, etc.), the function will also look for an RTL CSS file and append it to the list. The name of this file should have an '-rtl.css' suffix. For example a CSS file called 'mymodule-name.css' will have a 'mymodule-name-rtl.css' file added to the list, if exists in the same directory. This CSS file should contain overrides for properties which should be reversed or otherwise different in a right-to-left display.
• 'inline': A string of CSS that should be placed in the given scope. Note that it is better practice to use 'file' stylesheets, rather than 'inline', as the CSS would then be aggregated and cached.
• 'external': The absolute path to an external CSS file that is not hosted on the local server. These files will not be aggregated if CSS aggregation is enabled.

$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:

• 'type': The type of stylesheet being added. Available options are 'file', 'inline' or 'external'. Defaults to 'file'.
• 'weight': The weight of the stylesheet specifies the order in which the CSS will appear when presented on the page. Available constants are:
  • CSS_SYSTEM: Any system-layer CSS.
  • CSS_DEFAULT: Any module-layer CSS.
  • CSS_THEME: Any theme-layer CSS.

  If you need to embed a CSS file before any other module's stylesheets, for example, you would use CSS_DEFAULT - 1. Note that inline CSS is simply appended to the end of the specified scope (region), so they always come last.

• 'media': The media type for the stylesheet, e.g., all, print, screen. Defaults to 'all'.
• 'preprocess': If TRUE, Allows the CSS to be aggregated and compressed if the Optimize CSS feature has been turned on under the performance section. Defaults to TRUE.
• 'browsers': An array containing information specifying which browsers should load the CSS item. See drupal_pre_render_conditional_comments() for details.

Return value

An array of queued cascading stylesheets.

Code

includes/common.inc, line 2658

<?php
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',
      'weight' => CSS_DEFAULT,
      'media' => 'all',
      'preprocess' => TRUE,
      'data' => $data,
      'browsers' => array(),
    );
    $options['browsers'] += array(
      'IE' => TRUE,
      '!IE' => TRUE,
    );

    // 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;
      default:
        // Local and external files must keep their name as the associative key
        // so the same CSS file is not be added twice.
        $css[$data] = $options;
    }
  }

  return $css;
}
?>