Client Library in AEM

 

Client Library in AEM

 

The AEM Client Library man­ages all your JavaScript and CSS resources in the appli­ca­tion. It takes cares of depen­den­cy man­age­ment, merg­ing files and mini­fy­ing con­tent (remov­ing unnec­es­sary white spaces).

 

Adobe now recommends to create clientlibrary node for every individual component, that creates a separation of component from each others.

 

In above screenshot, we have 3 components and every component have their own clientlib node.

 

For that we have to add a “clientlib” node of type “cq:ClientLibraryFolder” under /apps/<site-name>/components/<component-name>/

 

Properties for clientlib node:

 

1.    cat­e­gories (String[]) with the sin­gle val­ue as “myproject.components” (to get a String array type click the “Mul­ti” but­ton). It should be unique value.

 

2.    allow­Proxy (Boolean) with value as true. This will make the clientlibs avail­able via the url /etc.clientlibs/, so it means they are not hav­ing the /apps ref­er­ence.

 

3.    embed (String[]) To merge the sev­er­al clientlib files into one, we define a clientlibs that is embed­ding the oth­er cat­e­gories.

 

Note: Embed property is NOT transitive – If Clientlib A embed B and B embed C, then only A and B will be included in the page,but C won't. In order to include Clientlib C, it must be added to the embed property of A as well.

 

4.    dependencies (String[]) There is a list of other client-side libraries on which the library folder depends.

 

Note: Dependencies property is transitive – if Clientlib A depends on B and B depends on C, then all clientlibs will be included in the page in the order of C>B>A.

 

Adding JavaScript and CSS resources

 

Create 2 folders and 2 files under clientlib node:

1)   Js (folder)

2)   Css (folder)

3)   js.txt

4)   css.txt

We need to create folders only if we have multiple css and js files else we can directly create 4 files as follows:

 Things to notice about Child nodes js.txt and css.txt

·         Place each file name inside js.txt or css.txt on separate line.

·         The first line should start with #base = [root], this refers to the path of folder that contains source file relative to text file. For example, #base=js(folder name).

·         If there are no folders, then directly give file name of .js and .css or simply, #base=.

·         We can skip either of the js.txt or css.txt file, if your clientlib only contains resources of one type only.

·         If we don’t add text files to client library folder then AEM won’t treat it as client library folder, because inside client library folder it looks for txt files to understand what are files it need to include in our component.

 

·         Note: We can use ?debugClientLibs=true to load all js and css files separately without concatanation

Calling Client Library in component:

 

If we are using a JSP we can use cq:includeClientlib.

But now as we are using the HTML Tem­plate Lan­guage (HTL), we can use the <data-sly-call> to invoke the ClientLib as follows:

<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html" />

<sly data-sly-call="${clientlib.css @ categories='myproject.components'}" />

<sly data-sly-call="${clientlib.js @ categories='myproject.components'}" />

                       Or

<sly data-sly-call="${clientlib.all @ categories='myproject.components'}" />

Note:

1)    The val­ue of the “cat­e­gories” prop­er­ties of the “clientlib” nodes are “myproject.components”, which is what we need to pro­vide above.

 

2)    “clientlib.all” calls both js and css.

 

Drawbacks of using above mentioned approach

Now, as we know we have multiple clientlib folder but the categories value is same for all i.e. myproject.components.

Problem: Server will make multiple serv­er calls to fetch the resources.

Solution: Use “embed” property to merge the sev­er­al clientlib files into one, we define a clientlibs that is embed­ding the oth­er cat­e­gories. Exam­ple here tak­en from /app­s/w­ere­tail/­clientlib­s/­clientlib-base.

Another solution is to add to “depen­den­cies” property, this way we can define depen­den­cies between ClientLibs.

For example adding a depen­den­cy on “cq.jquery”:

 

Minify and Gzip

To deliv­er a bet­ter per­for­mance we can enable “Mini­fy” and “Gzip” for the “Adobe Gran­ite HTML Library Man­ag­er”, in the Felix Con­fig­u­ra­tion con­sole (http://server/system/console/configMgr).

 

Q: Where are the gen­er­at­ed files stored in AEM?

A: They are stored in /var/clientlibs

Q: Is there a con­sole so I can see the depen­den­cies?

A: look at this page http://server/libs/cq/ui/content/dumplibs.html

Q: Can I rebuild the ClientLibs?

A: Via, this url: /libs/granite/ui/content/dumplibs.rebuild.html