 Bonjour. Parle vous Anglais. I hope so. Thank you everyone for waking up early and getting out to learn about what I think is the most exciting new feature of Drupal called single directory components. My name is Mike Herschel. I work for a company based in the U.S. called Agilena. We do a lot of U.S. based federal websites. You can find me on different social medias including things like Macedon and the crap show which used to be Twitter. And I'm at Herschel.com. Notably someone who could not make it is a good friend Mateo, Mateo Bosch. So Mateo and I were kind of like the initiative leads on this but to tell you the truth he did all the work. I just said like hey this is a cool idea. Let's try to make this happen. And he did a lot but he couldn't make it here. But a lot of the credit for this goes to Lullabot that sponsored a lot of his development to go into this. And you can find him on Drupal.org, Macedon and a bunch of other cool places. I have this cool meme here. So like if I'm the skateboarder, Mateo is the guy with the plywood there that makes it easy for me to get up and do stuff on the front end of Drupal. And so I thought that was pretty cool right there. A lot of people helped with this initiative right here. Most notably Lori, Christina, Pierre, Alex Pot and Lee Rowlands. This was a team effort. A whole bunch of work went into the design of the API. We had to make sure that it worked with other systems like UI patterns and everything else that might want to extend this. So what we are going to talk about today, we're going to talk about what's the problem? Like why the heck are we even making single directory components? We're going to talk of course about how it works. I am going to do a thing called coding karaoke where I have a video of me converting a component into a single directory component and then I have to talk along with that. So please pray for me. It's very early and I might have had some wine last night. We're going to talk about how modules and themes can extend this, how it can integrate into systems like Storybook, Fractal and we'll talk about what's next and what's happening. As we get here though, I want you all to raise your hands if you are a front end developer. All right. Who here is a back end developer? Designers, marketing, anybody? No. Who here is just hanging out? A couple maybe. So the problem that you're fixing is that as a front end developer, I have been working with Drupal for a very long time but if you're coming into Drupal from a different system, things can be very, very confusing. You have a lot of questions. You have a lot of questions like how is my CSS and JavaScript being loaded and where is it coming from? When you're jumping around between say a twig file and a CSS file and maybe a JavaScript file, you constantly lose context of where you are because you're jumping between different directory structures. When you're looking at your twig file, you don't know what data is expected. Some of the core twig files have that big dock block at the top but that's not even always up to date so you don't know what's available, what's expected, etc. And just finding your template can be very difficult if you don't know how to turn on the twig debugging mode. Components make it very easy to assemble a UI, to use it kind of like on the back end of Drupal, you can put together different bricks and Legos and build together functionality but in the front end of Drupal, you haven't always been able to do this and I would argue it's still not able to do this until we get an ecosystem of single directory components. Components take as set of like a fixed set of input and then we'll apply that to the markup and it will include all of the JavaScript, any images, any styles and put everything in there and bundle it up all as one. As I said earlier, like we looked around at other systems, as we were thinking about doing components in Drupal core, we looked at other systems and we said well how are other systems using components? Do other systems use components? And what we found is that every other system uses components. Drupal wasn't here, you know, but everybody else was there. And a show of hands here, who here kind of developed their own component system using Drupal? Like by like, you know, doing a components folder, doing something like pattern lab or something like that. Does anyone done that before? I have done it and it's a little bit weird and then you also feel like you're duplicating work from other people. So with single directory components, of course, we crashed that party. We are now doing components and single directory components is the implementation of how we're doing that. While we were researching components, we looked at things like single file components, which has been a Drupal module. We looked at things like including front matter in twig, as opposed to having a YAML based metadata file. One of the big benefits of single directory components is it's very easy to find and delete it. There's a saying that I'm somehow mangling here that it's like good code is easy to delete. And as a front end developer, if you come into a code base that you did not yourself right and you want to maybe delete some CSS, you are kind of scared shitless to delete that CSS because it might break something on another part of the website. With single directory components, you don't have to worry about that. So I'm sure you all have a lot of questions on how single directory components work. I have this video, the coding karaoke video I'm going to show you. I want to talk a little bit about this, about the video before I show it and before I narrate it. I think it's about maybe 11, 12 minutes long and I go fairly quickly. I'm probably going to be pausing at some point because I'm going to lose myself at some point. The first time I converted a component, it probably took me about an hour as I was kind of figuring things out, figuring things working. You're going to see in this video, I do intentionally leave in some error messages and some troubleshooting and things like that. So as I go through really fast, just realize that I practiced this several times before I recorded it. So let me start this up right now. So this website right here is Florida Drupal Camp. You all are officially invited to Florida Drupal Camp. It's happening in February. On the schedule of the Florida Drupal Camp website, we have this schedule item component right here. The schedule item component is a details element and you expand and collapse. It has those nice contextual links and it works kind of like you would expect. So we are going to convert that into a single directory component. So to do that, the first thing we're going to do of course is disable CSS and JavaScript aggregation. You all should know how to do that. New to Drupal 10.1 is we are also going to enable twig development mode. And this is the same type of thing you can do in your settings.php and development.services.yaml. But in this case, we're doing it in the UI because that's brand new and really cool. So looking at the source code, you can kind of see what we're looking at right here. Everything is, the markup is in the no-session-teaser.html.twig. So the first thing we're going to do is we are going to enable the single directory components module. There's no configuration. You just turn on the module. Keep in mind that this module is currently experimental. When this goes in as stable decor, there's not going to be a module. It's just going to be part of the theme system. We're also going to install Drupal Core Dev via Composer. This is optional. But what it gives you is it gives you way better error messages. So when you screw up your schemas, it'll show you exactly what's going on. So this is our template where we're starting right here. This is no-session-teaser. The first thing we're going to do is we're going to create a new directory under the theme called components. And for each component, we're going to create a new directory for that. We're going to call this one details. We're creating two files to start with details.component.yaml and details.twig. These are the minimum files that you need for a single directory component. To get the component.yaml, we're just going to copy and paste from the documentation. And we're going to just start deleting stuff because this is our starting point. We're going to name this thing details. We're going to get rid of a lot of stuff we're not going to use. We're going to make a couple things required, but it doesn't necessarily need to be required. We are not going to do any library overrides. I'll explain what those are. So this is where we're kind of going. The next thing we're going to do is we're going to copy in the CSS file and the SAS file. We're going to rename those to details.css and details.sas. Now, any CSS and JavaScript that have the same name as a component will load automatically. You don't have to create a library. You don't have to attach a library. Single directory components will create that library for you. You can override that and create dependencies and stuff. And I'll show you how to do that later, but not within this right here. So after copying in the SAS file, of course, we have to like update where our SAS is pulling its variables from. So this is our starting point right here with the component with our schema. And the first thing we're doing is we're copying the HTML from the no-session-teaser into our details.twig. And we're going to align these side by side. And what we're going to do right here is we're going to start to build the schema. Schemas and themes are optional, but it's very, very useful for knowing where your data is coming from and for giving error messages. In addition to that, schemas will tell Drupal what the component is expecting. And that's useful for modules that might want to automatically create a form for this to populate the data. And we'll talk about modules that can do that later. So we're going to go on the left-hand side and we're going to look through all the different variables that are there and we're going to pull them into the right-hand side. You can see right now I copied over attributes. I don't know what type of attributes is yet. I'm going to show you how to figure that out in a bit. The next thing we're going to do is we're going to copy over classes. Classes is an array of classes, so we're going to put type array. Label is the title, so that's a string. We have two booleans in here, is non-session and is training. So we're just going to create those as props here. There's a content array, which is really, it's an associative array, so we're putting it in as an object. There's a URL, which is a string. And there's title suffix, which is an array. Title suffix is the variable that gives you those really handy contextual links. So at this point, we can, within our node-session-teaser, we remove the markup. We have a lot of the schema defined within our details.component.yaml. And what we have to do now within our node-session-teaser is we have to tell it to use this newly created component. So, of course, I'm going to document a little bit about the component.yaml file. The component.yaml file defines, of course, the schema in here. It's optional for the actual, if you have a theme. You need to have the file there, but if you don't want to define your schema and you are in a theme, you don't have to. So this is the minimal of what you need right here. This is kind of some basic stuff. You can give it a name, you can give a description, you can give it a status. The component.yaml file follows the JSON schema architecture. So you can look up JSON schema if you're a backend developer and look through their documentation. And it will show you things that you can and cannot do. When you're defining your schema, it'll look something like this. You have your props key. You tell every single key what type it is. You can see in this particular case, we're creating a new prop called mail. And we're calling it, the title of it is email. It's a string. And we're giving it a format of email. Those formats, the different formats that you can define are defined within JSON schema. A lot of this stuff obviously is not mandatory. But you can, the benefit of this is you can define this. And if it gets invalidated, then it will give you an error message. Slots are basically, it's a twig block. If you all are familiar with twig, you probably have used twig blocks. You can put in any type of string that you want in there with variables. So you define your slots separately. And you can of course make it required if you'd like. Frequently, you will want to override the automatically generated library. So as I said earlier, if you have a CS, like in our case, if we had a details.css file and details.js file, single directory components will automatically bundle those up, create the library and serve that library whenever the component is being used. But frequently, you want to maybe add a dependency on something like Drupal once or Drupal any type of other library. You can also, if you have multiple CSS files or multiple JavaScript files, you can override individual keys within that. We have an annotated example at this very, very long URL at the bottom right here. If you go into Drupal's theming guide just on Drupal.org, we added a section there called single directory components. And within there, there's five or six different pages of which the annotated example is one. So what this is, is just this big, long YAML file that you can copy and paste as you saw what I did earlier in the video. And you can just start deleting stuff, start modifying it, and there's comments all over telling you what it's doing and how it's doing that. You can override components within modules. Themes can override components within modules and themes can also override components within other themes. Modules cannot override components. When you override a component, the schema is required and you copy and paste the whole component. So like the entire thing needs to be copied and pasted and that is intentional. It might sound like a pain in the butt, but if you have a single directory component where only part of it is overridden, you don't know where all your data is coming from. If you're going to inherit some code base and you might have a component that replaces another component that replaces another component, and maybe CSS is being overridden here, CSS or the markup is being overridden here, that could get confusing very fast. So you have to fork the entire component. It gives you full control and it works everywhere. Once again only themes can do the replacement right here. So what's next with single directory components? Right now we are looking for bugs, and there are a couple of bugs that we found. And we're looking for contrib modules to start utilizing this, and there are several contrib modules that are starting to utilize this. And I can talk about those in a little bit too. We want to be experimental for at least two cycles of the Drupal core release cycle, which means that we hope to be stable for 10.3. The reason is we want people to use it. Right now as an experimental module our API could change. We're not planning on changing our API, but it might change if needed. And if so, there will be some change records and stuff like that to let everybody know. But we want to make sure that single directory components is very well supported, flexible, easy to use, and works well. Right now you as either a contrib author or project maintainer or anything like that, you can put components and modules and themes, and we want this to happen. We have several core issues open to convert some Olivero components into using single directory components. The same with the Umami theme for the demo profile and the same for Claro. And for right now single directory components is experimental. So the fact that it's experimental is going to be a blocker for getting the Claro and Olivero components in before it's stable. But with the Umami theme we can get those in beforehand. We want to have modules that expose single directory components to site builders and there's already a couple modules out there. But because the schemas are defined, assuming that you define your schemas, Drupal can build a form. Drupal can say, you know, so if you're in layout builder instead of creating maybe a block or a paragraph or something that you add into your page, it can automatically, if we could have it automatically read in the components say we need these fields, it's going to be organized this way and then just populate the data. And that type of thing is really valuable. So layout stuff like having that in layout builder would be really cool. Having it in CK editor would be really neat. Something else that we're working with is integration with storybooks. So single directory components can integrate with storybook and there's some documentation on the, on Drupal.org on how to do that. It works pretty well. Like storybooks pretty amazing. This, like if you're going to take a picture of this, here's what you have. I have my narration that completely got screwed up as the second bullet point right there. Documentation is of course at the top. There's an examples module that Matteo put together that shows you how to use it. Within the documentation there are, there's a page that say modules that use or extend single directory components. And there's a lot of cool modules like SDC display that can integrate single components, single directory components into your, into your field formatters and things like that, which is, which is really powerful. So how you can help start using it, start talking about it. If you're going to a local Drupal camp, give a presentation about it. We're very active in the components channel in Drupal Slack. So if you have questions, you can post there. You'll get an answer pretty, pretty quickly. And you can always reach out directly to me too. And yeah, so apart from the video, thank you. Do y'all have any questions? I'm sure you have questions. So yeah, so tell me your questions. Thank you, Dave. Thanks for the presentation. Just a question about the direction within Drupal core. At the moment is an experimental module. What does the module actually do as opposed to it if it was part of core and mandatory for modules to use this within Drupal core? So single directory components are never going to be mandatory. You can always, you can always still do stuff the old way by just having your no dash dash session dash dash teaser or whatever. Single directory components are only are opt in. If you use single directory components, then you have the benefits of it. And if you don't, you, if you don't utilize it, then you don't get those benefits. So the module just turns on that functionality and that functionality once it's stabilized will be available by default. But if you don't utilize it, you don't utilize it. So it won't be a module to enable or disable. It'll just be there as core functionality. Absolutely. Yeah. After it becomes stable, I guess this is much more longer term, but why would this not become the default? As to, you know, if you're no module, why would you not provide your HTML, CSS, JavaScript in this format? I mean, Drupal core probably will. But at the same time, like backwards compatibility, we don't want to break other websites either, you know. So mandatory in 11 then. No. Thanks for all the hard work, of course. Thank you. Just one question. How strict is this validation or like this typing of the props? Because if you have like a string and maybe you'll get a render array that's getting in there, or should you use slots for that? Yeah. So you know what? I wonder if this will work here. So maybe it works on YouTube. You know, I do have this video. Maybe it won't lock up. Yeah. I'd like to fast forward to the parts. So this is like when you listen to this video, it's narrated, right? So let's see where I'm going here. The question was how strict is the typing and everything like that? So if you remember early, early into process, I, I add. The, I do a composer and solve Drupal Kordev and Drupal Kordev gives us a whole bunch of really good error messages. And you can see these error messages right here where I'm trying to pass a strict Boolean, but a string was found. Hold on. Let me back up one more time. So you can see those error messages at the top and this like would be white screen of death right here. And it says string value found, but Boolean or object is required for the field. So that, that tells me as a developer exactly what the problem is. And at that point I can go in and you'll see like and coming up right in here. I end up, I fixed that and well somewhere in here. Does that answer the question? No. Yeah. So what do you like advice if you have a property that may be a render array or a string? Sorry. Yeah, yeah. Some kind of way to define like two types or type unions. So you could either, you could either use the render, the render twig filter when, when invoking the, the component within Jason schema, you can, you can define multiple optional types. I think you pass an array or something like that. I have to figure out exactly how to do. I've done it before or just use a slot. Yeah. Yeah. Hi. I've seen the SCC display module. It's a quite cool approach to integrate the component. But what about if I want to integrate the component in my template? I could do the embed and include, but it's quite cumbersome. It's like an idea for a language server which provides Emmet. So I can see, oh, that's that component and the component expects this props. Currently, I would have to open the schema and look at the component, but would be awesome if my editor tells me what the component expects. Is there any idea about that? So material created this CLDevelop module. Let me make sure I understand the, the. So basically, if you work in TypeScript, for example, you type array dot and the editor tells you what you can do. So what would be cool if I could do embed component details and the editor tells me, oh, it needs a header and a summary and all the stuff. Yeah. Oh, gotcha. That, that would be actually pretty cool. Yeah. Yeah, I don't know if there's been any work on that or anything like that, but I would like, like if I were you, I would, I would ask that in the components channel and see if anyone's been working on anything like that. And, and see what happens. All right, thank you. First of all, thank you for the presentation. My question is how do you control like the markup of the component? I can imagine the component being a paragraph, for instance. And so how do I control the exact markup I want or I need within this? So the markup is defined within the component dot, your component dot twig file. Is that what you're asking? Yes. So there is a twig file that always goes with the schema. Yeah. So as you define your, let me see if I can come up with, I don't know if I have anything. This is, this is a USWDS based theme that we have here. So, so within your, within your component file, you'll have a minimum of a component dot YAML file and then, and then your components twig file. And your twig file is how you control that markup. Optional to those you can add in, of course, the CSS file and the JavaScript file. And if they have the same name of the, as the component name, they'll automatically be bundled into a library and served with it. Does that answer the question? Yes. And how is that kind of a better approach than the components module where you can actually. Well, the components module, all it does is twig namespaces. So like, like, let's say like your components modules is frequently used with atomic design where you define like your atoms, your, your molecules and things like that. The benefit of a single directory component is that it bundles all your CSS and your JavaScript and defines the schema of the component all together with the markup. All the components module does is just say like you can, you know, add like what, like at molecules or something and then the twig file. Thank you. You're welcome. I think we have time for one more. Thanks. That's really great to see. And I think this could be a huge change in how we think about theming in modules. I just wondered an apologies. I came in a little bit late, but if you talked about kind of how this fits with the wider thing around like native web components and being able to, you know, like any, like any JavaScript or whatever can define their own web components in the road, like the shoes, the shadow DOM and things like that. So if you, if you talked a little bit about kind of how, how you see those fitting in with single directory components or if they're, if they'll just work natively and you don't have to do anything about it because you just define them in the twig template in JavaScript or if you've got any thoughts on that, that would be good. Yeah, it's, it's based, it works basically like you would, like you would hope it to work. So if you're, so if you're defining like a web component, obviously you have a little bit of markup which might be a custom element or something like that. And at that point you have all your, all your JavaScript. You could easily bundle that into a, into a single directory component would work as expected. And the same thing goes if you're using other, other technologies such as like react view or whatever the heck you want, like single directory components can easily integrate in with all that. You're welcome. So Mike, if they have more questions or if they want to help, where do they go? That's a really good question, Dave. Thank you for asking. I would, I would start with the components channel and Drupal Slack. If you're not in Drupal Slack, you need to be there. And beyond that, there is a lot of documentation that we have spent a good, a good amount of time working on. So documentation is fairly good for Drupal standards. And there's a lot of, a lot of discussion happening in components. And yeah, so thank you.