On the clientlib node, there are several things to notice:
- jcr:primaryType – The “clientlibs_desktop” node must be of type cq:ClientLibraryFolder.
- categories – Value of this field is a String array. It is used to categorize the clientlibs. You could use an existing name here, meaning that when that particular clientlib is requested, your clientlib code would also be send in the response. You could use an altogether new name here as well, if you so desire.
- dependencies – This is used to specify if your client-lib is dependent on some other client-lib
- embed – It may happen that you would like to combine the output of some other clientlib in your clientlib. Then you should use “embed” instead of “dependencies”. This would bring the contents of the embedded clientlib in the same request.
As for child nodes
- css.txt – lists down the css or less files
You could even skip one of the js.txt or css.txt file if your clientlib only contains resources of one type only as in the above example.
Tips & Tricks
- Take a Dump !
A content management system like AEM, may typically include a lot of clientlibs of a single page for analytics, for various authoring features ( inline content editing, drag & drop support etc ). And hence sometimes it is useful to know more about the different clientlibs which are loaded on a page. An easier way is to take a dump of all the clientlibs in the system by navigating to the URL : http://localhost:4502/libs/granite/ui/content/dumplibs.html. The output of this page list down all the clientlibs ( including the ones provided by CQ by default ). You could search the clientlib you are interested in & drill down to see more details about it.
- Debug My Clientlibs
There is also a second way to handle this – You could append the ?debugClientLibs=true parameter on the page URL and the server would not concatenate these files instead serve all the JS/CSS separately. Though I’m not a big fan of this approach and it generally makes the rendering of the page slow ( typically due to a large number of HTTP requests )
- Configuring Day CQ HTML Client Library Manager
The OSGi Component that watches for any changes in your clientlibs, invalidates the older clientlibs and generates the new clientlibs from the given code is “Day CQ HTML Client Library Manager“. And as with any other configurable OSGI component, one can tweak certain important configurations for this one using the Sling Console. Go to http://localhost:4502/system/console/configMgr and search for “HTML Library Manager”
- Removing Cached Clientlibs
The clientlibs are generated and cached by CQ at /var/clientlibs. If you wish to clear the cache then one way is to navigate to the particular clientlib node under /var/clientlibs and delete the particular generated css/js files. Another and more cleaner option would be to use http://localhost:4502/libs/granite/ui/content/dumplibs.rebuild.html You could invalidate the caches and rebuild all the clientlibs or do both of them to get a more consistent view of your clientlibs
- Error in Generating Clientlibs
Sometimes it may happen that due to some error in your JS or CSS/LESS code, the Library Manager is unable to generate the clientlib. In such a case, an exception is normally logged in error.log which can give some hints about the possible developer mistake. To get a more detailed view about the error, one could create a new Logger configuration by going to Sling console and specify “com.day.cq.widget.impl.*” in the Logger field, as shown in the image below:
In a nutshell, clientlib functionality in AEM is a really useful one and is used to organize client-side resources in a modular and re-usable manner.