Creating cq5 component with a dialog (configurable component) - Part 1

By | 08:17 2 comments
The steps in this tutorial will require knowledge of creating a component in cq5. If you do not know how its done , check out my post "creating cq5 component " .

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 it 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(primary type::cq:widgetCollection)    
                                                           | tab1(primary type::cq:panel)

The interface in cq5 is created using Extjs frame work. 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

cq5 dialog structure
Above figure shows us the logical structure of a cq5 component dialog.The red rectangles are the actual input fields. Grey rectangles are structure for tabs. Black rectangles are structure for dialogs. All the rectangles are containers except for the red ones.From this information cq5 will create a 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 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.

Lets' 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 node. Enter items as the name and select "cq:widgetCollection" from the drop down for the node type. The naming convention again is important, 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 overview of crxde lite interface). Add a property to the node to give the tab a title. Enter name as 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 add in step 5 are explained below
  • name property is the name(location to be precise) of the property(or node depending on the vaue)  to be created under the components node(this node will hold  value content authors entered). "./" is replaced by 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 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.
  • 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 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.Check out part 2 for this.

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.




2 comments: Leave Your Comments

  1. Really good example of how dialogs work in CQ5. I've got one question about something you touched on. when we create a node with say name="./title/SomeChildProperty", in the JSP, how do you actually read that value?

    Could you show an example please?

    ReplyDelete
    Replies
    1. Hi Alisneaky

      when you use .title/SomeChildProperty it creates a node called title under your components node and the value is stored as someChildProperty property in the title node. To fetch it you have to use jcr api's. The following steps will fetch the property

      1) Fetch title node from the component's node (the node is available as currentNode in your component's jsp [implicit variable] if you have global.jsp included) by using getNode method

      2) get the property from title node using getProperty method

      3) fetch the value of the property by using getValue method on the property

      4) get string value from the value using getString method

      Node title = currentNode.getNode("title");
      Property someChildProperty = title.getProperty("someChildProperty");
      Value valueOfProp = someChildProperty.getValue();
      out.println(valueOfProp.getString());

      Make sure to check if the corresponding node and property exist before getting them using hasNode and hasProperty method to avoid exceptions.

      The links to the api are

      Node - www.day.com/maven/jsr170/javadocs/jcr-1.0/javax/jcr/Node.html
      Property - http://www.day.com/maven/jsr170/javadocs/jcr-1.0/javax/jcr/Property.html
      Value - http://www.day.com/maven/jsr170/javadocs/jcr-1.0/javax/jcr/Value.html

      Delete