We make extensive use of the dojo toolkit in our Java web applications. An important step in the development process of a dojo web application is creating a custom dojo build. This post describes how we create custom dojo builds as part of our maven build process.
Why custom dojo builds
We use a lot of dijits and custom built dojo components in our web applications. By consequence, you can easily end up with a web application that uses dozens of components. In a non-cross domain dojo setup, each component is downloaded synchronously in order not to break the component dependency graph. No need to explain that your application will load slowly if you don’t take extra precautions (slow script error, anyone?). A custom dojo build optimizes the load and execution time of a dojo application (more details can be found in the dojo documentation).
We build, test, package and deploy our Java (web) applications with maven, and creating a custom dojo build is part of that build process.
Our maven approach
Preparing your maven project for a custom dojo builds consists of three steps:
- Obtaining a dojo source distribution
- Unpacking the source distribution
- Running the build script in the obtained dojo source distribution
Step 2 and 3 require configuring a plugin in the project’s POM file. We only use standard maven plugins, i.e. plugins that exist in the maven repository. We did not write custom plugins.
After executing these steps, you can do two things:
- Build a war file that contains a web application with a dojo production build
- Prepare Eclipse configuration files to run the application on a WTP enabled Eclipse IDE
The rest of this post describes the 5 points outlined above in greater detail. The build process is parametrized using parameters in the maven POM file. Each parameter is explained at the end of the post.
1. Obtaining a dojo source distribution
To be able to make a custom dojo build, you need a source distribution of dojo. Unfortunately, dojo source distributions are not released to the main maven repository. There are two options:
- Download the source distribution from the dojo download page using the wagon-maven-plugin. However, this plugin downloads the dojo source distribution each time you preform a maven build. Not very efficient.
- Download the dojo source build and install it manually in your local repository, or a maven repository server hosted by your own organization. Obtaining the source distribution of dojo then boils down to adding a maven dependency for the source distribution (explained in Step 2).
We only describe the second option. As soon as dojo source releases are also deployed to the main maven repository, your maven build process will download the source release automatically, provided the group and artifact ID are the same as the ones used in this post.
The command we use to install a dojo source distribution in our local maven repository is (for version 1.3.1):
mvn install:install-file \
To install the source distribution to a remote maven repository server, you must use the deploy plugin instead (mvn deploy:deploy-file).
2. Unpacking the source distribution
We also rename the directory name of the unpacked directory from the verbose “dojo-release-<version>-src” to the more convenient “dojo-<version>” (the name you want to give is configurable through the dojo.source.local.unpacked.location parameter):
3. Running the dojo custom build script
<!-- releaseDir: don't forget the slash at the end! -->
4. Building the WAR
After creating the custom dojo build, it must now be added to you web application’s WAR. This must be done by configuring the maven-war-plugin. The files created by the custom build must be added as additional web resources. The following POM excerpt adds additional web resources that are located in a directory defined by the webresources.location parameter. We put all generated web resources in that directory, which includes the files that are generated by the custom build process. Note that the unpacked dojo source distribution, which is in fact also a generated resource, is excluded from the war.
<!-- this is relative to the pom.xml directory -->
5. Generating eclipse project files
If you configure your POM file as described above, you can generate WTP compliant eclipse project files with the maven-eclipse-plugin.
mvn -Dwtpversion=2.0 -DdownloadSources=true -DdownloadJavadocs=true \
The maven-eclipse-plugin runs in the generate-resources phase of the maven lifecycle. The unpacking of the dojo source distribution is done in the generate-sources and process-sources phases of the maven build lifecycle, which both occur before the generate-resources phase (for more information, see the maven documentation on the build lifecycle.
Also, since version 2.6 of the maven-eclipse-plugin, all web resources that are defined in the maven-war-plugin section of your POM file are also added to the eclipse project. By consequence, the dojo source distribution you are using in your project is automatically deployed to the server that you’re using in your eclipse IDE for testing and debugging purposes.
Note that creating the custom build is done in the compile phase of the maven lifecycle, which occurs after the generate-resources phase. This means that the custom build won’t be available in your eclipse IDE unless you first compile the project using maven and refresh your project. The prerequisite for this to work is that the custom build must be placed somewhere inside the web resources directory that you have defined in the maven-war-plugin section.
In this post we have made extensive use of POM parameters. This section enumerates and explains all the parameters we’ve mentioned in earlier sections
<!-- files and directory locations -->
<!-- dojo custom build parameters -->
- webresources.location: the location where all generated webresources will be located. Since these resources are generated, they will end up in the target directory of your maven project
- dojo.version: the version of dojo you’re using in this maven project
- dojo.source.basename: the name of the directory that is created when you unpack the dojo source distribution. This is typically “dojo-release-<dojo.version>-src”.
- dojo.source.friendlyname: a less verbose name for the directory that holds the dojo source distribution. Here it is “dojo-<dojo.version>”
The remainder of the parameters is used to parametrize the dojo build script. For more information on custom builds, please see the dojo documentation on custom builds.
- dojo.build.action: what actions must be performed in the dojo build process. This is typically “clean, release”
- dojo.build.version: the version this dojo custom build will carry. We use a combination of the project’s artifact ID and version
- dojo.build.release.name: How will the release be named. This corresponds with the name of the directory in which the custom build will be placed
- dojo.build.release.location: the location where the custom build will be created. In this location a directory will be created with the name that you’ve configured in the dojo.build.release.name parameter.
There are obviously more parameters that you can pass to the build script, feel free to add your own.
It may require some tinkering before you get things working, or before things work the way you want. In the end, it’s a bit of juggling with files to get them all in the correct location. But once you’re there, you get dojo custom builds for free each time you do a maven build… provided you create a correct dojo build profile of course.