Issue #1924368 by JohnAlbin, ykhadilkar, carwin: Change notice: Rename old CSS...

Issue #1924368 by JohnAlbin, ykhadilkar, carwin: Change notice: Rename old CSS constants to CSS_AGGREGATE_* and add new CSS weight constants.

core/includes/common.inc

@@ -68,19 +68,44 @@
 const SAVED_DELETED = 3;
 
 /**
- * The default group for system CSS files added to the page.
+ * The default aggregation group for system CSS files added to the page.
  */
-const CSS_SYSTEM = -100;
+const CSS_AGGREGATE_SYSTEM = -100;
 
 /**
- * The default group for module CSS files added to the page.
+ * The default aggregation group for CSS files added to the page.
  */
-const CSS_DEFAULT = 0;
+const CSS_AGGREGATE_DEFAULT = 0;
 
 /**
- * The default group for theme CSS files added to the page.
+ * The default aggregation group for theme CSS files added to the page.
  */
-const CSS_THEME = 100;
+const CSS_AGGREGATE_THEME = 100;
+
+/**
+ * The default weight for CSS rules that style HTML elements ("base" styles).
+ */
+const CSS_BASE = -200;
+
+/**
+ * The default weight for CSS rules that layout a page.
+ */
+const CSS_LAYOUT = -100;
+
+/**
+ * The default weight for CSS rules that style design components (and their associated states and skins.)
+ */
+const CSS_COMPONENT = 0;
+
+/**
+ * The default weight for CSS rules that style states and are not included with components.
+ */
+const CSS_STATE = 100;
+
+/**
+ * The default weight for CSS rules that style skins and are not included with components.
+ */
+const CSS_SKIN = 200;
 
 /**
  * The default group for JavaScript settings added to the page.
@@ -2496,15 +2521,16 @@ function drupal_add_html_head_link($attributes, $header = FALSE) {
  *     'core/modules/node/node.css' is 'node.css'. If the external library
  *     "node.js" ships with a 'node.css', then a different, unique basename
  *     would be 'node.js.css'.
- *   - 'group': A number identifying the group in which to add the stylesheet.
- *     Available constants are:
- *     - CSS_SYSTEM: Any system-layer CSS.
- *     - CSS_DEFAULT: (default) Any module-layer CSS.
- *     - CSS_THEME: Any theme-layer CSS.
- *     The group number serves as a weight: the markup for loading a stylesheet
- *     within a lower weight group is output to the page before the markup for
- *     loading a stylesheet within a higher weight group, so CSS within higher
- *     weight groups take precendence over CSS within lower weight groups.
+ *   - 'group': A number identifying the aggregation group in which to add the
+ *     stylesheet. Available constants are:
+ *     - CSS_AGGREGATE_SYSTEM: Any system-layer CSS.
+ *     - CSS_AGGREGATE_DEFAULT: (default) Any module-layer CSS.
+ *     - CSS_AGGREGATE_THEME: Any theme-layer CSS.
+ *     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.
  *   - 'every_page': For optimal front-end performance when aggregation is
  *     enabled, this should be set to TRUE if the stylesheet is present on every
  *     page of the website for users for whom it is present at all. This
@@ -2527,17 +2553,29 @@ function drupal_add_html_head_link($attributes, $header = FALSE) {
  *     small by ensuring that most commonly needed stylesheets are added to
  *     every page.
  *   - 'weight': The weight of the stylesheet specifies the order in which the
- *     CSS will appear relative to other stylesheets with the same group and
- *     'every_page' flag. The exact ordering of stylesheets is as follows:
- *     - First by group.
+ *     CSS will appear relative to other stylesheets with the same aggregate
+ *     group and 'every_page' flag. The exact ordering of stylesheets is as
+ *     follows:
+ *     - First by aggregate group.
  *     - Then by the 'every_page' flag, with TRUE coming before FALSE.
  *     - Then by weight.
  *     - Then by the order in which the CSS was added. For example, all else
  *       being the same, a stylesheet added by a call to drupal_add_css() that
  *       happened later in the page request gets added to the page after one for
  *       which drupal_add_css() happened earlier in the page request.
+ *     Available constants are:
+ *     - CSS_BASE: Styles for HTML elements ("base" styles).
+ *     - CSS_LAYOUT: Styles that layout a page.
+ *     - CSS_COMPONENT: Styles for design components (and their associated
+ *       states and skins.)
+ *     - CSS_STATE: Styles for states that are not included with components.
+ *     - CSS_SKIN: Styles for skins that are not included with components.
+ *     The weight numbers follow the SMACSS convention of CSS categorization.
+ *     See http://drupal.org/node/1887922
  *   - 'media': The media type for the stylesheet, e.g., all, print, screen.
- *     Defaults to 'all'.
+ *     Defaults to 'all'. It is extremely important to leave this set to 'all'
+ *     or it will negatively impact front-end peformance. Instead add a @media
+ *     block to the included CSS file.
  *   - 'preprocess': If TRUE and CSS aggregation/compression is enabled, the
  *     styles will be aggregated and compressed. Defaults to TRUE.
  *   - 'browsers': An array containing information specifying which browsers
@@ -2567,7 +2605,7 @@ function drupal_add_css($data = NULL, $options = NULL) {
   if (isset($data)) {
     $options += array(
       'type' => 'file',
-      'group' => CSS_DEFAULT,
+      'group' => CSS_AGGREGATE_DEFAULT,
       'weight' => 0,
       'every_page' => FALSE,
       'media' => 'all',
@@ -2710,10 +2748,10 @@ function drupal_get_css($css = NULL, $skip_alter = FALSE) {
  * @see drupal_add_js()
  */
 function drupal_sort_css_js($a, $b) {
-  // First order by group, so that, for example, all items in the CSS_SYSTEM
-  // group appear before items in the CSS_DEFAULT group, which appear before
-  // all items in the CSS_THEME group. Modules may create additional groups by
-  // defining their own constants.
+  // First order by group, so that, for example, all items in the
+  // CSS_AGGREGATE_SYSTEM group appear before items in the CSS_AGGREGATE_DEFAULT
+  // group, which appear before all items in the CSS_AGGREGATE_THEME group.
+  // Modules may create additional groups by defining their own constants.
   if ($a['group'] < $b['group']) {
     return -1;
   }

core/includes/theme.inc

@@ -209,7 +209,7 @@ function _drupal_theme_initialize($theme, $base_theme = array(), $registry_callb
   // And now add the stylesheets properly
   foreach ($final_stylesheets as $media => $stylesheets) {
     foreach ($stylesheets as $stylesheet) {
-      drupal_add_css($stylesheet, array('group' => CSS_THEME, 'every_page' => TRUE, 'media' => $media));
+      drupal_add_css($stylesheet, array('group' => CSS_AGGREGATE_THEME, 'every_page' => TRUE, 'media' => $media));
     }
   }
 

core/modules/system/lib/Drupal/system/Tests/Ajax/FrameworkTest.php

@@ -113,7 +113,7 @@ function testLazyLoad() {
     // @todo D8: Add a drupal_css_defaults() helper function.
     $expected_css_html = drupal_get_css(array($expected_css_basename => array(
       'type' => 'file',
-      'group' => CSS_DEFAULT,
+      'group' => CSS_AGGREGATE_DEFAULT,
       'weight' => 0,
       'every_page' => FALSE,
       'media' => 'all',

core/modules/system/lib/Drupal/system/Tests/Common/CascadingStylesheetsTest.php

@@ -156,8 +156,8 @@ function testRenderOrder() {
     drupal_add_css(drupal_get_path('module', 'simpletest') . '/simpletest.css');
     // A few system CSS files, ordered in a strange way.
     $system_path = drupal_get_path('module', 'system');
-    drupal_add_css($system_path . '/system.base.css', array('group' => CSS_SYSTEM, 'weight' => -10));
-    drupal_add_css($system_path . '/system.theme.css', array('group' => CSS_SYSTEM));
+    drupal_add_css($system_path . '/system.base.css', array('group' => CSS_AGGREGATE_SYSTEM, 'weight' => -10));
+    drupal_add_css($system_path . '/system.theme.css', array('group' => CSS_AGGREGATE_SYSTEM));
 
     $expected = array(
       $system_path . '/system.base.css',

core/modules/system/system.module

@@ -2561,12 +2561,12 @@ function system_init() {
  */
 function system_page_build(&$page) {
   $path = drupal_get_path('module', 'system');
-  // Use the CSS_SYSTEM group to load these early.
-  $page['#attached']['css'][$path . '/system.base.css'] = array('group' => CSS_SYSTEM, 'every_page' => TRUE);
+  // Use the CSS_AGGREGATE_SYSTEM group to load these early.
+  $page['#attached']['css'][$path . '/system.base.css'] = array('group' => CSS_AGGREGATE_SYSTEM, 'every_page' => TRUE);
   if (path_is_admin(current_path())) {
-    $page['#attached']['css'][$path . '/system.admin.css'] = array('group' => CSS_SYSTEM);
+    $page['#attached']['css'][$path . '/system.admin.css'] = array('group' => CSS_AGGREGATE_SYSTEM);
   }
-  $page['#attached']['css'][$path . '/system.theme.css'] = array('group' => CSS_SYSTEM, 'every_page' => TRUE);
+  $page['#attached']['css'][$path . '/system.theme.css'] = array('group' => CSS_AGGREGATE_SYSTEM, 'every_page' => TRUE);
 }
 
 /**

core/themes/seven/template.php

@@ -23,7 +23,7 @@ function seven_preprocess_maintenance_page(&$vars) {
 function seven_preprocess_html(&$vars) {
   drupal_add_library('system', 'normalize');
   // Add conditional CSS for IE8 and below.
-  drupal_add_css(path_to_theme() . '/ie.css', array('group' => CSS_THEME, 'browsers' => array('IE' => 'lte IE 8', '!IE' => FALSE), 'weight' => 999, 'preprocess' => FALSE));
+  drupal_add_css(path_to_theme() . '/ie.css', array('group' => CSS_AGGREGATE_THEME, 'browsers' => array('IE' => 'lte IE 8', '!IE' => FALSE), 'weight' => 999, 'preprocess' => FALSE));
 }
 
 /**