Developing with CRXDE

This section describes how to develop your JCR, Apache Sling or CQ5 application with CRXDE.

Please refer to the overview documentation for more information on the different development environments that are available.

CRXDE is a pre-packaged stand-alone Eclipse application. CRXDE is custom-built specifically for CQ and CRX and thus enables you to efficiently develop your project. CRXDE gives you a broad set of tools to easily create and manage files, folders, templates, components, dialogs, nodes, properties, scripts and bundles while logging, debugging and integrating with SVN. CRXDE is built on the Eclipse Rich Client Platform (RCP), leveraging the Eclipse File System (EFS) API.
CRXDE is recommended when you develop complex applications by creating new components and Java bundles.

To get started with CRXDE, proceed as follows:

1. Install CQ or CRX.
2. Download the CRXDE package.
3. Extract the package.
4. Double-click the executable.
5. Enter the location of your CQ or CRX installation. By default it is:
   
   • http://localhost:4502/ for CQ5 Quickstart
   • http://localhost:7402/ for CRX Quickstart
6. Enter your username and password. By default it is admin and admin.
7. Click OK.
   

Note. If your installation uses non-standard contexts for CRX web applications, e.g., when you deployed CRX to an application server in such a way, you need to do the following:

• In case CRX Launchpad web application is installed under another context (e.g., /launchpad instead of /), you need to login to this URL
  • http://<host>:<port>/launchpad
• In case CRX web application is installed under another context (e.g., /daycrx instead of /crx), you need to configure the CRX server endpoint to use this context (/daycrx/server)

The CRXDE User Interface looks as follows:

The screenshot shows CRXDE main window, with content navigator, editor window with a JSP file, outline of the file, and properties of the content node.

You can now use CRXDE to develop your application.

By default, CRXDE does not need to be configured. For advanced use cases, CRXDE offers advanced options to:

• Change the CRX server endpoint.
• Change the compiler output path.
• Change the mounted folders.

CRXDE supports the following Day products:

• CRX repository
• CQ5 suite of content management products; CQ5 is based on CRX repository

CRXDE provides the Integrated Development Environment functionalities and features offerred by its underlying Eclipse platform. These include editing of source code, code completion and restructuring, searching and browsing, and many others.

Additionally, CRXDE provides extended support for CRX and CQ5 specific development tasks. This functionality is described in the following subsections.

To create a folder with CRXDE:

1. In CRXDE, in the Navigator tab, right-click the folder under which you want to create the new folder, select New, then Folder.
2. Enter the Folder name and click Finish.

Day recommends that you create the following structure for your application:

• /apps/<application-name>: the application container
• /apps/<application-name>/components: the components container
• /apps/<application-name>/templates: the templates container
• /apps/<application-name>/src: the bundles container
• /apps/<application-name>/install: the compiled bundles container
• /apps/<application-name>/docroot: the static files container

To create a template with CRXDE:

1. In CRXDE, in the Navigator tab, right-click the folder where you want to create the template, select New, then Template.
   
2. Enter the Label, Title, Description, Resource Type and Ranking of the template. Click Finish.

It creates:

• A node of type cq:Template with Template properties
• A child node of type cq:PageContent with Page Content properties

You can drag and drop a thumbnail from your file system into the template folder.

You can add properties to your template: refer to the Creating a Property section.

To create a component with CRXDE:

1. In CRXDE, in the Navigator tab, right-click the folder where you want to create the component, select New, then Component.
   
2. Enter the Label, Title, Description, Super Resource Type and Group of the component. Click Next.
3. If needed, set values for the optional properties Allowed Parents, Allowed Children and check the box Is Container. Click Finish.

It creates:

• A node of type cq:Component
• Component Properties
• A component .jsp script

To create a dialog with CRXDE:

1. In CRXDE, in the Navigator tab, right-click the component where you want to create the dialog, select New, then Dialog.
   
2. Enter the Name and the Title. Click Finish.
   

It creates a dialog with the following structure:

dialog[cq:Dialog]/items[cq:TabPanel]/items[cq:WidgetCollection]/tab1[cq:Panel]

You can now adapt the dialog to your needs by modifying properties or creating new nodes.

To create a node with CRXDE:

1. In CRXDE, in the Navigator tab, right-click the node where you want to contain the new node, select New, then Node.
   
2. Enter the Name and the Type. Click Finish.
   

You can now adapt the node to your needs by modifying properties or creating new nodes.

To create a property with CRXDE:

1. In CRXDE, in the Navigator tab, right-click the node where you want to add the new property, select New, then Property.
   
2. Enter the Name, the Type and the Value. Click Finish.

You can also edit properties and add new ones in the Properties tab.

To create a new script:

1. In CRXDE, in the Navigator tab, right-click the component where you want to create the script, select New, then JSP.
2. Enter the File name. Click Next.
3. Select the JSP Template and click Finish.
   The new file opens in the main tab.

You can use the following key combinations for code completion:

• Ctrl + Space on Windows
• Cmd + Space on Mac

To import a file or a folder from your file system into the repository with CRXDE:

1. In your file explorer copy the file (or the folder).
   
2. In CRXDE, navigate to the location that will contain the file (or the folder). Right-click and select Paste.

The files are mapped to nodes of type nt:file and the folders to nodes of type nt:folder.

You can also drag and drop the file (or the folder) directly into CRXDE.

With CRXDE, you can easily create and compile individual Java classes.

To create a Java class, select a folder where you want to place the new class. Usually, it is a part of an existing Java package (e.g., com/example/mypackage). Right-click the folder, select New, then Class. Fill out the Eclipse dialog providing information about your class, and click Finish. Your class is created, and its skeleton source file displayed in the editor.

Once you add source code to your class, you can easily compile it. Right-click the class source file in Navigator, select Build, then Compile. Your class will be compiled and automatically deployed into CRX OSGi container. In case of compilation problems, you will see the status in the Remote Build view.

With CRXDE, it is straigthforward to create an OSGI bundle, add Javaclasses to it, and build it. The bundle is then automatically installed and started in the OSGI container.

This section describes how to create a Test bundle with a HelloWorld Java class that displays Hello World! in your browser when the resource is requested.

To create the Test Bundle with CRXDE:

1. In CRXDE create the following structure:
   
   • /apps/myapp/src
   • /apps/myapp/install
     
2. Right-click the folder /apps/myapp/src that will contain the Test bundle, select Create ..., then Create Bundle ....
   
3. Enter the following values for the bundle properties:
   
   • Symbolic Bundle Name: com.mycompany.test.TestBundle
     
   • Bundle Name: Test Bundle
   • Bundle Description: This is my Test Bundle
     
   • Package: com.mycompany.test
     
   Click Finish.

The wizard creates the following elements:

• The node com.mycompany.test.TestBundle of type nt:folder. It is the bundle container node.
  
• The file com.mycompany.test.TestBundle.bnd.  It acts as deployment descriptor for your bundle and consists of a set of headers.
  
• The folder structures:
  
  • src/main/java/com/mycompany/test. It will contain the packages and the Java classes.
    
  • src/main/resources. It will contain the resources used within the bundle.
    
• The Activator.java file. It is the optional listener class to be notified of bundle start and stop events.
  

The following table lists all the properties of the .bnd file, their values and descriptions:

For more information on the bnd format, refer to the bnd utility used by CRXDE to create OSGI bundles.

To create the HelloWorld Java class within the Test Bundle:

1. In CRXDE, in the Navigator tab, navigate to /apps/myapp/src/com.mycompany.test.TestBundle/src/main/java. Right-click it, select New, then Class.
2. Set HelloWorld as Name. Click Finish.
   The HelloWorld.java file is created beside Activator.java and displays following code in the main pane:
   package com.mycompany.test;
   
   public class HelloWorld {
   
   }
3. Add the following lines into the body of the HelloWorld class:
       public String getString(){
       return "Hello World!";
       }
   Save the changes.

To build the Test Bundle:

1. In CRXDE, in the Navigator tab, right-click the .bnd file and select Build Bundle.

The Build Bundle wizard:

• Compiles the Java classes.
• Creates the .jar file containing the compiled Java classes and the resources and places it into the myapp/install folder.
• Installs and starts the bundle in the OSGI container.

To see the effect of the Test Bundle, create a component that uses the Java method HelloWorld.getString() and a resource that is rendered by this component:

1. Create the component mycomp under myapp/components.
2. Edit mycomp.jsp and replace the code with the following lines:
   <%@ page import="com.mycompany.test.HelloWorld"%><%
   %><%@ include file="/libs/foundation/global.jsp"%><%
   %><% HelloWorld hello = new HelloWorld();%><%
   %>
   <html>
   <body>
   <b><%= hello.getString() %></b><br>
   </body>
   </html>
3. Save the changes.
4. Create the resource test_node of type nt:unstructured under /content.
   
5. For test_node, create the following property: Name = sling:resourceType, Type = String, Value = myapp/components/mycomp.
6. In your browser, request test_node: http://<hostname>:<port>/content/test_node.html.
7. A page is displayed with Hello World! in bold.

