 All right. Welcome, everybody. We've got a quick 25-minute session here, so we're going to go ahead and get started. So this is mastering the library's API in Drupal 8. And if you've done any work with Drupal 8, you probably noticed that placing CSS and JavaScript is pretty different from Drupal 7, so we're going to talk about some of those differences. My name is Matt Jager. I'm a front-end developer and tech lead at Atten Design Group. We're a full-service strategy design development shop out of Denver, Colorado. And we've got a nice-sized team of 25 people. We're project managers, designers, and engineers. We build digital projects. And we're super lucky to work with awesome college-driven organizations from all over the world. Stanford, Human Rights Watch for some of our clients. And just a couple of acknowledgments before we get started. A presentation by David Hernandez inspired a lot of this presentation. Also borrowed some stuff from my colleagues, John Ferris and Peter Weber as well, so thanks for those guys. So why are we going to talk about the library's API? So in Drupal 7, it was pretty easy to add CSS and JavaScript assets globally, but there really wasn't a good way to add these assets conditionally. And we also had this problem where if you ever tried to override a CSS file from core or core JavaScript library, you might end up doing something really strange like this FODE technique, where you're basically tricking the system into forgetting those CSS files. Otherwise you had to do a ton of overrides. So there were some hacks in ways that you could place assets conditionally and stop assets from being loaded, but there were just kind of some combination of terrible and disturbing. So in Drupal 8, we've got a new way of managing these assets and libraries, which at first it can seem a little complex, where before it might have seemed easier, but there's a lot more flexibility, there's a lot more control, and it's a pretty great new system. So step one is to define your libraries. So in any custom theme or custom module you have this libraries.yaml file, and this is a super basic stripped down version, so we're just going to walk through what it is here. So you name your library, and this is important because you're going to reference it later. So in this case the name is global, and then you have your CSS files, you have your JavaScript files, and then you can specify any dependencies, which is great. So whenever you're adding this library to a page or to a template, any of those dependencies will be added automatically. Another thing that's important to notice is under CSS we have the smacks category, so you're placing the path to that CSS file relative to the directory, and in this case it's located under theme. So we're going to talk about that a little bit. So the CSS assets in the libraries file, these are organized according to the smacks categorization, which is basically a way of structuring your CSS architecture, and it's really important that you place it under one of these five categories, otherwise it won't work. And what else is cool about this is it gives you a way to specify the order of which those CSS assets will be added to the page. So anything that you add under base is going to be added first, and then it just goes down the line, and then anything added under theme will be added last. There are a few other considerations there, but that's kind of the basic setup of how to organize your CSS files. So this is another example of an external library that you can add. So you're in that same file, your libraries.yaml file, you can add multiple libraries to this page, and you can do a basic one like we just looked at, or you can do an external library, and there's some other information, other metadata that you can include in there, but this is kind of the basic way that that's structured. But the important takeaway here is just that you have this option of referencing these external libraries in the same libraries.yaml file. And there's also a core libraries.yaml file, which is super great if you're curious about how to set up your libraries, if you want to see the different options. Core.libraries.yaml has many, many libraries that are specified there, so you can pop in there and take a look and see some of the different properties that you can use, different ways of structuring things. It's just a great reference and a great resource, so keep that in mind. So now we're going away from that super basic library definition to one that's a little bit more advanced, so this one is called JS header, and there's a couple more things that we're specifying here. So with CSS, we have that smacks categorization that allows you to specify the order to which the CSS is added to the page, and in Drupal, the JavaScript assets by default will be added to the footer. So if you want to add those to the header, you have this header, you can set the header to true, and then that will put those JavaScript assets in the header. And then what else is cool here is we have these other properties underneath the file, so in this case, in this example, if we're adding this Google API map library, we also want to add these attributes to the script, and so underneath that, you can set the type to external, which tells Drupal that this is an external library, and then under those attributes, those will basically be added to the script tag, so we have defer set to true, async is set to true, and then if we go to the next page here, so this will actually build the script tag, and it's adding it to the header of the site, and then you can see, we're running out of room over there, but you can see the async and defer, those tags are being added into the script that we specified as attributes over here. So you have a lot of control over how you build those script tags where they get added. So those are the basics of how you define libraries, just a quick overview of some of the options, but again, look at that core libraries.yaml file for more examples, so now we're going to move into attaching libraries, how do we actually attach the libraries? So Drupal addjs is gone, Drupal add css is gone, we don't have these basic functions, but there's still a number of ways that we can attach the assets in Drupal 8. So someone's singing back there, it's kind of awesome. So in your theme.info.yaml file, this is the way that you can add those libraries globally. So this is again a super basic example, you have some of the basic theme definitions in your info.yaml file. And then under libraries, you're just specifying which of those libraries you want to attach globally. So it uses that same name convention, so it'll be your theme dash global, whatever name you gave that library in the libraries.yaml file. So the libraries can have the same name in different files, or in different themes or different modules, because it's referencing that my theme or my module slash the library name. So that's how you attach them globally there. Another way that you can do it is you can attach them using twig directly to the template. So in our example, for a lot of the sites that we're building currently, we're using the components module. And so we have this header component. And when we define the header, when we build out that template using twig, then we attach the header library directly to that twig template. And so anytime that header component is being rendered, then we have our CSS assets that we need, we have our JavaScript assets that we need. And so you can be really granular and have a lot of control over how you're adding those assets. And this is really great, especially for component based design, atomic design, that kind of stuff. You can also still add them in PHP. So this is an example of a pre-process function. So for this example, for one of our clients, they have a donate page, and they're referencing this external library where we have to pull in this external JavaScript asset. And so we're just saying, for this specific page using the pre-process function, we're going to add in that library. And you do that by attaching it to that attached array in the key in the variables object. Another thing that's cool, and we haven't used this a whole lot, but it's this idea that you can attach libraries conditionally. So we can actually put some logic into our twig templates that say, if the certain variable exists, then we want to attach library. If the variable doesn't exist, then we want to attach a different library or not attach it at all. So in this example, we're saying if there's a certain data set that's being added to this page, then we want to include our chart library so that we can render that data using specific CSS or JavaScript. Otherwise, we can define a different library, attach a different library, or just not attach one at all. So those are the basics of attaching the library. Now we're going to look at how we can extend and override libraries. So we do this as well in the theme.info.yaml file. So the same place where we attach the libraries globally, we can also extend and override them. So underneath the area where you define the libraries, then you have this library's extent. And in this example, basically what we want to say is anywhere that we're displaying these forums, so if we have the classic theme installed and we're displaying those forums, and we want to do some tweaks to the styling of those forums, then we can attach and extend that library to include our own CSS that might tweak the styling of how those forums are displayed. And then it follows the same conditional logic. So anywhere that the forums are displayed, then our library goes along for the ride. So you're able to, there's a lot of power in the ability to extend libraries, make styling tweaks to anything that comes in a module or comes from core. It just makes it a lot easier to tweak those styles or add some JavaScript. And I think this is one of the places where the library's API in Drupal 8 is the most powerful, is our ability to override libraries. So again, if you install a module and it comes with its own styling, it comes with its own JavaScript files, it's referencing a specific JavaScript library, you can actually go in and replace that entire library. And you do that in the same place in your info.yaml file. So you specify libraries overrides, and then you basically call the namespace of the library that you want to override. So in this example, we have core Drupal collapse is the name of the library. And then you're just replacing that with the name of your library, using that same naming convention, your theme, your module slash name of the library. So that's if you want to replace it, and then if you want to remove an entire library, then you reference it, again, the same way using that namespace, and then you just set it to false. So in this example, we're replacing or removing entire libraries. And then you also have granular control, where you can replace or override just specific files. And so usually the best way to do this is to go in to the library that you want to override, and just copy that in, because you have to follow that same convention of how the CSS is organized, how the JavaScript is organized. So for example, here, we have csslayout.css that we want to override, but that's under the theme smacks category. So if you want to override that specific file, you have to put it in the same place. So you can go into that base theme library, copy this in to your info.yaml file, and then say I want to override the layout.css file with my own, let's say subtheme layout.css. And then it's basically the same process if we want to remove a specific file. So same thing as if you're removing an entire library, you just go in and set that specific file to false, and then it won't be loaded to the page. So in D7, the library's APA was a separate contrib module, and in D8, there actually is a separate library's API contrib module. We're not going to go into it in super detail. I just want to make sure that you guys know that it exists. And basically, it's set up to really handle external libraries that don't ship with a specific contrib module. So it's a way to reference external libraries and to be able to add them to different sites or to different modules. So it's just something to be aware of. There are a few gotchas with the library's API that I want to go through. So if a file is already linked to in a library, then if you link to that same file in a different library and that library is being added to the same page, it won't be called twice. So if you're trying to be really specific about the order in which CSS assets are being added to the page, and you have that CSS file that's linked to in two separate libraries, you lose some of that control because it's not going to be added to the page twice. So again, just something to be aware of. And then module CSS files are grouped before theme CSS files. So we have that SMAC's convention of how those CSS assets are ordered. But if you have a mymodule.libraries.yaml file, and you're linking to some CSS assets, those are going to be added to your page up above any theme CSS files. So if you have CSS assets that are under the theme SMAC's category in both a module and a theme, they're not necessarily going to be in the same place. The module CSS files are always going to be before the theme files. And then a third point here is that you will need the full doc group path if a library is already overridden. So if you're trying to override a library twice, then rather than just specifying that library naming convention, you actually have to reference the full path from the doc group. So again, you probably won't need that, but just a nice thing to put in your back pocket. And then there's a lot more information about how this all works in the Drupal 8 theming guide. So that's a good reference to check out. All right, that's about it. I have my slides available on GitHub, so you can reference this presentation later if you'd like. And we have some time for questions if anybody has any. Sure.