Developing with Eclipse

This section describes the process of setting up a local development environment for a simple CQ5 project with Eclipse. It then describes how to integrate logic into the project through Java coding and JSP scripting. Lastly, it points to open source software to enable collaborative and automated developing.

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

The local development environment involves:

  • A CQ5 installation that will act as your local environment.

  • CRX Explorer within the CQ5 instance to create and edit nodes and properties within the CRX repository.

  • FileVault (VLT), a Day developed utility that maps the CRX repository to your file system.

  • Eclipse to edit the project source on your local file system.

  • Apache Maven to run local snapshot builds.

Creating the Project Structure in CQ5

This section describes the creation of a simple project structure in CQ5:

  1. Install CQ5 on your machine. Please refer to Installing CQ5 for the detailed procedure. In the current context, CQ5 runs locally on port 4502.

    If already installed then ensure it is running and connect.

  2. In the CRX Explorer, create the project structure:

    1. Under the /apps folder, create the nt:folder myApp.

    2. Under the myApp folder, create the nt:folder components.

    3. Under the myApp folder, create the nt:folder templates.

    4. Under the myApp folder, create the nt:folder install.

  3. In your browser, navigate to the Tools tab. Under designs, create the design page of your application:

    • Title: My Application Design Page.

    • Name: myApp.

    • Template: Design Page Template.

Installing FileVault (VLT)

FileVault (VLT) is a tool developed by Day that maps the content of a CRX instance to your file system. The VLT tool has similar functionalities to those of an SVN client, providing normal check in, check out and management operations, as well as configuration options for flexible representation of the project content.

To install VLT, follow the steps:

Installing Eclipse

Eclipse is open source software used to edit the project source locally on your file system. Apache Maven is also open source software, used to run local snapshot builds: it compiles Java code and stores the compiled code in a jar file.

In this section, you will install Eclipse and a Maven plugin which embeds the Maven functionality within Eclipse:

  1. Download Eclipse - select the Eclipse IDE for Java EE Developers option.

  2. Install Eclipse: extract from the downloaded zip file to your destination directory.

  3. Start Eclipse:

    1. Navigate to the directory into which you extracted the contents of the Eclipse installation zip file. For example C:\Program Files\Eclipse\.

    2. Double-click eclipse.exe (or to start Eclipse.

  4. Create a new workspace for your project and name it myApp.

  5. Install the Maven plugin (m2) from Sonatype: check the documentation at
    Note: Day recommends to disable Maven SCM handler for Subclipse and Maven Integration for AJDT.

  6. After installation it is recommended to restart Eclipse.

Creating the Project Structure in Eclipse

In this section, you will create two Maven projects:

  • one called UI (after User Interface) which contains the CQ5 project structure with the JSP scripts.

  • the other called Core which contains the Java code (source and compiled). The compiled code is stored in a jar file.

The advantage of such a structure is that it adds modularity and autonomy to the logic of your application because each jar file (bundle) can be managed separately.

Create the UI Maven Project

Create the Core Maven Project

Scripting with Eclipse and CQ5

When editing UI code use the following sequence:

  • Create a template and a component with the CRX Explorer.

  • Update the changes with VLT (export from the repository to your file system) .

  • Create a component script (JSP) with Eclipse.

  • Check in the changes from the file system into the repository with VLT.

The following example illustrates this process:

It is possible to define the VLT commands as External Tools in Eclipse. This enables you to run the VLT commands from within Eclipse.

Java Developing with Eclipse and CQ5

When editing Core code use the following sequence:

  • Create a Java class.

  • Compile the Java class.

  • Reference the jar file in the ui library.

  • Embed the Java Class logic into the JSP script.

  • Use VLT to check these changes to the JSP script (in the file system) into the repository.

  • Use VLT to deploy the jar file (with the compiled class) from the file system into the repository.

The following example illustrates this process:

Building collaborative and automated projects

This section points to three open source softwares which enhance the development of CQ5 projects by adding collaboration and automation features:

  • Subversion (SVN) to manage a central repository where all the developers involved in the project can commit and retrieve the code and the content they generate on their local instance.

  • Apache Archiva to centrally store and retrieve the project libraries.

  • Apache Continuum to automate the build process.

Collaboration with Subversion (SVN)

As the CQ5 repository can be mapped to your file system with VLT, it is now easy to set up a central repository with SVN. This is used by all developers in the project as a place they can commit, and retrieve, the code and content they generate on their local instances.

The setup of an SVN server is not covered in this document as many tutorials are already available online.

When VLT is in operation it creates .vlt files within the local directory structure. These .vlt files hold timestamps and other VLT-specific information that should not be checked into the SVN repository. This can be prevented by adding .vlt to the ignore list of the local SVN setup. To do this you add the following code to the local SVN setup file - settings.xml in the .subversion directory of your user's HOME directory:

Central dependency management with Apache Archiva

Java libraries, called artifacts in Maven language, can be managed centrally through Apache Archiva, an artifact repository that is used to store and retrieve the project artifacts. The setup of Archiva is well detailed online and can be referenced during setup. The Archiva server requires little management outside that of configuring local developer accounts to obtain access to the snapshots and full releases. Archiva can be found here.

When setting up Archiva for a CQ project the only step that is specific to CQ itself is initally populating the repository with the artifacts needed for CQ development. To acquire the full set of libraries you can use the same method as described above in point #7 of Create The UI Maven Project.

You can use the same script as shown there (and reproduced here):

This script simply downloads all the libraries from your CQ installation. By deploying these librarties to your Archiva repsoitory, you can make them available to your whole development team. To deploy the downloaded files to Archiva, see the Archiva documentation here.

Build automation with Apache Continuum

Once the project content and code is centrally available through an SVN server, it is possible to automate the build process and run the build on a daily basis (for example a nightly build). This is done with Apache Continuum, a continuous integration server with the sole duty of providing build management of artifacts and releases.

The setup of Continuum is also well detailed online.

Any questions?
Find tips, tricks, and solutions to common issues in our support community: