CQ5 Clientlib explained by example

In this blogpost I will go through the basic functionality that the ClientLibraryFolder offers, and how you can utilize that with the tag.
The “clientlib” functionality will manage all your Javascript and CSS resources in your application. It takes cares of dependency management, merging files and minifying content.

The following application scenario will be explained :
- multiple components with their own Javascript and CSS files
- global Javascript and CSS files
- /apps folder is not available via the dispatcher (recommended)
- CSS resources have to go in the , Javascript resources at the end of the page
- Resources need to be minified
- Some resources need to be merged

Let’s get started!

Step 1: Creating components and clientlib nodes

First we make a few components, in this example 3 components are used.

Next we are going to add a “clientlib” node of type cq:ClientLibraryFolder, inside this node the Javascript and CSS resources are stored.

Add a property to every clientlib-node called “categories” of type String[] with the single value of “myproject.components”. (To get a String[] type click the Multi button ).

Your components-folder will look now like this:

Step 2: Adding Javascript and CSS resources

Now we are going to add some simple Javascript and CSS resources in the clientlib-node.

CSS (first.css):
.firstContainer {
margin-top:10px;
}

Javascript (first.js):
/*
* This is the comment of the function
*/
function getNameFirst() {
// return the name
return "some value";}

js.txt
This mentions all the Javascript resources of the clientlib, in this case one line :

first.js

css.txt
Same as for js.txt, but then for all the CSS resources, so also one line:

first.css

Your components folder will now look like this:

The configuration of the components are now finished.

Step 3: Using

Now the components are finished we can now use the to write out the references inside the of our template. You can also choose to write out certain references in other places in the page, for example some Javascript at the end of the page.

We start with putting the following into the

Note that “myproject.components” is the value of the “categories”-properties of the clientlib-node.

This results in the following HTML-output:

This has a few downsides:
- The resources are retrieved from /apps
- 6 server calls have to be made to fetch the resources
- Application structure is exposed
Step 4: redirecting resources via /etc/designs and merging into single files

What we want is that the user gets the resources from /etc/designs/, so that /apps can be closed for the production configuration. And on top of that we want that the resources will be merged into a single .js/.css reference.

Create a new folder “aproject” in /etc/designs, then create the structure as shown below. The js.txt and css.txt should be empty files.

The clientlib-node has the following properties:

With the embed-property it embeds all the resources of “myproject.components”

Now change the attributes in the section to:

This results now in the following HTML output:

If you open these files you will see that the three js/css resources are merged into one file. And although the resources are located in the /apps-folder all references are now done via the /etc/designs folder.

Step 5: Dependencies

Another property you can add to the clientlib-node is “dependencies”, this way you can define depedencies between clientlibs.

Let’s add a dependency on cq.jquery:

When you now reload the page the dependency is written:

Step 6: Minify and Gzip

To deliver a better performance you can enable “Minify” and “Gzip” for the “Day CQ HTML Library Manager” in the Felix Configuration console (http://server/system/console/configMgr). These settings are recommended for production installations.

When you now look at this resource “/etc/designs/aproject/clientlib.js”, it results in this:

function getNameThird(){return"some value"
}function getNameSecond(){return"some value"
}function getNameFirst(){return"some value"
};

So all comments and spacing are removed to save download-time.

FAQ

Q: I don’t want to have all my Javascript references in the
A: Move the to the right location in your template, you can use multiple times

Q: Where are the generated files stored in CQ?
A: They are in /var/clientlibs

Q: When developing I want to have single file references in my HTML
A: Enable the debug-option in the HTML Library Manager

Q: Is there a console so I can see the depedencies?
A: Yes, look at this page http://server/libs/cq/ui/content/dumplibs.html

Q: Are there debugging options available?
A: Yes, ?debugClientLibs=true writes out single files
A: Yes, ?debugClientLibs=true and CTRL+SHIFT+U gives you timing info

Feike Visser (@heervisscher) is an experienced consultant working in the EMEA-region. Feike has done live implementations at large enterprises like NATO, BBC, Philips, Deutsche Bank, HMRC, HSBC.

View the original article here