Drupal 8 theming concepts

A theme is a collection of files that define the presentation layer. You can also create one or more "sub-themes" or variations on a theme. drupal.org/docs/8/theming.

The big change from Drupal 7 to Drupal 8 for theming is the change from PHP templates to twig and the use of yml "YAML" files.

CSS file organization

Drupal 8 follows the SMACSS-style categorization. (SMACSS = Scalable and modular architecture for css).

Base — CSS reset/normalize plus HTML element styling.

Layout — macro arrangement of a web page, including any grid systems.

Component — discrete, reusable UI elements.

State — styles that deal with client-side changes to components.

Theme — purely visual styling (“look-and-feel”) for a component.

CSS file naming conventions

CSS files should be placed in a css/ directory and broken down by module, theme, and admin files.

Note: Modules should never have any base styles. Drupal core's modules do not have any base styles. Instead Drupal core uses the Normalize.css library augmented with a drupal.base.css library.If a module attaches a CSS file to a template file, the CSS file should be named the same as the template file, e.g. the system-plugin-ui-form.html.twig CSS file should be named system-plugin-ui-form.css

YAML / YML

yaml  is a "human readable" markup language designed for data serialization for all programing languages.

Syntax for yml is key : value

Use a colon as a separator

Tabs are NOT allowed. Use spaces ONLY.

Properties and lists MUST be indented by two (2) spaces.

Yaml files end in the .yml file extension.

In Drupal 7, modules needed a MODULE_NAME.info file. Now, in Drupal 8 requires a MODULE_NAME.info.yml

Use yaml lint to find syntax errors. BLT can validate yml with blt validate:yaml.

Example - 

name: Hello World Module

description: Creates a page showing "Hello World".

package: Custom

type: module

core: 8.x

Libraries

Sometimes a site will require an external library. Libraries can be defined 3 different ways, within a theme, on a single page, or on a subset of pages with a preprocess function.

Each asset/library needs to be defined in the root of your module folder or in your theme root directory. For example the Drupal contrib module slick requires the external slick library. Inside of the theme directory docroot/themes/custom/MY_THEME there needs to be a MY_THEME.libraries.yml file.

slick:  

  version: 1.0.0  

  css:    

    theme:      

        stylesheets/ui/slick-rotator.css: {}

In the above example the theme key is for visual styling for a component. You can assign weights, or specify a theme. Therefore, in this example the asset/library slick has defined a css file included inside of the slick module directory.

Define a library on a single template

External libraries can increase the weight of a project and slow down a site's performance. If a custom javaScript library only needs to load on a single template, it might make sense to attach the library to only that template. For example, if you add attach_library to the top of twig template file, the library will only load whenever that twig template is used.

{# Place attach_library in a twig template. #}

{{ attach_library('THEME_NAME/library-name') }}

Define a library on a subset of pages

There can also be instances where you only need to add a library to a specific set of pages instead of every page. You can accomplish this with a preprocess function added the THEME_NAME.theme file.

function MY_THEME_page_attachments(array &$attachments) {

if (!\Drupal::currentUser()->hasPermission('access contextual links')) {  

  return;  

}

$attachments['#attached']['library'][] = 'contextual/drupal.contextual-links';

}