Archive for November, 2011

Building Components in Adobe CQ5 – Part 2: A tutorial on jQuery, AJAX and Sling

In this second part of my series on CQ5 and jQuery, we are going to look at how to implement a jQuery plugin that uses AJAX to retrieve data from CQ5. I picked the jQuery Flexigrid plugin as the target for this tutorial. The sample that we will build is to retrieve a list of users from CQ5 and display that list in the grid component. Although this is use case is meant for an administrative type of task (we would not display a list of registered users to just anyone), I picked this scenario because it will show us how to execute a callback to a JSP in CQ to retrieve JSON formatted data. Since the default Sling servlet in CQ5 can be used to retrieve content in JSON format for pretty much anything, I wanted to chose a fringe use case where we would not use the default Sling servlet and provide our own request handler so we can understand the complete workflow involved.

This tutorial builds on the first part of this series. We are going to create a new component in our /app/samples tree and re-use the clientlibs approach to include the required Flexigrid client files. We’ll then create a component JSP that will render the Flexigrid plugin. Once the grid is displayed, it will make a callback to the server to fetch the data to be displayed. This will be the focus of this post – showing how to configure and handle the call back through Sling and return the result of a CQ5 API call (get all users) in JSON back to the grid to be displayed. Continue reading…

How to change the default authenticator in CQ5

 

,,

While working with a colleague a few weeks ago, we ran into an interesting challenge with the site he was buillding in CQ5. This new site required a login page that needed to match a specific style. What we kept seeing the default Geometrixx-styled authenticator would be displayed. Now, we could have used our css file to override the look of the default authenticator. But we needed to add additional elements to the authentication page and wanted to manage the changes within the /app tree.

After some digging, I found that the authenticator hendler setting is not where I expected it to be (as part of the JCR properties of the site), it’s a sling:OsgiConfig propery located within the /libs tree. The full path is:

/libs/cq/security/config.publish/com.day.cq.impl.LoginSelectorHandler

Continue reading…

Building Components in Adobe CQ 5 – Part 1: A tutorial on clientlibs using jQuery UI

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:

  1. 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;
  2. 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.

  1. 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:
  2. Create a new cq:ClientLibraryFolder node under myjquerysample called clientlibs.
  3. 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.

  4. 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.
  5. 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.
  6.  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.
  7. Your clientlibs folder should now look like this
  8. 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.
    The contents of the js.txt file (I am sure you have guessed already) is the filename(s) of javascript files you would like to include with your component. In our case, we need to reference the jquery-ui-1.8.16.custom.min.js.
    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.
  9. 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.
  10. Now comes the final part, writing the script that will render the component’s content. This is where is all comes together.
    <%--
    My jQuery Sample Component component.
    Author: Marcel Boucher]
    --%>
    
    <%@include file="/libs/foundation/global.jsp"%>
    <%@page session="false" %>
    
    <%
    // Retrieve the configuration property if set by author.
    final String message = properties.get("message", "Default message for dialog.");
    %>
    
    <cq:includeClientLib categories="jquerysamples" />
    
    <script type="text/javascript">
    // This function is called on page ready. It bootstraps the div tag with the jQuery UI dialog class.
    jQuery(function ($) {
    $( "#dialog-message" ).dialog({
    modal: true,
    autoOpen: false,
    buttons: {
    Ok: function() {
    $( this ).dialog( "close" );
    }
    }
    });
    });
    
    // This function actually displays the dialog sets the title and body.
    function showDialog() {
    jQuery( "#dialog-message" ).dialog( "option", "title", 'My Sample jQuery UI Dialog' );
    jQuery("#dialog-message p").html("<%= message %>");
    jQuery("#dialog-message").dialog("open");
    }
    
    </script>
    
    <button id="btnShowMessage" onclick="showDialog()">Show jQuery dialog</button>
    
    <!-- Placeholder for the jQuery UI Dialog plugin -->
    <div id="dialog-message" title="My Sample Dialog">
    <p>Default message content.</p>
    </div>
    

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.

,,,