In this blogpost I will go through the basic functionality that the ClientLibraryFolder offers, and how you can utilize that with the <cq:includeClientLib /> 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 <head>, 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 <cq:includeClientLib />
Now the components are finished we can now use the <cq:includeClientLib /> to write out the references inside the <head> 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 <head>
<cq:includeClientLib css="myproject.components" />
<cq:includeClientLib js="myproject.components" />
Note that “myproject.components” is the value of the “categories”-properties of the clientlib-node.
This results in the following HTML-output:
<link rel="stylesheet" href="/apps/mycomponents/MyThirdComponent/clientlib.css" type="text/css">
<link rel="stylesheet" href="/apps/mycomponents/MySecondComponent/clientlib.css" type="text/css">
<link rel="stylesheet" href="/apps/mycomponents/MyFirstComponent/clientlib.css" type="text/css">
<script type="text/javascript" src="/apps/mycomponents/MyThirdComponent/clientlib.js"></script>
<script type="text/javascript" src="/apps/mycomponents/MySecondComponent/clientlib.js"></script>
<script type="text/javascript" src="/apps/mycomponents/MyFirstComponent/clientlib.js"></script>
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/<project>, 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 <head> section to:
<cq:includeClientLib css="myproject.all" />
<cq:includeClientLib js="myproject.all" />
This results now in the following HTML output:
<link rel="stylesheet" href="/etc/designs/aproject/clientlib.css" type="text/css">
<script type="text/javascript" src="/etc/designs/aproject/clientlib.js"></script>
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:
<script type="text/javascript" src="/etc/clientlibs/foundation/jquery.js"></script>
<script type="text/javascript" src="/etc/designs/aproject/clientlib.js"></script>
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 <head>
A: Move the <cq:includeClientLib js=”your-category” /> to the right location in your template, you can use <cq:includeClientLib /> 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
