Creating cq5 component with a dialog

The steps in this tutorial will require knowledge of creating a component in cq5.

Let us create a Blog post component. The component will enable the content authors to insert a blog post onto a page. The blog will have three parts viz title, short description, and blog body.

step 1: In CRXDE lite navigate to apps/yourproject/components folder. Right-click on the component folder and create a component with the label blogPost.

step 2: Right-click on the component and select create dialog option. Give the name and title as dialog and dialog. This convention of naming its dialog is essential for it to work.

On clicking OK of the pop-up a preliminary structure for the dialog is created. The structure created is a tree structure of nodes
dialog(primary type:: cq:dialog)
| items (primary type::cq:widget)
| items(primarytype::cq:widgetCollection) | tab1(primary type::cq:panel)

The interface in cq5 is created using the Extjs framework. The above tree structure tells the cq5 program what kind of dialog you want. The cq:dialog node is the dialog's outer container. The widget is what the dialog will display. It's for us to customize what kind of widget our dialog has to display. A widget can be made up of multiple widgets put together. For this, the widgets are held in widget collection. The outer widget holds the widget collection. Its easier to understand the concept when you see them as containers. Check out the figure below

The above figure shows us the logical structure of a cq5 component dialog. The red rectangles are the actual input fields. Grey rectangles are the structure for tabs. Black rectangles are the structure for dialogs. All the rectangles are containers except for the red ones. From this information, cq5 will create an extjs script that pops up the dialog when the content authors double click on our component. By tweaking what container holds what widget we can tweak the way the authoring interface looks.

The cq:panel node creates a tab. A dialog can have multiple tabs. We can use these tabs to group data that the author will have to configure. The tab will again display widget or multiple widgets. The widgets could be text fields, text boxes, rich text editors, etc.

Let's create two tabs for our dialog. The first will have a text field for title and text box for description. The second will have a rich text editor for the author to enter rich formatted text.

Step 3: On tab1 node right-click and select create a node. Enter items as the name and select "cq:widgetCollection" from the drop-down for the node type. The naming convention again is important, the name of the widget collection node has to be "items". Before going to the next step click on the tab node, you'll be able to see the properties of the node in the bottom section of the crxde lite window(check out this link for an overview of crxde lite interface). Add a property to the node to give the tab a title. Enter the name as the title. Select-String as the type from the list. Enter "Blog Post Details" as the value and hit add.

Step 4: Right-click on items node under tab1 and create a new node of type cq:widget.

Step 5: Add the following properties to the node created above.

1. name:name, type:String, value:./title
2. name:xtype, type:String, value:textfield
3. name:fieldLabel, type:String, value:Title
4. name:fieldDescription, type:String, value:Enter title for blog post. 

The purpose of the properties added in step 5 are explained below

• the name property is the name(location to be precise) of the property(or node depending on the value) to be created under the components node(this node will hold value content authors entered). "./" is replaced by the current path (which will be the path to components node). Thus "./title" will create a property called title on the components node. If you specify the value of name as "./title/theValue" it would create a node called title under your components node and the value authors gave as input would be stored as theValue property on the title node.
• xtype will tell what type of input field it is. Its sort of similar to the type attribute of the HTML input tag.CQ5 has a long list of xtypes, check out this link for more details. Textfield in the above step will create a text field as the name suggests. Cq5 allows a lot of configurations to fine-tune your interface. To use the config options just add them as properties to the node created in the above step. The config options for textfield xtype can be found at this link.
• The field label is the label for your input field
• fieldDescription is the description of what value has to be entered in the input field 

Step 6: Repeat steps 4 and 5 with the following values
xtype: textarea
name: ./description
fieldLabel: description
fieldDescription: Enter a short description of the blog post

Step 7: Create a tab by creating a node tab2 of type cq:panel parallel to the tab1 node(tab1 and tab2 will be children of the widgetCollection node). Give tab2 the title "Blog Body"

Step 8: Create a widget in tab2 of xtype richtext with name ./blogText.
Now we have our dialog ready, all we need to do now is write code to display whatever will be entered by the author in the dialog.

CQ5 has a built-in feature that lets you edit dialogs in WYSWYG fashion. To use it all you have to do is double click on the dialog node. For more check out http://dev.day.com/docs/en/cq/current/developing/developmenttools/dialog_editor.html.

Now that we have our dialog ready let's see how the data can be fetched in our jsp and displayed.

The data configured by the author are stored as properties of a node. Since cq5 is built on sling it treats everything as content and content has a resource. So instead of using the node, we can use the resource to fetch the property. The properties are stored as a value map. We'll have to fetch the property from the value map.

CQ5 exposes the valueMap of the components' resource as "properties" object (it is done in one of the files included in global.jsp . Make it a point to include global.jsp in every jsp). The valueMap has get() method which will return the value.

The jsp of our blogPost component will be like this gistfile1.jsp
<%@include file="/libs/foundation/global.jsp"%>
<h1><%=properties.get("title","configure title")%></h1>
<br /><br />
<h3><%=properties.get("description","configure description")%></h3>
<br /><br />
<cq:text property="blogText" placeholder="configure blog post"/>

That's it, our configurable blog component is done.

cq:text tag is a convenience tag that is brilliant to output formatted HTML. It comes with a lot of brilliant things like a place holder, tagClass, etc... The best part is no null pointers in case you are not using JSTL.

NOTE: You can use the properties object in JSTL too. Ex: ${properties.title} instead of <%=properties.get("title","configure title")%>