How to Set Up the Development Environment with Eclipse in AEM

1. Creating the Project Structure in CQ5
2. Installing FileVault (VLT)
3. Installing Eclipse
4. Creating the Project Structure in Eclipse
5. Scripting with Eclipse and CQ5
6. Java Developing with Eclipse and CQ5
7. Building collaborative and automated projects

This 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.
The setup described here is an alternative among others and may vary from project to project.
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 AEM
This section describes the creation of a simple project structure in CQ5:
Install CQ5 on your machine. Please refer to the section called “Installing a CQ WCM Instance – Generic Procedure” for the detailed procedure. In the current context, CQ5 runs locally on port 4502.
If already installed then ensure it is running and connect.
In the CRX Explorer, create the project structure:
Under the /apps folder, create the nt:folder myApp.
Under the myApp folder, create the nt:folder components.
Under the myApp folder, create the nt:folder templates.
Under the myApp folder, create the nt:folder install.
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:
In your file system, go to /crx-quickstart/opt/filevault. The build is available in both tgz and zip formats.
Extract the archive.
Add /crx-quickstart/opt/filevault/vault-cli-/bin to your environment PATH so that the command files vlt or vlt.bat are accessed as appropriate. For example, /crx-quickstart/opt/filevault/vault-cli-1.1.2/bin
Open a command line shell and execute vlt –help. Make sure it displays the following help screen:

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:
4. Navigate to the directory into which you extracted the contents of the Eclipse installation zip file. For example C:\Program Files\Eclipse\.
5. Double-click on eclipse.exe (or eclipse.app) to start Eclipse.
6. Create a new workspace for your project and name it myApp.
7. Install the Maven plugin (m2) from Sonatype. Disable Maven SCM handler for Subclipse (Optional) and Maven Integration for AJDT (Optional).
8. 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

To create the UI Maven project, follow the steps:

1. In Eclipse open the Workbench.

2. Create the UI Maven project:

• In the Menu bar, click File, select New, then Other... .

• In the dialog, expand the Maven folder, select Maven Project and click Next.

• Check the Create a simple project box and the Use default Workspace locations box, then click Next.

• Define the Maven project:

• Group Id: com.day.cq5.myapp

• Artifact Id: ui

• Name: CQ5 MyApp UI

• Description: This is the UI module

• Click Finish.

3. Set the Java Compiler to version 1.5:

• Right-click the ui project, select Properties.

• Select Java Compiler and set following properties to 1.5:

• Compiler compliance level

• Generated .class files compatibility

• Source compatibility

• Click OK.

• In the dialog window, click Yes.

4. Create the filter.xml file which defines the content that will be exported by VLT:

• In Eclipse, navigate to ui/scr/main and create the content folder.

• Under content, create the META-INF folder.

• Under META-INF, create the vault folder.

• Under vault, create the filter.xml file.

• In filter.xml, copy the following code to filter.xml:

<!–

Defines which repository items are generally included

–>

• Save the changes.

5. Check out the CQ5 content into your ui project with VLT:

• From the system command line, navigate to the directory holding your Eclipse workspace//myApp/ui/src/main/content.

• Execute the command: http://localhost:4502/crx

This command creates the folder jcr_root under //myApp/ui/src/main/content. This maps to the CRX root (/). Under jcr_root the following files and folders are created, as defined in filter.xml:

• apps/myApp

• etc/designs/myApp

It also creates two files, config.xml and settings.xml in //myApp/ui/src/main/content/META-INF/vault. These are used by VLT.

6. To enable Eclipse to map the file paths used in the JSP scripts, create a link to the apps folder under ui:

• Right-click ui, select New, then Folder.

• In the dialog window, click Advanced and check the Link to folder in the file system box.

• Click Browse, then specify //myApp/ui/src/main/content/jcr_root/apps.

• Click OK.

• Click Finish.

7. To enable Eclipse to identify the Java classes, methods and objects used in the JSP scripts, export the needed Java libraries from the CQ5 server to your file system and reference them in the ui project.

In this example, you will reference the following libraries:

• libs/cq/install stored in the CQ5 server

• libs/sling/install stored in the CQ5 server

