Using OpenCms Maven
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.
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.
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.
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
The system project contains all OpenCms ressources beneath the /system folder (excluding custom modules).
The content project contains ordinary user content. By default it synchronizes all resources of the default site.
Creates and synchronizes organization units of the system.
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:
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.
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 <syncVFSPaths> 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.: <module>../template_vfs</module>)
- 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
- 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)