Skip to content
This repository

Dojo Web Builder

branch: master
README.md

Dojo Web Builder

The Dojo Web Builder provides a web interface to the dojo build system, allowing a user to generate custom toolkit builds using just their web browser.

This project contains the source code behind the hosted solution provided by The Dojo Toolkit at http://build.dojotoolkit.org.

The project is divided into two logical components, a front-end Dojo application and the backend RESTful interface to the build system. For usage details see the sections below.

Usage

Maven is used as the build manager for the project. It has been configured for quickstart with minimal configuration using an embedded Jetty plugin, see details below.

To connect the application, once running, point your web browser at http://localhost:8080/.

In addition, the application is not tied to these platforms, allowing you to build a WAR file and deploy to the application server of your choice.

Quickstart with Jetty

$ mvn -Ddojo.source=/some/path/to/dojo-1.6-source jetty:run

Quickstart with Jetty, using older Dojo release

$ mvn -Ddojo.source=/some/path/to/dojo-1.5-source -Ddojo.version=1.5.0 jetty:run

Quickstart with Jetty, setting build cache path

$ mvn -Dcachepath=/tmp/ -Ddojo.source=/some/path/to/dojo-source jetty:run

Configuration

Configurable application parameters are set using Java system properties. Users can modify these values using the -D command line argument. The only mandatory property is the dojo source location. Both the dojo.source and cachepath parameters support the use of environment variables, using the %env_name% format.

Mandatory Parameters

  • dojo.source - Directory location for the source release of the Dojo Toolkit version you want to build. Source folder must contain the correct version of dojo expected by the project, see dojo.version parameter below.

Optional Parameters

  • dojo.version - Change the version of the Dojo Toolkit being exposed by the project. Currently supported versions are: 1.6.0 (default), 1.5.0. Default version is set in the pom.xml file.

  • cachepath - Specify the custom build cache directory. By default, this is a different temporary directory each time the application is started. This value can also be set using a context parameter in the application's web.xml.

Supporting custom modules

The Dojo Web Builder supports serving up custom modules you've created alongside modules from the Dojo Toolkit. These modules will be exposed alongside the normal Dojo Toolkit modules in the web application, allowing users to create custom builds using your own modules. To configure the tool to serve up your local module files, follow the steps below...

Generate package descriptor for custom modules

$ cd src/main/resources/package_scripts/
$ rhino generateNewPackageMetaData.js ~/code/js/custom_modules_root/

Create package & version directory in package repository

$ mkdir ../../config/packages/custom_modules
$ mkdir ../../config/packages/custom_modules/1.0.0

Copy custom package descriptor to package repository

$ cp package.json ../../config/packages/custom_modules/1.0.0

Run Dojo Web Builder as normal

The src/main/config/packages/ directory contains the package meta-data files. Packages to be served are identified by the presence of a child directory. Each package directory must contain at least one version directory. Version directories contain the package modules descriptor files. Multiple versions of the same package are allowed, the web application automatically uses the most recent version.

To support a different version of Dojo, use the steps above to generate the package descriptor and place in a new version directory under the src/main/config/packages/dojo path. Then use the dojo.version parameter to modify the default version of Dojo served.

Deploying Multiple Versions of Dojo

The Dojo Web Builder also supports building for multiple versions of The Dojo Toolkit concurrently, allowing the user to choose the version they need dynamically. To achieve this, ensure you have downloaded local copies of all the versions of the toolkit you want to expose and then configure the application using the steps below....

Currently, package descriptor files are included for Dojo 1.8.0. If you need to expose an older version, please generate the package descriptor, as per the instructions above.

(Optional) Generate package descriptors for older versions of Dojo

See description above and package in src/main/config/packages/dojo/X.Y.Z/. Note 
that you need to uncomment the "DOJO-CONFIG" lines in generateNewPackageMetaData.js.

Fill in location parameter for all version packages

$ vim src/main/config/packages/dojo/${dojo.version}/package.json
$ <replace location field value with directory path>

Run Dojo Web Builder WITHOUT normal dojo.source parameter

$ mvn jetty:run

Development notes

Layout

The project uses Maven's standard directory layout to organise source files. Front-end application code lives in src/main/webapp and the backend API code lives in src/main/java.

Profiles

Maven profiles are used to assist with development, details below. To change the current profile, use the -PprofileName parameter when running the application.

  • standard (default) - Quick start using optimised client-side code layer, debug mode turned off.

  • release - Same as standard but triggers a full-rebuild of the client-side code, copying generated resources to JS directories before starting application.

  • dev - Debug mode turned on, uses source JavaScript modules uncompressed and unoptimised.

Use the -Pdebug mode during front-end development or module changes won't show up!

Testing

The project has an integration test suite used for verifying the API works as expected. These tests must be run against a deployed version of the application. To run the the tests against localhost, use the following commands

$ mvn -Ptest test

The following system parameters (-D) can be used to modify the API endpoint used for testing.

  • test.host - Hostname (default: "localhost")

  • test.port - Port (default: "8080")

  • test.path - Path to application (default: "")

  • test.protocol - Protocol (default: "http")

Dependencies

Backend

  • Java, version 1.5.0 or above

  • Application server, supporting servlet-2.5 container

Frontend

The Dojo Web Builder is tested on the following web browsers

  • Chrome 10+

  • Firefox 3.6+

  • IE7+

Feedback

File bug reports at http://bugs.dojotoolkit.org or contact James Thomas (thomasj @ twitter) for anything else.

TODO

  • Support AMD module format natively within build and analysis tools. At the moment we use a build time transformation.

  • Extract out Dojo dependent functionality, transforming the tool into a generic AMD module builder.

Something went wrong with that request. Please try again.