Thursday, 4 December 2014

AEM Client Library in Detail

In this post, I will explain client library in detail. i.e. In this post I will explain use of different client libraries properties with the help of working example. So - 

Agenda

1). Use of categories property.
2). Use of dependencies property.
3). Use of embed property.
4). Use of channels property.
5). Use of Client Lib Debugger tool using categories.
6). Adobe CQ HTML Library Manager Service configuration.

For explaining all of these properties, I have created a project named as blog under apps directory as shown below - 
For explaining all of the above task, I have created three things. These are - 

1). I have created three client library named as dependency, embedded & main under clientlibs folder.

2). I created a page component named as clientLibInDetail. This page component will use all of the above specified client libraries.

3). I also created a template named as clientLibInDetail. This template uses the above created page component.



Let's start with the first property of client library folder i.e.




Use of Categories : 

"This property defines to which category this set of CSS & JS files belongs"
i.e. If you define multiple values for this property then this set of JS & CSS belongs to all of these defined categories & wherever you use any of these category this set of JS & CSS will be present there.

If you define only one value for this property, there is no need to make it as String[], just define it as String property. It will work fine but if you want to give multiple value for this property then just define it as String[] and add as many values as you want. In my case property set of these client libraries are - 

property for main.client client library











property for dependency client library









property for embedded client library








Use of dependency Property:

1). It is multivalued property.

2). All categories defined in this property must be in the same order in which you want to load them. i.e. if there are four client libs c1,c2,c3,c4 & you want then to be loaded in c3,c2,c1,c4 sequence then just maintain the same order in this field so that these client libraries will be load in the same manner.

3). For every dependency property value there is a individual hit to the server for loading these categories i.e. if you have four values in this property then 4 hits will be shown at debugging console network tab.

4). When you see  the source of your page using right click -> view source tab you will see same number of script tag will be generated as of values in this property. i.e for 4 values there are four script tags for these values.

Use of embed Property:

1). It is multivalued property.

2). For all embed property value there is only one hit to the server for loading these categories i.e. if you have four values in this property then only one combined hits will be shown at debugging console network tab.

3). When you see  the source of your page using right click -> view source tab you will see only one script tag for all values in this property. i.e if there are n values in this property only one script tag will be generated.

4). Using embed property means add code of all categories into one combined JS & CSS file. i.e. for 4 client libraries c1,c2,c3 & c4 only one combined JS file with the name of parent client library name is created.

NOTE : Name of final JS file will be same as parent client lib name. i.e. main.js or main.min.js (if minified) option is clicked in HTML Service.

5). All categories defined in this property must be in the same order in which you want to add them in main client library. i.e. 
if there are four client libs c1, c2, c3, c4 & you want them to be added in c3, c2, c1, c4 sequence in main client library then just maintain the same order in this field so that these client libraries will be added in the same manner. 
i.e. if you have embed property value in the given order with simple alert message. c1, c2, c3, c4 then first c1 alert will be executed then c2 alert then c3 then c4 & at the end main.client.lib JS file that embed these categories alert will be executed.

Use of channel Property:

1). It is multivalued property.
2). It is used to some additional functionality for different channels. For example : 
if you want to perform some JS functionality only for ie6 not for other browsers, or you want to add some CSS or JS for only touch UI. then this channel property comes into picture.


I will give you a demo for this property for this in my main client library just add channel property & it's values as "touch" as shown in figure - 












effect of adding this property is :- 
As I added this property to my main client library so the main.min.js or main.js will not be available for desktop system.
i.e.
I have added three alerts in these three client libs as given below -
main.js - " Main js working fine" 
dependency.js - "dependency is working fine"
embed.js - "embed is working fine"

as embed is a part of main.min.js or main.js (if not minified) so you don't get two alerts for main.js as well as for embed.js but for dependency.js, I will get an alert as it is not a part of main.min.js or main.js file.

Use Case for this property - 
If you want to achieve some functionality for touch only devices then just create two client libraries with same category name & in first client lib add common code for all channels & in second client lib use this property channels and set it's value as touch. So that for touch devices both of these client libs are loaded and you will get your desired functionality. For non touch devices only first client lib is loaded as second have this channel property it will not be available here.

I have used four values for this property ie6, extjs, touch & negation of these values.
Note: I have checked this functionality only for ie6, extjs, touch, !touch. 

AEM client lib debugger tool
AEM provides a UI for debugging a tool for identifying all the JS, CSS & themes related to a particular client lib. you can find it at - 
http://<IP-Address>:<PORT>/libs/granite/ui/content/dumplibs.test.html in my case it is -
http://localhost:4502/libs/granite/ui/content/dumplibs.test.html
when you hit this URL you will see a screen where you can enter a client lib category name and it will show you How this client library CSS & JS file will be available in different modes. As show in fig. - 























It will show which CSS files and which JS file are included in this category with there dependency file name as well as their embedded file name. Also show the channel value.

Adobe CQ HTML Library Manager Service configuration

Go to Felix console ->> Configuration tab -> search for "HTML Manager Service" yow will get a screen as - 





















All properties are self explanatory.

reference documentation - 
http://docs.adobe.com/docs/en/cq/current/developing/clientlibs.html

github repository link

Happy Coding
Namah Shivay