Module Development
This tutorial documents all the steps necessary to build a custom magnolia module (used to administer custom content). The standard tutorials available from Magnolia are very rudimentary. To truly create a working module, a lot of time needs to be spent on the sources for the various modules available from Magnolia. This guide will attempt to comprehensively document all the concepts and processes to be followed.
Magnolia uses maven as the build system, while we prefer ant with ivy as the build system. This tutorial will be based on ant+ivy to build the module. All material presented in this tutorial was derived from the new website project for The University Of Chicago Press.
Project Structure
The screen shot shows our standard project structure for building a custom module.
Configuration Files
ant.properties.master
A master configuration file that is checked into version control system. Each developer maintains a local version named ant.properties that contains developer environment specific properties (location of tomcat, groovy, jcr export files to be imported on module deployment, etc.).
ivy.xml
The standard ivy configuration file. Lists the dependencies for building the project, as well as exclude rules for jar files that are not necessary for building and deploying the module.
build.xml
The standard ant build file. Defines the various build tasks to build the various components for the project as well as the final module jar file.
Directories
bin
The bin directory contains scripts that are used by the project. For example, our bin directory contains the standard Tomcat setenv.sh file, a shell script used to create fresh Magnolia Author and Public instances from the downloaded Magnolia bundled war file, with some additional third-party modules along with our own module.
config
The config directory is the root directory under which all configuration files for the project including Magnolia module configuration directories and files. Examples of configuration files are standard Java and Groovy ConfigSlurper compatible files for configuring the runtime environment.
lib
The directory under which all dependencies are downloaded to. Also includes libraries that are not available from ivy or maven repositories, which are checked in to the version control system.
src
The root directory under which all source files are stored (both java class and web templates and resources). This directory is further sub-divided into:
- app - Contains the source files for the custom module we are building
- test - Contains the unit test source files for the module.
- web - Contains the freemarker templates as well as web resources (css and js files). We prefer to use subversion for revision control of templates and web resources as opposed to JCR versioning which is not available in Magnolia CE.