ClientLibs: CQ Static Resource Management

In this post, I am going to cover a feature that is provided in CQ to manage static resources (js, css, images, etc.). For every web, application performance is an important factor that we usually ignore in the first place and down the line, it becomes a bottleneck for us. So, performance can be improved by considering various factors while designing a new application, few of them are listed below:

1) Web page size
A web page is composed of HTML markup, JS files, CSS files and images. We should try to keep page size as low as possible so that the page is loaded quickly in the browser.

2) Ajax calls v/s full page to reload
There are many instances where it’s always better to make an Ajax call to hit the server and update a small area (HTML DOM) of the page rather than reloading the whole page.

3) Amount of data transfer between server and browser
When we make a call to service on the server, the services should only return page/context-specific data rather than returning whole information/data. We can call the server again (via Ajax calls) to fetch limited data and update the page accordingly.

In this post, I’ll try to show the benefit of using the client libs feature to reduce the page size. Let’s consider a scenario where we have a web application built using CQ and it has multiple pages that are composed of many components. Each component needs a set of JS, CSS, and images that might not be needed on other pages so, it does not make sense to load all those irrelevant resources on other pages where that component is not present.

For example, we have a login page and a home page that the user sees after successful login. The login page is composed of a login component (with a form) to enter username and password and we are using a jQuery validation plugin to validate the form before submitting it to the server. Once the user is validated we redirect the user to the home page which does not have any form (i.e. we don’t need validation jQuery plugin) on this page and there is no point in including validation plugin and we only need jQuery javascript file.

Login Page: needs jQuery and jQuery Validation plugin
Home Page: needs just jQuery

Normally, we include resources (like JS, CSS) in the section of a page (in CQ it’s a template). If jQuery and jQuery validation plugin are included in the head section of template then it’ll be included on every page no matters whether that page actually needs them or not and hence the page size is increased unnecessarily. There is a better way to handle this in CQ and load the resources when they are actually needed and this is where CQ’s clientlib feature comes in to play.

What is the client lib feature?
With the client lib feature, we can categorize every JS and CSS file as a library (with a specific name) and can include/import them in individual components or templates (if it is used globally). For the time being consider this as java import feature. If on a page there are multiple components that need the same library then CQ will make sure that the library is loaded only once. We can also define dependencies while creating clientlibs, e.g. jQuery validation plugin is dependent on base jQuery JS file.

How to define a client lib in CQ?

To define a client lib CQ follow below steps:

1) create a folder called clientlibs (by right-clicking on designs folder) under /etc/designs (actually we can create this folder anywhere we want but, to keep it simple and consistent I am creating this under designs folder)

2) Create a new node under clientlibs folder called as jqvalidate with type as cq:ClientLibraryFolder (as shown below):


3) Copy/Put your JS (jq.validate-min-XXX.js) file in jqvalidate folder (we can also copy and css file to this folder if there is any).

4) Create a file js.txt in jqvalidate folder (also create another file css.txt if you have copied any css file in jqvalidate folder).

5) Add name of JS file (e.g. jq.validate-min-XXX.js) in js.txt (also add name of CSS file in css.txt) file and save it.


6) Click on jqvalidate folder node in crxde and open the Properties tab and update/add 2 new properties as shown below and save the node:
NOTE: both properties are of type String Array (String[])
a) categories: This is the name using which we’ll be referencing our jQuery validation client lib in our components and templates.
b) dependencies: Using this property we define the dependency of current library (in this case jQuery validation) on another client lib (in this case cq.jquery).


At this point we are done with creation of a validation library now, we’ll see how to use for developing components and templates.

How to use/import client lib?
To include a client lib in your component/template simply add following code/tag:

If you want to load multiple client libs then provide comma-separated names against categories attribute in above tag e.g.