3) Libraries - Including JavaScript and CSS in Drupal 8 Themes
Image source: Joshua Brandenburg

3) Libraries - Including JavaScript and CSS in Drupal 8 Themes

November 27, 2015

Lessons From the Road

Back in 2014, I set out on an adventure with Memorial Sloan Kettering and multiple web and design agencies to begin building the first fully-operational, enterprise-level Drupal 8 website. We succesfully launched the site in May of 2015. I want to share some of the real-world lessons I learned over the past year, so that hopefully you can start adopting Drupal 8.

Libraries - Including JS and CSS

JS and CSS are included in D8 via libraries.

Using libraries in our themes keeps development more consistent between creating custom modules and custom themes. One major advantage to this approach is that libraries provide the ability use dependencies to insure proper source order of JS libraries. So we no longer need to rely only on fiddling around with weights and scopes.

Declare the library in .info.yml

We need to make Drupal aware that this theme has a library. To do so, in the themes THEMENAME.info.yml file, we declare the library.

libraries:
  - THEMENAME/LIBRARYNAME
  - THEMENAME/NAMESPACE.LIBRARYNAME2

libraries:
  - mskcc/msk.globalstyles
  - mskcc/msk.globalscripts

It is a good idea to namespace your library name (by prepending it with a unique site or theme abbrevation) so that you don’t unintentionally declare the same library name as some other module, etc.

Note: Libraries silently fail if they don’t load.

Create libraries.yml file

Create a file THEMENAME.libraries.yml in your theme folder. This file will list out and define all of your libraries. A given library can include both CSS and JS. (The above examples have them separate.)

Example CSS Library

Here is an example of defining a library for CSS.

NAMESPACE.LIBRARYNAME:
    css:
      theme:
        path/to/cssfile.css: { }

  msk.globalstyles:
    css:
      theme:
        //cloud.typography.com/7801712/653006/css/fonts.css: { }
        assets/styles/legacy.css: { browsers: { IE: 'lt IE 9', '!IE': false } }
        assets/styles/main.css: { browsers: { IE: 'gt IE 8', '!IE': true } }
        css/drupal-compatibility.css: { }

Note the necessity of the “theme:” heading under css. These sub-groupings are available: theme, base, layout, component, and state.

Paths are relative to theme folder root.

The curly brackets contain additional parameters, and must be present even if no paramaters are being passed.

CSS Parameters

Most paramaters that were available in Drupal 7’s drupal_add_css can be translated into parameters in Drupal 8 libraries.

Some example parameters:

  • browsers: { IE: ‘gt IE 8’, ‘!IE’: true },
  • every_page: true,
  • weight: -10,
  • preprocess: FALSE

Example JS Library

Here is an example of defining a library with JS.

NAMESPACE.LIBRARYNAME :
    version: VERSION
    js:
      path/to/jsfile.js: {}
    path/to/jsfile2.js: {}
    dependencies:
      - MODULE/LIBRARYNAME
      - THEMENAME/LIBRARYNAME

  msk.globalscripts:
    version: VERSION
    js:
      js/drupal-compatibility.js: {}
      assets/tmp/concat/assets/scripts/main.js: {}
  
    dependencies:
      - core/jquery
      - core/jquery.ui
      - core/jquery.ui.effects.blind
      - core/jquery.ui.dialog
      - core/drupal
      - core/modernizr
      - core/html5shiv
      - mskcc/msk.jPushMenu
  
  msk.jPushMenu:
    js:
      assets/scripts/vendor/jPushMenu_custom.js: {}

Note: there is no “theme:” heading under js:

The curly brackets contain additional parameters, and must be present even if no paramaters are being passed.

dependencies: This lists out other libraries upon which this library depends. You can refer to core libraries or other libraries defined in this same libraries.yml file of the theme.

Look in core/core.libraries.yml (and search through all *libraries.yml files in core) to find the names of libraries that you may need to list as dependencies and to find many examples of how to define libraries and use parameters.

Example JS Parameters

  • every_page: true,
  • weight: -22,
  • browsers: { IE: ‘lte IE 8’, ‘!IE’: false },
  • minified: true
  • preprocess: 0,
  • scope: header, footer