New stylesheets-override and stylesheets-remove theme .info.yml file properties

Posted by sun on December 30, 2012 at 1:35pm

Project:

Drupal core

Introduced in branch:

8.x

Issues:

#575298: Provide non-PHP way to reliably override CSS

#1861676: Remove stylesheets[] and scripts[] .info file property support for modules

#1793074: Convert .info files to YAML

Description:

Prior to Drupal 8, there was a single stylesheets[] property for theme .info files, which allowed to

add new CSS files of a theme or base theme
override (replace) CSS files that were previously added by a module or base theme in a theme
remove CSS files of a module or base theme

The baked-in facility to override and remove CSS files was partially broken in that it caused the replacement CSS files to be loaded in a different order/position than the original, and all other meta/loading properties of the original CSS file got lost, since the file essentially was re-defined from scratch.

This rendered the override/remove facility of the stylesheets[] property useless for most cases and theme authors had to resort to writing relatively complex PHP code to achieve the correct behavior. This problem has been fixed in Drupal 8 by introducing dedicated and separate theme .info.yml file properties for adding, overriding, and removing stylesheets.

Drupal 7

mytheme.info:

; Add a new CSS file:
stylesheets[all][] = layout.css

; Override a CSS file:
; WARNING: The file is moved from its original position to the
;   end of the CSS files stack! Use the PHP override code below.
stylesheets[all][] = system.theme.css

; Remove a module CSS file by *adding* it but without supplying
; the actual file in the filesystem:
stylesheets[all][] = node.css

template.php:

<?php
/**
 * Implements hook_css_alter().
 */
function mytheme_css_alter(&$css) {
  // Use our vertical tabs style instead of the default one.
  if (isset($css['core/misc/vertical-tabs.css'])) {
    $css['core/misc/vertical-tabs.css']['data'] = drupal_get_path('theme', 'mytheme') . '/vertical-tabs.css';
  }
}
?>

Drupal 8

mytheme.info.yml:

# Add a new CSS file:
stylesheets:
  all:
    - layout.css

# Override a CSS file:
stylesheets-override:
  - system.theme.css

# Remove a CSS file:
stylesheets-remove:
  - node.css

Notes

All CSS files are "keyed" by their file (base)names, which means that you are free to put your theme's CSS files into a ./css subdirectory and the override/remove properties still work as you'd expect; i.e., they do not care for the path/directory names and this works, too:
# Override the system.theme.css file with our version in the ./css subdirectory: stylesheets-override: - css/system.theme.css

Inheritance

The override and remove logic applies to base themes, too. The behavior and logic is how you would expect it to be — the following table describes the effects:

Description	Base theme	Sub theme	File used
Override combinations:
Base theme overrides a stylesheet, sub theme inherits it.	`stylesheets-override: - file.css`	→	base-theme/file.css
Sub theme overrides a stylesheet.		`stylesheets-override: - file.css`	sub-theme/file.css
Base theme adds a stylesheet, sub theme overrides it.	`stylesheets: all: - file.css`	`stylesheets-override: - file.css`	sub-theme/file.css
Base theme removes a stylesheet, sub theme overrides it.	stylesheets-remove[] = file.css `stylesheets-remove: - file.css`	`stylesheets-override: - file.css`	sub-theme/file.css
Remove combinations:
Base theme removes a stylesheet; sub theme inherits it.	`stylesheets-remove: - file.css`	→	None
Sub theme removes a stylesheet.		`stylesheets-remove: -file.css`	None
Base theme adds a stylesheet; sub theme removes it.	`stylesheets: all: - file.css`	`stylesheets-remove: - file.css`	None
Base theme overrides a stylesheet, sub theme removes it.	`stylesheets-override: - file.css`	`stylesheets-remove: - file.css`	None

Impacts:

Themers

Updates Done (doc team, etc.)

Online documentation:

Not done

Theming guide:

Not done

Module developer documentation:

Not done

Examples project:

Not done

Coder Review:

Not done

Coder Upgrade:

Not done

Other:

Other updates done

Comments

I'm confused, is this

Posted by SebCorbin on December 30, 2012 at 4:33pm

I'm confused, is this compatible with http://drupal.org/node/1876152 ?

Yes

Posted by nbz on January 1, 2013 at 5:52pm

From what I understand, that is for modules, this is for themes.

Module .info files no longer handle theme related stuff.
Theme .info files can override currently attached css files.