Using OpenCms-Maven

Introduction

After setting up a basic OpenCms project with OpenCms-Maven, developers can start customizing and extending it. Therefore OpenCms-Maven provides tools to synchronize the changes in the OpenCms installation with your workspace and vice versa.

Project structure

Every OpenCms-Maven project must have a minimal project structure that consists of four or five different subprojects. These projects are:

Project name –> Output

parent –> none
webapp –> war file
system –> VFS resources
content –> VFS resources
orgunits –> VFS resources

Each sub project contains its own POM file which defines the type of the project and the actions that should take place while building.

parent

The parent project actually contains only one interesting resource – the so called parent POM file. This file declares settings which are global for the whole OpenCms project. Other POM files in the subprojects have this file declared as their parent. The parent POM finally defines the structure of the whole Maven project. For example, if a new subproject should be added to the project the new project would have been included in a special section within the parent POM.

The parent project’s directory is also the only entry point for some actions like cleaning and building the whole project.
webapp
Contains the webapplication itself and starts an instance of OpenCms in the background that is used by the VFS plugin to access the VFS. It also executes basic functions of the VFS modules:

The basic intializing of the VFS
Importing of user and group data

system
The system project contains all OpenCms ressources beneath the /system folder (excluding custom modules).

content
The content project contains ordinary user content. By default it synchronizes all resources of the default site.

orgunits
Creates and synchronizes organization units of the system.

Development cycle

After having a running OpenCms installation changes at the system normally are applied by an iterative development cycle.

The cycle begins by updating the current workspace on the RFS with a source control management client (for example Subversion or the Subversive plugin for eclipse). To apply these changes the synchronization mechanism of the OpenCms-Maven VFS plugin has to be triggered next. After synchronizing the ressources within the OpenCms VFS should be the same as in the SCM. Changes in the VFS are not published immediately so if you need them in the online project you have to publish them manually.

The system should be now in a „clean“ state. That means the developer can now begin to modify VFS resources. After modification a new call of the synchronization mechanism will write the new modifications from the VFS to the right place RFS. The developer can then use the SCM client again to commit the changes to the repository.

Synchronizing VFS resources

To synchronize VFS resources you have to call the OpenCms-Maven VFS Plugin for the particular subprojects the resources belong to. You can use the following syntax:

mvn vfs:sync

this calls the sync goal of the OpenCms-Maven VFS Plugin. After calling it, the plugin uses special files that contain synchronization information to compare the state of the RFS resources with the VFS resources. New resources in the VFS will be created in the RFS and modified resources will have got modified metadata within the /src/main/vfs-metadata/ folder.

CAUTION: because of problems with the eclipse workspace, resources in the RFS won’t be automatically deleted by the plugin. Instead a message will occur on the command line that prompts the user to delete the relevant files. We hope to get this fixed in future.

Example

What follows now is a little example to illustrate the handling of the OpenCms-Maven VFS Plugin. The goal will be to add a new VFS module and commit it to the repository.

Copy an existing Eclipse VFS project (e.g. the “system” project)
Name it template_vfs (or whatever you want – our convention is to use _vfs for VFS projects and _java for Java projects)
change all folder names etc. according to your new module in pom.xml (e.g. groupId, artifactId, URLs to scm and version control and most importantly the section)
Go to MODULE_NAME/src/main/vfs and delete all subfolders and the file #synclist.txt
Go to MODULE_NAME/src/main/vfs-metadata and delete all subfolders
Create a new module in OpenCms and publish the module folder (and files, if any)
From the opencms-modules.xml copy the module section of the new module to \MODULE_NAME\src\main\opencms-module\opencms-module.xml (remove the existing entries)
Add the VFS module to the modules section of the parent pom. (e.g.: ../template_vfs)
If your VFS module uses a Java module add that as dependency to the webapp module
Now you can do a vfs:sync in your VFS module
Hit F5 in Eclipse. Now all the resources should be within your workspace.
Now you can do a complete build (mvn clean package) and test, if everything works as expected
If everything works, check in the module to your version control system

Hints:

Adding new files and folders is always done in OpenCms
Check the resource filter in Eclipse. It filters resources starting with a “.” (e.g. the .content folder or the .config file)