The CQ Project Maven Archetype

What is the CQ Project Maven Archetype?

The CQ Project Maven Archetype is a standard Maven Archetype that can be used to quickly and easily generate multi-module Maven Projects that can be used to bootstrap new Adobe CQ 5.5 development projects.

The generated Maven Project has the following characteristics:

• it is based on the real world experience of CQ developers and trainers
• it includes examples of common development tasks
• it demonstrates best practices for working with items like OSGi Bundles, JSP Tag Libraries and CQ based content (components, DAM assets etc)
• it makes the development phase of a CQ project with multiple developers involved easier and more efficient
• it makes packaging releases for QA, Staging and Production environments easy and reliable
• it is completely customized for your project based on the values you supply during the project generation process

NOTE: The CQ Project Maven Archetype is built and tested against Adobe CQ 5.5 and by default the generated project will not work with CQ 5.4 due to changes made by Adobe between the two versions. However, the basic Project layout and Maven module definitions are still valid (and recommended) for a CQ 5.4 project.

What do I need to be able to use the CQ Project Maven Archetype?

The CQ Project Maven Archetype is available from the official CQ Blueprints Maven Repository. In addition, the generated CQ project makes use of Maven Artifacts that are only available from the CQ Blueprints Maven Repository. So you need to have access to the CQ Blueprints Maven Repository configured.

If you have not already configured access to the CQ Blueprints Maven Repository, see Connecting to the CQ Blueprints Repository.

The generated CQ project also makes use of Maven Artifacts that are only available from the Adobe Maven Repository.

If you have not already configured access to the Adobe Maven Repository, see Connecting to the Adobe Maven Repository.

How do I use the CQ Project Maven Archetype to bootstrap a new CQ development project?

The CQ Project Maven Archetype is a standard Maven Archetype, so you use it just like you would any other Archetype.

Here's a step-by-step guide:

1. Get access to the official CQ Blueprints Maven Repository (see above)
2. Run the following Maven command from your favorite command line:
      mvn archetype:generate -DarchetypeCatalog=http://dev.cqblueprints.com/nexus/content/repositories/releases/ -Dfilter=multi-module
3. Normally this Maven command would present you with a list of all of the available Maven Archetypes (possibly many hundreds of them), however since you added the additional parameters on the command line, there should only be one Archetype in the list.
4. You will next be prompted to select which Archetype you want to use, so assuming only 1 Archetype was returned, enter the number 1 and hit Enter.
5. Next you will see a summary of the customizable properties for the generation of the Maven Project and a Yes/No style prompt.
6. If you hit Enter now, Yes is the default response and so the Maven Project would be generated with the default property settings. Normally you will instead want to type the letter n and then hit Enter, which will give you the chance to customize the properties before the Maven Project gets generated.
7. Assuming you typed the letter n and then hit Enter, you will now be presented with a prompt for each property, where you can customize its value. The available properties are:
   • groupId : this will be used as the normal Maven groupId for all modules in the generated Maven Project. See Maven's Guide to Naming Conventions for help in picking good groupId and artifactId values
   • artifactId : this value will be used for several purposes
     • as part of the normal Maven artifactId for all modules in the generated Maven Project
     • as the name of your CQ Application, which means that various JCR paths will include this value, for example:
       • /apps/artifactId
       • /etc/designs/artifactId
       • /content/artifactId
       • /content/dam/artifactId
   • version : this will be used as the normal Maven version value for all modules in the generated Maven Project
   • package : this will be used as the base Java package for the Java classes anywhere actual Java classes are used
   • project-name : this is a human readable and friendly name for your project, it can contain spaces etc.
   • taglib-domain : this will be used as the server name in the URI of the JSP Tag Library module
   • taglib-shortname : this will be used as the XML namespace for the JSP Tag Library module
8. Once you have entered values for the customizable properties, you will be presented with the same prompt as you saw in Step 5 above, with the same Yes/No prompt. If you are happy with the values simply hit Enter. If you want to change any of the values, enter the letter n and then hit Enter and go through the process of changing the property values again.
9. Next the project is actually generated and written to your local filesystem. It will be placed in a sub-directory of the directory where you ran the mvn command, the directory will have the same name as what you entered for the artifactId property above
10. If you do not already have access to the Adobe Maven Repository from your development environment, follow these instructions Connecting to the Adobe Maven Repository.
11. If you change into this directory, you can run mvn install and the whole project will build successfully (nothing will be deployed to a CQ instance however)
12. Recommended : check this project into your source control repository (e.g. Subversion) immediately and then begin your development effort