• libs/wcm/install stored in the CQ5 server

• /crx-quickstart/server/lib/container stored in your file system

Proceed as follows:

• In your file system, create a CQ5 libraries folder called cq5libs. This folder can be created anywhere.

• Under cq5libs, create the folders: cq, sling and wcm.

• From the system command line go to .../cq5libs/cq and execute http://localhost:4502/crx to export the libraries stored under /libs/cq/install from the CQ5 server.

• From the system command line go to .../cq5libs/sling and execute http://localhost:4502/crx to export the libraries stored under /libs/sling/install from the CQ5 server.

• From the system command line go to .../cq5libs/wcm and execute http://localhost:4502/crx to export the libraries stored under /libs/wcm/install from the CQ5 server.

• In Eclipse, right-click the ui project, select Build Path, then Configure Build Path. In the dialog select the Libraries tab.

• Click Add External JARS..., navigate to .../cq5libs/cq/jcr_root, select all the jar files and click Open.

• Click Add External JARS..., navigate to .../cq5libs/sling/jcr_root, select all the jar files and click Open.

• Click Add External JARS..., navigate to .../cq5libs/wcm/jcr_root, select all the jar files and click Open.

• Click Add External JARS..., navigate to /crx-quickstart/server/lib/container, select all the jar files and click Open.

• Click OK.

Create the Core Maven Project

To create the Core Maven project, follow the steps:

1. In Eclipse, create the Core Maven project:

1. In the Menu bar, click File, select New, then Other... .

2. In the dialog, expand the Maven folder, select Maven Project and click Next.

3. Check the Create a simple project box and the Use default Workspace locations box, then click Next.

4. Define the Maven project:

• Group Id: com.day.cq5.myapp

• Artifact Id: core

• Name: CQ5 MyApp Core

• Description: This is the Core module

5. Click Finish.

2. Add the necessary plugins and dependencies to the core project:

1. Open the pom.xml file under the core.

2. Copy-paste following code before the tag:

bundle

org.apache.maven.plugins

maven-compiler-plugin

1.5

1.5

org.apache.felix

maven-bundle-plugin

1.4.3

true

com.day.cq5.myapp.*;version=${pom.version}

com.day.cq.wcm

cq-wcm-api

5.1.20

com.day.cq

cq-commons

5.1.18

org.apache.sling

org.apache.sling.api

2.0.3-incubator-R708951

3. Save the changes.

3. Deploy the CQ5 specific artifacts as defined in the pom.xml (cq-wcm-api, cq-commons and org.apache.sling.api) to the local Maven repository:

1. From the system command line go to /.m2/repository/com/day/cq/wcm/cq-wcm-api/5.1.20 (create the folders if they don’t exist) and execute http://localhost:4502/crx to export the library from the CQ5 server.

2. From the system command line go to /.m2/repository/com/day/cq/cq-commons/5.1.18 (create the folders if they don’t exist) and execute http://localhost:4502/crx to export the library from the CQ5 server.

3. From the system command line go to /.m2/repository/org/apache/sling/org.apache.sling.api/2.0.3-incubator-R708951 (create the folders if they don’t exist) and execute http://localhost:4502/crx to export the library from the CQ5 server.

 

Note

You don’t need to perform this step if the three CQ5 artifacts are globally deployed for the project on a Maven repository (e.g. using Apache Archiva).

4. Set the Java Compiler to version 1.5:

1. Right-click the core project, select Properties.

2. Select Java Compiler and set following properties to 1.5:

• Compiler compliance level

• Generated .class files compatibility

• Source compatibility

3. Click OK.

4. In the dialog window, click Yes.

5. Create the package com.day.cq5.myapp that will contain the Java classes under core/src/main/java:

1. Under core, right-click src/main/java, select New, then Package.

2. Name it com.day.cq5.myapp and click Finish.

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:

1. Create a new template with the CRX Explorer:

• In the CRX Explorer, under /apps/myApp/templates, create a new template: Name: contentpage Type: cq:Template

• Under the contentpage Node, edit the Property jcr:title and add as Value: MyApp Content Page Template

• Under the contentpage Node, add a new Node: Name: jcr:content Type: cq:PageContent

