Caution: The documentation you are viewing is
for an older version of Zend Framework.
You can find the documentation of the current version at:
Zend_Dojo build layer support - Zend_Dojo
Dojo build layers provide a clean path from development to production when using Dojo for your UI layer. In development, you can have load-on-demand, rapid application prototyping; a build layer takes all Dojo dependencies and compiles them to a single file, optionally stripping whitespace and comments, and performing code heuristics to allow further minification of variable names. Additionally, it can do CSS minification.
This script is generally referred to as a "layer" script.
Then, in your application's layout, you'd instruct Dojo to load this module:
If you use Zend_Dojo to do this, you'd do the following:
But since Zend_Dojo aggregates your various dojo.require statements, how do you create your layer script? You could open each page and view the generated dojo.require statements, and cut and paste them into a layer script file manually.
However, a better solution exists: since Zend_Dojo aggregates this information already, you can simply pull that information and build your layer file. This is the purpose of Zend_Dojo_BuildLayer.
At its simplest, you simply instantiate Zend_Dojo_BuildLayer, feed it the view object and the name of your custom module layer, and have it generate the content of the layer file; it is up to you to then write it to disk.
When should you do the above? For it to work correctly, you need to do it after all view scripts and the layout have been rendered, to ensure that the dojo() helper is fully populated. One easy way to do so is using a front controller plugin, with a dispatchLoopShutdown() hook:
Note: Do not generate the layer on every page
It's tempting to generate the layer script on each and every page. However, this is resource intensive, as it must write to the disk on each page. Additionally, since the mtime of the file will keep changing, you will get no benefits of client-side caching. Write the file once.
The above functionality will suffice for most situations. For those needing more customization, a variety of options may be invoked.
While the view object may be passed during instantiation, you may also pass it in to an instance via the setView() method:
While the layer name may be passed during instantiation, you may also pass it in to an instance via the setLayerName() method:
dojo.addOnLoad is a useful utility for specifying actions that should trigger when the DOM has finished loading. The dojo() view helper can create these statements via its addOnLoad() and onLoadCapture() methods. In some cases, it makes sense to push these into your layer file instead of rendering them via your view scripts.
By default, these are not rendered; to enable them, pass the consumeOnLoad configuration key during instantiation:
Alternately, you can use the setConsumeOnLoad() method after instantiation:
One of the chief benefits of a Dojo module layer is that it facilitates the creation of a custom build. Zend_Dojo_BuildLayer has functionality for generate build profiles.
The simplest use case is to utilize the generateBuildProfile() method and send the output to a file:
Just like generating layers, you may want to automate this via a dispatchLoopShutdown() plugin hook; you could even simply modify the one shown for generating layers to read as follows:
As noted, with module layers, you should only create the file once.
The above functionality will suffice for most situations. The only way to customize build profile generation is to provide additional build profile options to utilize.
As an example, you may want to specify what type of optimizations should be performed, whether or not to optimize CSS files in the layer, whether or not to copy tests into the build, etc. For a listing of available options, you should read the » Dojo Build documentation and » accompanying documentation.
Setting these options is trivial: use the addProfileOption(), addProfileOptions(), or setProfileOptions() methods. The first method adds a single key and value option pair, the second will add several, and the third will overwrite any options with the list of key and value pairs provided.
By default, the following options are set:
You can pass in whatever key and value pairs you want; the Dojo build script will ignore those it does not understand.
As an example of setting options: