This is the first part of a multi-part set of posts I want to write about some things I learned while building a component in CQ 5.4. Since I struggled in a couple of areas, I am sure some of you have or will too.
In this first post, I want to cover the use of the clientlibs functionality in CQ. As you will gather from visiting the link, there is not much detail on this very useful capability. As you may or may not know, CQ renders web pages using Apache Sling. The tag line says “Bringing back the fun” … More on my take on that in a later post. Ultimately, pages are displayed by first locating content in the repository and based on the content’s resource type and selector. These resolve to scripts that actually render the content. The bottom line is that the final page that you see in your browser is made up of the output of multiple scripts that generate the HTML and associated assets.
This is where clientlibs comes in handy. Let’s say you would like to use a jQuery plugin from jQuery UI or some other plugin like Flexigrid in a custom CQ component, the key requirement is to include a combination of CSS and JS files in your page. Of course, in CQ you can edit the page templates of your site to include those libraries required for your component. But this is not best practice for a couple of reasons:
- Including client-side files in templates increases you page overhead because these files will be included in all pages wether they are needed or not;
- Your component will not be portable. If your rely on includes in the templates, then if you wanted to re-use your component on some other instance of CQ, you would have to manually touch the site templates to ensure that your component has the necessary libararies.
Clientlibs is a convenience wrapper for the com.day.cq.widget.HtmlLibraryManager service interface. This service manages the client side includes like JS and CSS to manage which files should be included in the page as well as ensuring duplicate files are not sent. Using clientlibs in CQ is really easy, once you know what to do that is :).
Here is a short tutorial to walk through what you need to do to. The example we will use, is include the jQuery UI files to leverage the dialog plugin to display a jQuery modal dialog.
I am using CRXDE to create the project.
- Create a basic component project in CQ. I am assuming you know how to do this. If not, have a look at this tutorial. I called my component myjquerysample. The project should look like this:
- Create a new cq:ClientLibraryFolder node under myjquerysample called clientlibs.
- Set the following properties on the new node:
Name Type Value dependencies String cq.jquery categories String jquerysamples
The dependencies property tell the CQ rendering engine to make sure that the jquery libraries are included in the page. CQ uses comes with jQuery libraries as they are used for built-in product features. CQ 5.4 comes with jQuery version 1.4.4. The categories property is absolutely key. We’ll see in another step that the category name will be used to tell CQ which clientlibs must be included with the html that will be generated. In fact, the cq.jquery we specified for the dependencies is a category. CQ uses categories to identify client libraries to be included.
- Select and download the jQuery UI components from jqueryui.com. Again, I assume you know how to do this. Here is a screenshot of the options that I chose. Extract the zip file you downloaded. In the extracted folder, you will find a folder named js and another css.
- Open the css folder on your file system. Since I selected Cupertino as the theme for the jQuery UI components there is a sub folder called cupertino. Open that folder to drag and drop its contents (css file and images folder) into the clientlibs node in CRXDE.
- On your file system, navigate to the js folder to drag and drop the jquery-ui-1.8.16.custom.min.js to the clientlibs node in CRXDE.
- Your clientlibs folder should now look like this
- Now we need to tell CQ which files we would like to have picked up when our component gets rendered. To do this, create two additional text files in the clientlibs folder: js.txt and css.txt.
We need to do something similar to the css.txt file. The difference, is we are pointing to the jquery-ui-1.8.16.custom.css file.
- OK, now we have everything in place in our clientlibs node. Let’s create a simple component that displays a modal dialog with a message defined by the content author. To accomplish this, we’ll first need to create a dialog node that will enable the content author to provide a string which will be the message to be displayed in the dialog.
Again, I assume you know how to do this. Here is a screenshot of my dialog tree as a reference.
- Now comes the final part, writing the script that will render the component’s content. This is where is all comes together.
There is a lot going on here. The key line in this code is the <cq:includeClientLib> JSP tag. We tell CQ to include all clientlibs folders that have been tagged as being part of the jquerysamples category. This also means that you could create shared clientlibs across multiple components.