In CRXDE you can display the file error.log that is located on the file system at <crx-install-dir>/crx-quickstart/server/logs and filter it with the appropriate log level. Proceed as follows:

1. In CRXDE, in the Console tab at the bottom of the window, click the arrow beside the Display Selected Console icon and select CQ.
2. In the drop-down menu, set the log level. It can be one of the following values: trace, debug, info, warn or error.
   The error.log is filtered according to the log level and displayed in the tab.

To debug with CRXDE:

1. Stop the CRX server.
   
2. Start the CRX server in debug mode: on the command line, change to the directory <crx-quickstart> and enter the following command:
   java -debug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=30303 -jar <quickstart-name>.jar
   Note: you can also enter the following command: server/start -d
   
3. In CRXDE, in the top menu bar, select Debug, then Attach Debugger.
4. As port number, enter 30303 (as defined as the address argument of the Xrunjdwp option). Click OK.
   
5. The Debug Perspective is displayed. You can now set breakpoints in the .jsp and .java files.

To switch back to the standard perspective, use cmd + F8 or terminate the debug session by using the Disconnect button in the Debug view.

With CRXDE you can perform the following operations through the tree context menu (Version Control):

• Import into SVN (initial checkout)
  
• Check out from SVN
• Export from SVN
• Update from SVN
  
• Commit to SVN
• View the SVN status

The following image illustrates the Version Control context menu:

Importing allows you to put a project under version control that was initially created with CRXDE (rather than in SVN). Use this command to initially check out content to SVN.

To import the CRX repository into SVN:

To check out from SVN:

Exporting from the SVN is similar to checking out except that this action does not create a working copy.

When you create or modify a file or a folder that is under version control, it is automatically added to the version control.

To commit a change:

To update a file or folder from SVN:

You can view the SVN status, either by looking at the icons on the nodes in the Navigator tab or by doing the following:

CRXDE 1.0 supports the following product versions.

CRXDE supports this version out of the box.

CQ 5.3 is based on the CRX 2.0 release (only released as a part of CQ 5.3). To ensure compatibility of CRXDE 1.0 with CQ 5.3, the CRXDE Support module from CRX 2.1 release should be installed into CQ 5.3.

To use CRXDE with this release, you have two options outlined in the following subsections.

To upgrade the CRXDE Support package in your CQ 5.3 instance to version 2.1 you have to obtain the upgrade package and install it into your CQ 5.3. There are two ways of obtaining the package.

Download from Package Share (recommended). The CRXDE Support package is available on Day Package Share, in the section Public » Day » CQ 5.3.0 » upgrade. The package is called cq53-update-crxdesupport. To install it:

• Go to Packages in your CQ 5.3 instance
  
• Select Package Share
  
• Log in to Package Share using your day.com user account
  
• Navigate to the Public » Day » CQ 5.3.0 » upgrade section
• Click Download for cq53-update-crxdesupport-2.1.0.zip
  
• After downloading, the button changes to Downloaded; click this and the CQ5 Package Manager will open
• Install the package
  

Extract the updated components from CRX 2.1 quickstart jar file. If you don't have access to the Package Share from your instance, you can also get all the required components from a CRX 2.1 quickstart jar file. Please follow these steps:

• Extract the CRX support package from the CRX 2.1 quickstart jar file:
  • unpack the CRX 2.1 quickstart file in an empty folder:
    java -jar crx-2.1.0.20100426-<edition>.jar -unpack
  • in the folder where you unpacked CRX 2.1, unzip the initial content file:
        crx-quickstart/repository/install/crx-initial-content-2.1.0.zip
  • using the CRX Package Manager upload and install the CRX 2.1 crxde-support package from the unpacked zip file:
        jcr_root/etc/packages/day/crx210/product/crxde-support.zip
• Then install additional packages:
  • navigate to the extracted crx-initial-content-2.1.0
  • navigate to jcr_root/libs/sling/install
  • upload the following jars to /libs/sling/install (e.g. using WebDAV):
    
    • org.apache.sling.commons.auth-0.9.0-R925144.jar
    • crx-auth-token-2.1.0.jar

After upgrading the CRXDE Support package, restart the instance. Start CRXDE and connect to the instance to check, whether the tool works correctly. Pay special attention to checking, if you can execute server-side functionalities (like bundle compilation, product creation, CRXDE operations).

After you have successfully installed the upgrade and tested your instance, your CQ 5.3 is ready for developing with CRXDE.

Please see Upgrading CQ 5.3 to CRX 2.1 for upgrade instructions.The procedure includes the required update of the CRXDE support package to version 2.1.

After you have successfully upgraded and tested your instance, your CQ 5.3 is ready for developing with CRXDE.