AEM Client Libraries

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

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.

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.

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

www.tothenew.com

Dependency Vs EmbedDependency: 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.

www.tothenew.com

Dependency Vs EmbedEmbed: 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?

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

www.tothenew.com

AEM Design & ThemeThe <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.

themedA 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

www.tothenew.com

ClientLib configuration : minificationWhen 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.

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:

• Use project and component specific name spacing for CSS selectors and JS.

• Use data attributes in components to expose component data in JS.

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.

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