I know, I know...I was meant to be back in September...and yet, so much water has ran under that bridge. I won't give you explanations on how busy I've been, I will just continue with this educational series on AEM and frontend.
If you got here from google or another link, I advise you read the series from the beginning. In this post, we will learn what clientlibs are.
Clientlibs is short for client-side libraries, the pattern used in AEM to manage and ship frontend code to the browser. To better understand it, you should start by reading the official documentation
As you can see, the important part is that you have declared that node to be of
The other important thing is that you should assign it to a category, like this:
I know you're wondering why it is categories and not ONE category, and why it accepts an array, instead of a single definition. This is because, in essence, you're not giving a name to it, but declaring it as part of a category of name [the.category.name.you.wish]. And you can assign the code in your clientlib, to multiple categories.
Good question. You should follow a certain convention, but that convention is open. I could suggest you form your category by concatenating the path in your folder structure, including your project-id. If you do that, you can reproduce category conventions across many projects, and even create cross dependencies without issues.
There are other very important properties to clientlibs.
- dependencies (string) multiple
- embed (string) multiple
- allowProxy (boolean)
and you can see them being used, in this gist.
Now let's explain them
Like with categories, it takes an array of strings, defining the name of other categories that should be loaded, before yours. There is a mechanism in the backend (in the background) that will make sure those categories, with all the code they have, are loaded before this one.
You can also embed scripts that are necessary for your clientlibs to work. Unlike dependencies, which trigger an independent request, embedded code is concatenated or aggregated in the same file.
You have to be careful with embeds having dependencies of their own, because clientlibs embeds are transitive. This means that, if you embed a clientlib category that by extension has a declared dependency, that dependency WON'T BE LOADED.
Allow proxy is a boolean that makes a category located at the apps/ folder (which is private) made public when hitting
via a proxy servlet. Basically, if you don't set it to true, and your code is under apps/, your public site will not be able to download it.
Now you know how to create a clientlibs folder, you will want to define what code that category is including. For that, you need to import it to using the .txt files.
However, let's suppose the bundle was in a different directory. In order to include it, you need to define the base and import it.
Now, this is the more 'on a per case basis' method. In my current project, we have a very complex mechanism under the hood. A sling model that basically will, via a template, request the category associated with the component name (since we have conventionally defined all categories are formed from the folder path to the components).
But you can do it manually too, for example, like this (I added all examples to a single gist for the sake of brevity).
And that's it! That will basically include the '< script >' tag with the right src= for js, and the '< link rel... >', for the CSS! And you can do it anywhere on your page!
If you're requesting your clientlibs per component, you should make sure you're not duplicating requests. You should have a debouncing mechanism or potentially a good check in the backend, to make sure not to exhaust your performance with multiple requests to a single item!
Now you know all the basic things about clientlibs you should know, to work as a frontend developer with AEM. See you in the next post!