How should I use the generated project?

The generated project is a multi-module Maven project consisting of a parent project and 6 modules. The 6 modules each serve a different purpose and are intended to best separate the different development concerns so that Developers can work easily in parallel without tripping over each other.

What follows is a brief description of each module, the module's intent and a high level guide as to how to work with the module:

${artifactId}-view

Use this module for development of CQ components, templates and designs.

As a developer you will use the vlt tool to synchronize your local CQ repository with the src/main/content/jcr_root directory of this module. The filter.xml file to control how vlt works is already correctly defined for you as part of the project generation process. You will normally NOT use Maven to do anything with this module during day-to-day local development, the Maven build will only be used when making formal releases for example where the CQ content will be bundled up into a CQ Package for deployment to QA / Staging / Production type environments.

${artifactId}-config

Use this module for managing your JCR based configuration settings.

The default module generated from the Archetype demonstrates how to use the run modes feature of CQ to target configuration settings to specific environments.

As a developer you will use the vlt tool to synchronize your CQ repository with the src/main/content/jcr_root directory of this module. The filter.xml file to control how vlt works is already correctly defined for you as part of the project generation process. You will normally NOT use Maven to do anything with this module during day-to-day local development, the Maven build will only be used when making formal releases for example where the CQ content will be bundled up into a CQ Package for deployment to QA / Staging / Production type environments.

${artifactId}-services

Use this module to deploy custom OSGi services to your CQ environment.

The Maven build for this module is pre-configured to use the SCR tools to automatically generate OSGi service descriptors based on Java Annotations. The default module generated from the Archetype contains various examples of Services with Annotations applied.

As a developer you WILL use Maven to build and deploy this module into your CQ environment by simply running the following Maven command:

mvn -Pauto-deploy install

The Maven build will generate all of the necessary OSGi metadata, package your OSGi bundle and deploy it to your CQ environment. Once the build process is finished, it should be as easy as hitting refresh on your browser to see the effects of your code changes.

${artifactId}-taglib

Use this module to write your JSP Custom Tag Library classes, which will then be deployed as an OSGi bundle to your CQ environment.

The Maven build for this module is pre-configured with everything you need to write a JSP Custom Tag Library, including plugins to automate the generation of the Tag Library Descriptor (.tld) file.

As a developer you WILL use Maven to build and deploy this module into your CQ environment by simply running the following Maven command:

mvn -Pauto-deploy install

The Maven build will generate the Tag Library Descriptor, all of the necessary OSGi metadata, package your Taglib as an OSGi bundle and deploy it to your CQ environment. Once the build process is finished, it should be as easy as hitting refresh on your browser of a page that uses your Tag Library to see the effects of your code changes.

IMPORTANT: due to an issue with the 2.1.0 version of the maven-sling-plugin, you must ensure that the JCR path that you want to deploy the services and the taglib bundles to already exists before you make use of the auto-deploy profile. Check the pom.xml in either module for further information.

${artifactId}-all

Use this module to build and package your entire CQ Project into a single deployable CQ Package - the package will include everything from the view, config, services and taglib modules.

Normally as a developer you will not use this module during day-to-day local development. This module will mainly be used for making nice / clean / repeatable releases from the Development team to the QA team, or for Staging and Production environments for example.

${artifactId}-content

Use this module for sharing content between developers for early stage testing purposes.

Most CQ development projects must begin and proceed for a significant amount of time before content authors begin to formally contribute real content through a CQ Author instance. However, since CQ is very content centric, developers often need content to be available to fully test their code.

The intent of this module is to allow developers to easily share content (via a source code repository) and prevent 2 situations:

• each developer mocking up their own example content in parallel and not sharing it with the rest of the team (thus wasting time)
• piecemeal / inconsistent distribution of actual example content that may be available to the Development team (from a marketing team for example)

IMPORTANT: Do not confuse this module with the view module. The view module will contain code and assets that are appropriate for the development team to create and manage during all phases of the project (including after "go live"). This module instead contains content that will eventually be managed by content authors and will only temporarily be managed by developers. The filter.xml file to control how vlt works in the view module and in the content module are configured differently to reflect this difference. Once the content authors have access to a functional CQ Author instance and are able to contribute real content and use the other management features available to them, this module should be deleted (removed from the Maven build and also removed from your source code repository) - and instead developers should start using CQ Packages exported from the CQ Author environment that contain the real content and use that real content for any further testing purposes going forward.

This module is not bundled into the CQ Package created by the all module, as it is not intended to be included in formal releases from the Development team.