If you ever had to overwrite a module’s css file or a core javascript library in Drupal 7, you likely remember the experience. And not because it was a glorious encounter that left you teary-eyed at the sheer beauty of its ease and simplicity.
Along with Drupal 8 came the Libraries API and a new standard of adding CSS and JS assets and managing libraries. In true Drupal 8 fashion, the new system uses YAML files to grant developers flexibility and control over their CSS and JS assets. This gives you the ability to overwrite core libraries, add libraries directly to templates, specify dependencies and more.
There are many pros to this approach. The most important improvement being that you can add these assets conditionally. The FOAD technique and other hackish ways to overwrite core CSS files or javascript libraries are long gone. This is extraordinarily good news!
However, the simplicity of the drupal_add_js() and drupal_add_css() functions have also disappeared, and now you have to navigate a potentially overwhelming and confusing nest of yml’s just to add some custom CSS or javascript to a page. (No, you can’t just add css via the theme’s .info file). In this post, I’ll guide you through the new Libraries API in Drupal 8 so you can nimbly place assets like you’ve always dreamed.
Prerequisites
If you haven’t yet experienced the glory that is the yml file, you’ll want to get familiar. Read this great introduction to YAML then come back to this post.
Creating Libraries
First step is to create your libraries.yml file at your-theme-name.libraries.yml or your-module-name.libraries.yml.
Here’s an example of how you define a Drupal 8 library.
A few things to note:
- The path to CSS and JS files are relative to the theme or module directory that contains the libraries.yml file. We’ll cover that in more depth shortly.
- The dependencies, in this case jQuery, are any other library your library depends on. They will automatically be attached wherever you attach your library and will load before yours.
- Multiple libraries can be defined in one libraries.yml file, so each library in the file must have a unique name. However the libraries will be namespaced as mytheme/mylibrary or mymodule/mylibrary so a libraries.yml file in your theme and libraries.yml file in your module can contain libraries with the same name.
- The css files are organized according to the SMACSS categories. This gives some control over the order of which assets are added to your page. The css files will be added according to their category. So any css file in the theme category will be added last, regardless of whether or not it comes from the base theme or the active child theme. Javascript files are not organized by SMACSS category.
Now that you know the library basics, it’s time to up the ante.
Properties
You can add additional properties inside the curly braces that allow you to define where the javascript is included, additional ordering of files, browser properties and more. We won’t cover all the possibilities just now, but here are some examples
Attaching Libraries
The simplest way to attach libraries globally is through the your-theme-name.info.yml file. Instead of adding stylesheets and scripts ala Drupal 7, you now attach libraries like so:
Global is great and all, but perhaps the coolest libraries upgrade in Drupal 8 is the ability to attach libraries via twig templates. For example, if you have a search form block, you can define the css and js for the block, add it to a library, and add that library to the search form block twig template. Those assets specific to the search form block will only be included when the block is rendered.
And yes, you can also attach libraries with our ol’ pal php.
Extending and Overriding Libraries
Another boon is the ability to extend and override libraries. These extensions and overrides take place in the your-theme-name.info.yml file.
As you might expect, libraries-extend respects the conditions of the library is being extended. Maybe you have a forum module that comes with css and js out-of-the-box. If you want to tweak the styling, you can extend the forum modules library, and add your own css file.
For overrides, you can remove or override a specific file or an entire library.
Final Considerations
Before we wrap up, I'll send you on your way with a couple final considerations and gotcha's that you need to be aware of.
- The Libraries API Module is still relevant in Drupal 8, and should be used to handle external libraries that don't ship with drupal or a module or theme. It also allows libraries to be used by multiple modules or sites.
- If a file is already linked to within a library it won't get added a second time.
- Module CSS files are grouped before theme CSS files, so a module's css file will always be loaded before a theme's css file.
- Refer to the Drupal 8 Theming Guide for more info.
Thanks for reading. Now go forth and use your asset placing powers for good, not evil.