This document discusses client-side libraries in AEM and best practices for their use. It explains that clientlibs allow logical organization of JavaScript and CSS files and avoid duplicate includes. Key points covered include using cq:ClientLibraryFolders to define libraries, including them via cq:includeClientLib, dependencies vs embedding, debugging tools, themes, and minification. Best practices include placing component code in clientlibs, embedding to reduce requests, requesting from /etc, defining dependencies, and minification on publish.

1. AEM Client
Libraries

2. www.tothenew.com
Agenda
• What is clientlib & Why do we need it?
• Pre-requisite for AEM ClientLib
• How Client-Side libraries works in AEM?
• Dependency Vs Embed
• Debugging Tools
• AEM Design & Theme
• ClientLib configuration : minification
• Best Practices for ClientLib

3. www.tothenew.com
What is clientlib & Why do we need it?
• Modern websites rely heavily on client-side processing driven by complex JavaScript and CSS code.
Organizing and optimizing the serving of this code can be a complicated issue.
• Standard Way of including Client Library (JS/CSS):
<script type="text/javascript" src="../jquery/source/1.8.1/jquery-1.8.1.js"></script>
While this approach works in AEM, there is the danger that multiple copies of the same JS library may be
included in the final HTML output.
• To avoid this and to allow logical organization of client-side libraries AEM uses client-side library folders.

4. www.tothenew.com
Pre-requisite for AEM ClientLib
• A client-side library folder is a repository node of type cq:ClientLibraryFolder, placed anywhere within the
/apps, /libs and /etc
[cq:ClientLibraryFolder] > sling:Folder
- dependencies (string) multiple
- categories (string) multiple
- embed (string) multiple
• categories: Identifies the categories into which the set of JS and/or CSS files within this cq:ClientLibraryFolder fall.
The categories property, being multi-valued, allows a library folder to be part of more than one category.
• dependencies: This is a list of other client library categories on which this library folder depends. For example, given
two cq:ClientLibraryFolder nodes F and G, if a file in F requires another file in G in order to function properly, then at
least one of the categories of G should be among the dependencies of F.
• embed: Used to embed code from other libraries. If node F embeds nodes G and H, the resulting HTML will be a
concentration of content from nodes G and H.

5. www.tothenew.com
How Client-side Libraries works in AEM?
• Add a cq:includeClientLib tag to your JSP code to add a link to client libraries in the generated HTML page. To
reference the libraries, you use the value of the categories property of the cq:ClientLibrary node.
<cq:includeClientLib categories="cq.jquery"/> // To include both CSS and JS libraries
<cq:includeClientLib js="cq.jquery"/>
<cq:includeClientLib css="cq.jquery"/>
The generated HTML page contains the following code:
<script type="text/javascript"
src="/etc/clientlibs/foundation/cq.jquery.js"></script>
• The node contains :
– One or more source files that, at runtime, are merged into a single JS and/or CSS file. The name of the generated file is the node
name with either the .js or .css file name extension. For example, cq.jquery.js or cq.jquery.css.
– Resources that support CSS styles, such as image files.
– One js.txt file and/or one css.txt file that identifies the source files to merge in the generated JS and/or CSS files.
• #base=[root] , where [root] is the name of the root folder where all scripts are present, like ., js, css.
• The web client must have permissions to access the cq:ClientLibraryFolder node. Generally, you locate the node
below /etc/clientlibs in the repository

6. www.tothenew.com
Dependency Vs Embed
Dependency: When the code in your client library folder references other libraries.
• In the JSP, the cq:includeClientLib causes the HTML code to include a link to your generated library file as
well as the dependencies.
<script src="/etc/clientlibs/foundation/cq.jquery.js" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js" type="text/javascript">
• The dependencies must be another cq:ClientLibraryFolder. To identify dependencies, add a property to your
cq:ClientLibraryFolder node with the following attributes:
– Name: dependencies
– Type: String[]
– Values: The value of the categories property of the cq:ClientLibraryFolder node that the current library folder depends
on.
• Disadvantage: A new request is made to the server for every dependency.

7. www.tothenew.com
Dependency Vs Embed
Embed: You can embed code from a client library into another client library.
• At runtime, the generated JS and CSS files of the embedding library includes the code of the embedded
library.
• Embedding code is useful for providing access to libraries that are stored in secured areas of the repository.
• App-specific client library folders:
It is a best practice to keep all application-related files in their application folder below /app.
It is also a best practice to deny access for web site visitors to the /app folder.
To satisfy both best practices, create a client library folder below the/etc folder that embeds the client library
that is below /app.
• Using embedding helps to minimize requests
Q: How many requests are made when you embed a clientLib which itself has one dependency?

8. www.tothenew.com
Debugging Tools
• To trace the origin of embedded code :
?debugClientLibs=true
• Discover client libraries :
libs/granite/ui/content/dumplibs.test.html
• Rebuild clientlibs :
libs/granite/ui/content/dumplibs.rebuild.html

9. www.tothenew.com
AEM Design & Theme
The <cq:includeClientLib> tag Includes a AEM html client library, which can be a js, a css or a theme library
theme:
A list of comma-separated client lib categories. This will include all theme related libraries (both CSS and JS) for the
given categories.
themed
A flag that indicates of only themed or non-themed libraries should be included. If omitted, both sets are included.
geometrixx-clientlibs
themes
myTheme (clientLibray)
css.txt
myCss.css
js.txt
myJS.js

10. www.tothenew.com
ClientLib configuration : minification
When it comes to the production environment, page load performance is of the utmost importance. The more files
that need to be fetched and the greater their size, the longer it will take for the page to be loaded.
AEM can deliver enhanced performance by enabling Minify in the Day CQ HTML Library Manager of the Felix
Configuration console.
• Minify compresses JS and CSS using the YUI compressor, removing all comments and whitespace.

11. www.tothenew.com
Best Practices for clientLib
• Place component JS and CSS in a clientlib located in the component folder - /apps/sample-
component/clientlibs.
• Embed component clientlibs into a single clientlib to reduce requests.
• Request all clientlibs from /etc, avoid pointing to apps.
• Use the dependencies property of a clientlib to define dependencies between libraries.
• Do minification of client libraries on the publish instance.
• Don’t include JS & CSS directly at the component unless it is very important.
JS & CSS CODING GUIDELINES:

12. www.tothenew.com
Assignments
• Problem-1
– Create a component with a dialog and having color drop down (green, blue, black
etc) and one rich text editor for authoring text.
– This component is supposed to render text and apply chosen color to text.
• Problem-2
– Create two designs which will have different text color & background theme.
– Apply both of them in different pages.
– The component text & background color should reflect based on the design
applied.

13. www.tothenew.com
References
• https://docs.adobe.com/docs/en/cq/5-6-1/developing/clientlibs.html
• https://docs.adobe.com/docs/en/aem/6-0/develop/mobile/responsive.html
• https://docs.adobe.com/docs/en/aem/6-1/develop/the-basics/clientlibs.html