• Under the jcr:content Node, edit the Property sling:resourceType and add as Value: myApp/components/contentpage

• Under the jcr:content Node, add a new Property: Name: personName Value: myName

2. Create a new component with the CRX Explorer:

• In the CRX Explorer, under /apps/myApp/components, create a new component: Name: contentpage Type: cq:Component

3. Use VLT to update the changes made from your repository to your file system, and therefore Eclipse:

• From the system command line navigate to //myApp/ui/src/main/content/jcr_root.

• Execute:  to see the changes made on the repository.

• Execute:  to update the changes from the repository to your file system.

4. Create the component script (JSP) with Eclipse:

• In Eclipse, navigate to ui/src/main/content/jcr_root/apps/myApp/components/contentpage.

• Right-click contentpage, select New, then File.

• In the dialog, name the file contentpage.jsp and click Finish.

• Copy the following code into contentpage.jsp:

This is the contentpage component.

• Save the changes.

5. With VLT check in the changes from the file system into the repository:

• From the system command line navigate to //myApp/ui/src/main/content/jcr_root.

• Execute:  to see the changes made on the file system.

• Execute:  to add the contentpage.jsp file to VLT control.

• Execute:  to commit the contentpage.jsp file to the repository.

6. From CQ5 create a page based on this template. Open the page to make sure it displays the following message:

This is the contentpage component.

 

Tip

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:

1. Create the Java class:

1. In Eclipse, under core/src/main/java, right-click the com.day.cq5.myapp package, select New, then Class.

2. In the dialog window, name the Java Class HelloPerson and click Finish. Eclipse creates and opens the file HelloPerson.java.

3. In HelloPerson.java replace the existing code with the following:

package com.day.cq5.myapp;

import com.day.cq.wcm.api.Page;

public class HelloPerson {

private Page personPage;

public static final String PN_PERSON_NAME = “personName”;

public HelloPerson(Page personPage) {

this.personPage = personPage;

}

public String getHelloMessage() {

String personName = personPage.getProperties().get(PN_PERSON_NAME).toString();

return personName != null ? personName : “–empty–“;

}

}

4. Save the changes.

2. Compile the Java class:

1. Right-click the core project, select Run As, then Maven Install.

2. Make sure that a new file core-0.0.1-SNAPSHOT.jar (containing the compiled class) is created under core/target.

3. Reference this jar file in the ui library to enable the code completion when accessing this class with the JSP script:

1. In Eclipse, right-click the ui project, select Build Path, then Configure Build Path. In the dialog select the Libraries tab.

2. Click Add JARS... and navigate to core/target, select the core-0.0.1-SNAPSHOT.jar file and click OK.

3. Click OK to close the dialog.

4. Embed the Java Class logic into the JSP script:

1. In Eclipse, open the JSP script contentpage.jsp in ui/src/main/content/jcr_root/apps/myApp/components/contentpage.

2. Replace the existing code with the following:

<%

HelloPerson hello = new HelloPerson(currentPage);

String msg = hello.getHelloMessage();

%>

Hello, .

This is the contenpage component.

3. Save the changes.

5. With VTL check in the changes to the JSP script from the file system to the repository:

1. From the system command line navigate to //myApp/ui/src/main/content/jcr_root.

2. Execute:  to see the changes made on the file system.

3. Execute:  to commit the modified contentpage.jsp file to the repository.

6. Deploy the jar file containing the compiled class from the file system into the repository with VLT:

1. In Eclipse, under core/target, copy the core-0.0.1-SNAPSHOT.jar file.

2. In Eclipse navigate to ui/scr/main/content/jcr_root/apps/myapp/install and paste the copied file.

3. From the system command line navigate to //myApp/ui/src/main/content/jcr_root.

4. Execute:  to see the changes made on the file system.

5. Execute:  to add the jar file to VLT control.

6. Execute:  to commit the jar file to the repository.

7. In your browser, refresh the CQ5 page to make sure it displays following message:

Hello, myName.

This is the contentpage component.

8. In CRX Explorer, change the value myName and make sure that the new value is displayed when you refresh the page.

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 Archive to centrally store and retrieve the project libraries.

• Apache Continuum to automate the build process.