Skip to content

Home

Jump to bottom Edit New page
ccmitchellusa edited this page Oct 23, 2012 · 29 revisions

Welcome to the Dojo-Build-Factory wiki!

Goals

Simplify getting started with Dojo, by greatly decreasing the number of files and concepts needed to become productive. Gone are the days of sorting through 20,000 files and their dependencies that might be needed to use Dojo.

  • pre-defined, built/optimized layers for common sub packages of Dojo (a more logical mapping than the current fragmented projects. All Javascript files included in the pre optimized layers are removed from the build output, greatly reducing the overall number of JavaScript files needed to get started.

  • pre-packaged themes (css files & associated resources) for mobile and desktop which have individual .css files rolled up into aggregate CSS layer that's easy to include in HTML pages.

  • pre-packaged localization bundles (multiple bundles, one per language, per major sub package of dojo)

simplified dojo packaging using pre-build layers and themes concept

Packages

  • AMD Loader (minimal, 4k)

  • Full Core

  • Common UI F/W

  • Desktop UI (dijit)

  • Desktop Theme: Claro (claro)(cross-platform)(optimized)

  • Mobile UI (dojox/mobile)

  • Mobile Theme: iOS (iPad/iPhone)(optimized)

  • Mobile Theme: Android (2.1-3.x)(optimized)

  • Mobile Theme: Blackberry (OS6)(optimized)

  • Mobile Theme: Mobile One UI (future)(cross-platform)(optimized)

  • Vector Graphics API (dojox/gfx)

  • Business Charting (dojox/charting and it's dependencies, with a single default nice looking theme)

  • Grid (gridx)

  • Gauges (dgauge)

  • Calendar (dojox/calendar)

  • Treemap (dojox/treemap)

  • Language packs

Combinations of the above (or finer-grained groupings of modules will be created as needed)

Background

Problem

Custom builds for Dojo are an advanced development topic, and doing builds from scratch can be very difficult to achieve because of the many variables and considerable flexibility in build options. Unfortunately, custom builds are a necessity to reduce the number of network requests for resources (the number of resources requested is now higher, due to the finer granularity of modules in Dojo 1.7+)

Because creating builds are very difficult, many new users give up when hitting this complexity barrier.

Solution

As described above, we've created a "standard" set of pre-build layers for commonly used Dojo packages. These packages are a trade-off between development complexity and performance optimization, and are intended to be a good starting point when learning Dojo. Once you've learned how to use Dojo (as a black box set of components), you can take the Dojo Build Factory project and tweak it to optimize for your app. With this approach you'll be starting from a working baseline that you can mold to your application's needs.

Download Pre-built Distributions

The Fastest way to be productive--just use the layer files provided by downloading one of the pre-built distributions.

This allows you to treat Dojo as a black box. When you're just getting started, you just want something that works and don't want to learn all the intricate details of how we built it.

Using the pre-built packages will get you started and able to build web apps without having hundreds of Dojo files sent across the network.

Standard Layer Files

You will find the standard layer files inside the /dojo directory (ls *-layer.js). It's up to you to use only the layer files you need for your application. See the next section for how to use the layers.

  • dojo.js - Only the AMD loader (contains sync loader codepaths as well, due to a limitation with 1.7.1-2 i18n bundle handling by the AMD loader).
  • core-web-layer.js - Contains Base Dojo and Core Dojo modules as well as common abstract UI classes needed for Desktop and Mobile UI's. This layer will always be needed, unless you're just using Dojo AMD loader to load your own modules or other 3rd party AMD-compliant libraries (eg. with JQuery or JQuery Mobile).
  • dijit-layer.js - The Desktop UI layer (dijit). Contains the Dijit Desktop UI library. Requires core-web-layer.js.
  • mobile-ui-layer.js - The Mobile UI layer. Contains the Dojo Mobile UI library. Requires core-web-layer.js.
  • mobile-compat-layer.js - The desktop browser compatability layer. Use this layer in addition to the mobile-ui-layer to add IE8+ and FF4+ browser support for Dojo Mobile.
  • graphics-layer.js - The Vector Graphics API layer. Needed by Dojo Graphics packages like Charting and Gauges. Requires core-web-layer.js.
  • charting-layer.js - The Charting layer. Contains all standard Dojo chart types (except Gantt) plus a single default theme, "Julia" which is accessible. Requires graphics-layer.js.
  • dgauges-layer.js - Gauges layer contains the new Dojo 1.8 Gauge framework (works with Dojo 1.7) for interactive Analog and Bar gauges with default theme. Requires graphics-layer.js.
  • treemap-layer.js - Treemap layer contains the new Dojo 1.8 Treemap chart type (works with Dojo 1.7). Requires graphics-layer.js.
  • calendar-layer.js - Calendar layer contains the new Dojo 1.8 Calendar (works with Dojo 1.7). Requires core-web-layer.js.

In addition, the themes have all @imports processed, so that a reduced number of CSS files will be needed in your applications. TODO - Document Built Theme Structure

Using the Standard Layers

There are two ways to include the pre-build standard layer files into your applications.

Note: Layers and amd modules are two different things. A layer bundles a bunch of modules in a single resource to decrease the number of transactions required to load a set of modules. When a layer is loaded, the modules it contains are stored in the loader cache but not resolved until they are required. In other words, loading a layer does not require (in the sense of amd terminology) the modules it contains. Therefore you still have to require the modules even when using a layer, by following one of the methods explained below.

Option 1 - "script" includes

For this approach, you pre-load the layer files you want to use via script tags. With this approach, when you write your application, you still must use individual module names in your require and define dependency lists, but all modules in the layers get pre-cached into memory resulting in fewer network requests.

Option 2 - Nested AMD requires

With this approach, you also write your application using individual module names in your require and define dependency lists, but you use the require() function of the Dojo AMD loader to first load in layer files, and then load in your application code.

require(["core-web-layer","mobile-ui-layer"], function(){
    require(["dojox/mobile/View", ...], function(View, ...) {
    ...
    });
});

Another way to write the "nested require" approach is to use the dojoConfig deps/callback properties:

<script type="text/javascript">
var dojoConfig = {
    deps:["core-web-layer","mobile-ui-layer"],
    callback: function(){
        require(["dojox/mobile/View", ...], function(View, ...) {
        ...
        });
    },
    // other dojoConfig properties
    ...
};
</script>
<script type="text/javascript" src="./dojo/dojo.js"></script>

Basic Use Case

These prebuilt layers are great to use for demos, getting started scenarios, or within Phonegap to quickly put apps together treating Dojo as a set of prebuilt scripts that you use via api's and don't care about how the api's were implemented internally.

When You've Outgrown the Standard Layers

At some point, you may reach a need to optimize out every unused byte of your web application, and you know that there are a number of components included in the standard layers that you don't need. That's ok, Dojo Build Factory's layers are intended for starter scenarios--not for advanced optimization.

At this point, you can build upon our experience in creating working optimized builds by extracting and building this project, like we do (see the Build section below). Take the well-documented build scripts as a starting point to create your own, and if you find something missing from the build that would be useful to others, consider contributing back your modifications using the Issue tracker.

Building the Standard Dojo Layers

To build the standard profiles with the Build Factory, do the following:

  1. Install Apache Ant and make sure it's set up in your environment properly (1.7-1.8.x have been verified as working)
  2. cd into an empty directory that will hold the build factory and Dojo source trees.
  3. git clone https://github.com/pruzand/Dojo-Build-Factory.git This will create a directory Dojo-Build-Factory
  4. NOTE: THIS STEP SHOULD NO LONGER BE NECESSARY, AS THE CLOSURE COMPILER LIBRARY IS NOW INCLUDED Grab the most recent Closure Compiler zip from http://closure-compiler.googlecode.com/files/compiler-latest.zip
  5. NOTE: THIS STEP SHOULD NO LONGER BE NECESSARY, AS THE CLOSURE COMPILER LIBRARY IS NOW INCLUDED unzip compiler-latest.zip and copy compiler.jar into the build/lib directory.
    This will make the Closure Compiler Ant tasks available to the Build Factory.
    Closure Compiler is used to optimize out unwanted/unnecessary codepaths from Dojo modules.
  6. Copy the dojo, dijit, dojox and util source code trees for the 1.7+ version of Dojo you're building under the build/src directory. The util directory must be present for the build to work properly. Prune any subprojects from dojo/dijit/dojox directories that you know you don't want.
  7. Run the build from inside the build/ subdirectory...
    ant -DprofileFile="profile_filename"

where profile_filename is the name of your profile without the .js extension located in the build/profiles directory.

Additionaly, in case you want to generate flattened nls bundles for a given set of locales, you should also defined the value of the localeListParam build property at runtime. The -DlocaleListParam contains a comma-delimited list of locale identifiers. i18n resource string bundles for the locales specified will be built-into the layers. If not specified (the default) then a null value is set, which implies only the English default strings will be baked into layers and all remaining localized resource bundles will remain as separate bundles. If you do not want the extra localized bundles, you should remove them from the build results.

For example, the following command specifies to process the build/profiles/profile-1.8.js profile and generate flattened nls bundles for the ar, fr and it locales:

For the 1.8 branch of the build factory... ant -DprofileFile="profile-1.8" -DlocaleListParam="ar,fr,it"

For more information about the i18n support, see this page.

The build will run for approx 4-20 minutes depending on your system (faster with SSD). If all goes well, you should see the following message: BUILD SUCCESSFUL.

Build results are placed into two parallel directories under the build/result directory:

  • compressed - This directory contains the minified (unreadable) version of the built layers and modules.
    Use this tree for optimized runtime performance.
  • uncompressed - This directory contains the un-minified but built version of the layers and modules. Use this tree for src debugging issues in dojo modules.

Known Limitations & Additional Helpful Tweaks

  • The build profile builds the dojo.js AMD Loader with support for sync loader, due to 4-5 bugs with i18n that won't be fixed until 1.8 (or possibly 1.7.3). If you don't need i18n support, it's technically possible to get a much smaller dojo.js (i.e. the "Nano" loader) by specifying additional has properties to the closure compiler. Support will be added to build factory in the future once the AMD loader bugs with i18n have been fixed. TODO: Add details here

  • The build profile includes non-webkit browser code paths, so that IE, Firefox and Opera browser support is included. If you know you're targeting webkit-only browsers (most mobile devices plus Chrome and Safari on desktop), you can get further code reduction setting the "has" flags for webkit appropriately. TODO: Add details here

  • If you exported the full dojo, dijit, dojox, util dirs from svn under the build/src tree, there are many additional folder you can prune from the results tree after running the build command, such as many miscellaneous projects under dojox and additional theme directories you may not need. Some of the main dojo projects (such as GFX, Charting and Mobile) have some non-obvious runtime dependencies on some of the other dojox sub projects, so if you remove the dojox projects before build, the build may not pick up correct set of dependencies into the GFX/Charting/Mobile layers. It's better to remove the subproject dirs you think you don't need from dojox from the result trees after you've run the build.

  • The build profile builds & copies all desktop dijit themes into the results directory. If you only use claro theme, you can safely remove the following directories under the digit/themes directory (before or after build): [soria/, tundra/, nihilo/] resulting in additional disk footprint reduction.

Add a custom footer
Add a custom sidebar
Clone this wiki locally