One very difficult task that a AEM developer can face is debugging their Client Library folders. In AEM it is possible to have a ClientLib folder where all your JS and CSS can be compiled and returned to a Web page that uses the single ClientLib file; however, you can embed other ClientLib folders as well. As a result, one ClientLib folder could have multiple JS and CSS files strewn throughout the entire AEM repository inside multiple ClientLibs that you may not even know exist. How do you deal with an error in a ClientLib file that is included on your AEM template?
Useful Tools
Two helpful tools that you can use for debugging ClientLibs are as follows: 1. http://<AEM URL>:<AEM Port><Content URL>?debugClientLibs=true example: http://localhost:4502/content/geometrixx/en/community.html?debugClientLibs=true 2. http://<AEM URL>:<AEM Port>/libs/granite/ui/content/dumplibs.html example: http://localhost:4502/libs/granite/ui/content/dumplibs.html
Tool 1: ?debugClientLibs=true
The first utility is a query string parameter that you can pass into the Web page you are authoring. For example, take a look at the Geometrixx website. Lets focus our attention on the community website on Geometrixx (/content/geometrixx/en/community). We can see there is a comment element that has its style definition in ClientLib.css. Once we locate this file we can see that the ClientLib.css file is 2402 lines.
Where is the style found for this comment component? It is in the Geometrixx ClientLib, but where in the CRX tree structure is it located?
If you retype the URL with the following query parameter, ?debugClientLibs=true (http://localhost:4502/content/geometrixx/en/community.html?debugClientLibs=true), several actions will occur. You can see that the AEM instance will return all of the individual files that all ClientLibs include inside each file. In other words, the ClientLibs will be returned in pieces instead of one file. This may take a while depending on the size of the ClientLib and the dependencies.
You will discover that there is a file called ClientLib.css?debug=true in place of where the ClientLib file use to be. Inside this file, you will find a list of all of the CSS files that are included in this ClientLib. You will also have all of the paths that the CSS files are located in. The same can be found in the ClientLib.js?debug=true.
This can be useful to find out which files are included in the ClientLib. The source tree returned from AEM will also be different. We can use this now in our example to learn that the CSS for this comment element is located in the qna.css file:
We can also learn that the qna.css file is located in the CRX repository at: /libs/social/qna/components/qnaforum/clientlibs/qna.css. We learn this by looking at the source tree returned by the AEM instance. This may be a little confusing, so I prefer to refer to the ClientLib.css?debug=true file.
Tool 2: http://<AEM URL>:<AEM Port>/libs/granite/ui/content/dumplibs.html
This utility that is built into AEM can also serve the same purpose as ?debugClientLibs=true as described above. It also gives you other advantages. You can see all the ClientLibs on the current AEM instance and what their dependencies and embeds are. This can be particularly useful if you are looking for the parent ClientLib of a particular ClientLib. The power of this overall view can also make refactoring ClientLibs useful as well. You can also see if a ClientLib contains JS, CSS or both.
One useful capability of this tool is that it also has a search feature for specific categories. Since it is possible in AEM to give multiple category names to multiple ClientLibs, searching for a specific ClientLib can become cumbersome. Using this search capability will enable you to see every ClientLib with the specified category. Note – If you are using a older version of AEM or CQ 5.6.1, the old url is: /cq/ui/content/dumplibs.html
Get Consistent and Organized ClientLibs
ClientLibs can be incredibly difficult to deal with in AEM because of the way that any ClientLib file can include another ClientLib in a completely different location. It may get even more frustrating when you are trying to maintain AEM JS and CSS that developers in the past have put in all sorts of locations. With the query parameter ?debugClientLibs=true and the /libs/granite/ui/content/dumplibs.html utility, you can manage and even organize your ClientLibs so they are consistent. It may be incredibly frustrating to know that two types of jQuery versions are being included but you can’t find out which ClientLib is the cause. With these tools, it makes hunting these issues down much easier.
Have you ever had to use these debugging tools to solve an interesting problem? Maybe you’ve used ClientLibs in an unusual way? The AEM Podcast would love to hear from you. Tweet us @Axis41 or email us at info@aempodcast.com. Don’t forget to follow our LinkedIn Adobe Experience Manager showcase page for the most up-to-date information and articles on AEM.