Assets and libraries

Working with CSS and JS files has become standardized in Drupal 8 compared to its previous version where we had more than one way to do things. And this, of course, continues in Drupal 9. Libraries are key, so let's see how they work by going through some examples of making use of some CSS or JS files.

There are three steps to adding assets to your page:

• Creating your CSS/JS file
• Creating a library that includes them
• Attaching that library to a render array

Libraries

Assuming that you already have the CSS/JS files, libraries are defined inside a module_name.libraries.yml file in the module root folder. A simple example of a library definition inside this file would look like this:

my-library:

version: 1.x

css:

   theme:

     css/my_library.css: {}

js:

   js/my_library.js: {}

This is a standard YAML notation by which we define a library called my-library and provide some information about it. We can specify a version number and then add as many CSS and JS file references as we need. The file paths are relative to the module folder this library definition is in, and we can add some options between the curly braces (more advanced, but we will see an example in a moment).

Additionally, you'll note that the CSS file has an extra level key called theme. This is to indicate the type of CSS to be included and can be one of the following (based on SMACSS (https://smacss.com/) standards):

• base: Usually contains CSS reset/normalizers and HTML element styling
• layout: High-level page styling, such as grid systems
• component: UI elements and reusable components
• state: Styles used in client-side changes to components
• theme: Visual styling of components

The choice here is also reflected in the weighting of the CSS file inclusion, the latter being the "heaviest"—it will be included last.

Another important aspect of using libraries in any application is the ability to include externally hosted files (usually from a CDN). Let's take a look at an example library definition that uses externally hosted files:

angular.angularjs:

   remote: https://github.com/angular/angular.js

   version: 1.4.4

   license:

     name: MIT

     url: https://github.com/angular/angular.js/blob/master/     LICENSE

     gpl-compatible: true

   js:

     https://ajax.googleapis.com/ajax/libs/angularjs/1.4.4/     angular.min.js: { type: external, minified: true }

This example is taken from a Drupal.org example (https://www.drupal.org/docs/8/creating-custom-modules/adding-stylesheets-css-and-javascript-js-to-a-drupal-8-module) on defining libraries in Drupal since version 8. However, as you can see, the structure is the same as our previous example, except that it has some more meta information regarding the external library. And instead of a local path reference, we have a remote URL to the actual resource. Moreover, we also see some options within the curly braces with which we can specify that the file is actually externally located and minified.

An important note when it comes to JS in Drupal is that it doesn't include all libraries such as jQuery by default. It does so only when and where it's needed. This has, therefore, brought the concept of library dependencies to the forefront, as certain scripts require other libraries to be loaded for them to work.

Let's assume that my-library depends on jQuery and specify it as a dependency. All we need to add to our library definition is the following:

dependencies:

  - core/jquery

Keep in mind that the dependencies key is at the same YML level as css and js.

With this, we declare the Drupal core jQuery library to be required by our library. This means that if we use our library somewhere and jQuery is not included, Drupal will process the dependencies and include them all. A side-benefit of this is that dependencies are always included before our scripts, so we can also control that.

The core/jquery notation indicates that the extension (module or theme) that defines the jquery library is Drupal core. If it had been a module or theme, core would have been replaced by the module or theme machine name. So, for example, to use our new library somewhere, it would be referenced as module_name/my-library.

Attaching libraries

The most common way you'll be using libraries is attaching them to your render arrays. This approach implies that the library is needed for the rendering of that component so that if said component is missing from the page, the library assets are no longer included.

Here is what a render array would look like with the previous library we defined attached to it:

return [

  '#theme' => 'some_theme_hook',

  '#some_variable' => $some_variable,

  '#attached' => [

    'library' => [

      'my_module/my-library',

     ],

  ],

];

The #attached property is important here, and it signifies that we are essentially attaching something to the render array, which in our case happens to be a library.

However, you may have cases in which the library you need is not linked to a specific render array (a component on the page) but to the entire page itself—all pages or a subset. To attach libraries to an entire page, you can implement hook_page_attachments(). Consider the following example:

function hook_page_attachments(array &$attachments) {

  $attachments['#attached']['library'][] = 'my_module/my-  library';

}

This hook is called on each page, so you can also attach libraries contextually (for example, if the user has a specific role or something like that). Moreover, there is also the hook_page_attachments_alter() hook, which you can use to alter any existing attachments (for example, to remove attachments from the page).

Another way you can attach libraries is inside a preprocess function. We talked about preprocess functions earlier in this chapter; it's simple to achieve:

function my_module_preprocess_theme_hook(&$variables) {

  $variables['#attached']['library'][] = 'my_module/my_  library';

}

All you have to do is add the #attached key (if it doesn't already exist) to the variables array.

These three methods of attaching libraries are the most common ones you'll encounter and use yourself. However, there are a few other ways and places where attachments can be added—you can alter an existing render element definition and you can attach libraries directly to a Twig file. I recommend that you read the Drupal.org documentation (https://www.drupal.org/docs/8/creating-custom-modules/adding-stylesheets-css-and-javascript-js-to-a-drupal-8-module) for more information on these methods.