documentation/manual/en/module_specs/Zend_Dojo-BuildLayers.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.dojo.build-layers">
   4     <title>Zend_Dojo build layer support</title>
   5
   6     <sect2 id="zend.dojo.build-layers.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             Dojo build layers provide a clean path from development to
  11             production when using Dojo for your UI layer. In development, you
  12             can have load-on-demand, rapid application prototyping; a build
  13             layer takes all Dojo dependencies and compiles them to a single
  14             file, optionally stripping whitespace and comments, and performing
  15             code heuristics to allow further minification of variable names.
  16             Additionally, it can do <acronym>CSS</acronym> minification.
  17         </para>
  18
  19         <para>
  20             In order to create a build layer, you would traditionally create a
  21             JavaScript file that has <command>dojo.require</command> statements for
  22             each dependency, and optionally some additional code that might run
  23             when the script is loaded. As an example:
  24         </para>
  25
  26         <programlisting language="javascript"><![CDATA[
  27 dojo.provide("custom.main");
  28
  29 dojo.require("dijit.layout.TabContainer");
  30 dojo.require("dijit.layout.ContentPane");
  31 dojo.require("dijit.form.Form");
  32 dojo.require("dijit.form.Button");
  33 dojo.require("dijit.form.TextBox");
  34 ]]></programlisting>
  35
  36         <para>
  37             This script is generally referred to as a "layer" script.
  38         </para>
  39
  40         <para>
  41             Then, in your application's layout, you'd instruct Dojo to load this
  42             module:
  43         </para>
  44
  45         <programlisting language="html"><![CDATA[
  46 <html>
  47 <head>
  48     <script type="text/javascript" src="/js/dojo/dojo.js"></script>
  49     <script type="text/javascript">
  50         dojo.registerModulePath("custom", "../custom/");
  51         dojo.require("custom.main");
  52     </script>
  53 ]]></programlisting>
  54
  55         <para>
  56             If you use <classname>Zend_Dojo</classname> to do this, you'd do the
  57             following:
  58         </para>
  59
  60         <programlisting language="php"><![CDATA[
  61 $view->dojo()->registerModulePath('custom', '../custom/')
  62              ->requireModule('custom.main');
  63 ]]></programlisting>
  64
  65         <para>
  66             But since <classname>Zend_Dojo</classname> aggregates your various
  67             <command>dojo.require</command> statements, how do you create your layer
  68             script? You could open each page and view the generated
  69             <command>dojo.require</command> statements, and cut and paste them into a
  70             layer script file manually.
  71         </para>
  72
  73         <para>
  74             However, a better solution exists: since
  75             <classname>Zend_Dojo</classname> aggregates this information
  76             already, you can simply pull that information and build your layer
  77             file. This is the purpose of
  78             <classname>Zend_Dojo_BuildLayer</classname>.
  79         </para>
  80     </sect2>
  81
  82     <sect2 id="zend.dojo.build-layers.usage">
  83         <title>Generating Custom Module Layers with Zend_Dojo_BuildLayer</title>
  84
  85         <para>
  86             At its simplest, you simply instantiate
  87             <classname>Zend_Dojo_BuildLayer</classname>, feed it the view object
  88             and the name of your custom module layer, and have it generate the
  89             content of the layer file; it is up to you to then write it to disk.
  90         </para>
  91
  92         <para>
  93             As an example, let's say you wanted to create the module layer
  94             "<filename>custom.main</filename>". Assuming you follow the recommended project
  95             directory structure, and that you are storing your JavaScript files under
  96             <filename>public/js/</filename>, you could do the following:
  97         </para>
  98
  99         <programlisting language="php"><![CDATA[
 100 $build = new Zend_Dojo_BuildLayer(array(
 101     'view'      => $view,
 102     'layerName' => 'custom.main',
 103 ));
 104
 105 $layerContents = $build->generateLayerScript();
 106 $filename      = APPLICATION_PATH . '/../public/js/custom/main.js';
 107 if (!dir_exists(dirname($filename))) {
 108     mkdir(dirname($filename));
 109 }
 110 file_put_contents($filename, $layerContents);
 111 ]]></programlisting>
 112
 113         <para>
 114             When should you do the above? For it to work correctly, you need to
 115             do it after all view scripts and the layout have been rendered, to
 116             ensure that the <methodname>dojo()</methodname> helper is fully populated. One
 117             easy way to do so is using a front controller plugin, with a
 118             <methodname>dispatchLoopShutdown()</methodname> hook:
 119         </para>
 120
 121         <programlisting language="php"><![CDATA[
 122 class App_Plugin_DojoLayer extends Zend_Controller_Plugin_Abstract
 123 {
 124     public $layerScript = APPLICATION_PATH . '/../public/js/custom/main.js';
 125     protected $_build;
 126
 127     public function dispatchLoopShutdown()
 128     {
 129         if (!file_exists($this->layerScript)) {
 130             $this->generateDojoLayer();
 131         }
 132     }
 133
 134     public function getBuild()
 135     {
 136         $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper(
 137             'ViewRenderer'
 138         );
 139         $viewRenderer->initView();
 140         if (null === $this->_build) {
 141             $this->_build = new Zend_Dojo_BuildLayer(array(
 142                 'view'      => $viewRenderer->view,
 143                 'layerName' => 'custom.main',
 144             ));
 145         }
 146         return $this->_build;
 147     }
 148
 149     public function generateDojoLayer()
 150     {
 151         $build = $this->getBuild();
 152         $layerContents = $build->generateLayerScript();
 153         if (!dir_exists(dirname($this->layerScript))) {
 154             mkdir(dirname($this->layerScript));
 155         }
 156         file_put_contents($this->layerScript, $layerContents);
 157     }
 158 }
 159 ]]></programlisting>
 160
 161         <note>
 162             <title>Do not generate the layer on every page</title>
 163
 164             <para>
 165                 It's tempting to generate the layer script on each and every
 166                 page. However, this is resource intensive, as it must write to
 167                 the disk on each page. Additionally, since the mtime of the file
 168                 will keep changing, you will get no benefits of client-side
 169                 caching. Write the file once.
 170             </para>
 171         </note>
 172
 173         <sect3 id="zend.dojo.build-layers.usage.options">
 174             <title>BuildLayer options</title>
 175
 176             <para>
 177                 The above functionality will suffice for most situations. For
 178                 those needing more customization, a variety of options may be
 179                 invoked.
 180             </para>
 181
 182             <sect4 id="zend.dojo.build-layers.usage.options.view">
 183                 <title>Setting the view object</title>
 184
 185                 <para>
 186                     While the view object may be passed during instantiation,
 187                     you may also pass it in to an instance via the
 188                     <methodname>setView()</methodname> method:
 189                 </para>
 190
 191                 <programlisting language="php"><![CDATA[
 192 $build->setView($view);
 193 ]]></programlisting>
 194             </sect4>
 195
 196             <sect4 id="zend.dojo.build-layers.usage.options.layername">
 197                 <title>Setting the layer name</title>
 198
 199                 <para>
 200                     While the layer name may be passed during instantiation,
 201                     you may also pass it in to an instance via the
 202                     <methodname>setLayerName()</methodname> method:
 203                 </para>
 204
 205                 <programlisting language="php"><![CDATA[
 206 $build->setLayerName("custom.main");
 207 ]]></programlisting>
 208             </sect4>
 209
 210             <sect4 id="zend.dojo.build-layers.usage.options.onload">
 211                 <title>Including onLoad events in the generated layer</title>
 212
 213                 <para>
 214                     <command>dojo.addOnLoad</command> is a useful utility for
 215                     specifying actions that should trigger when the <acronym>DOM</acronym> has
 216                     finished loading. The <methodname>dojo()</methodname> view helper can
 217                     create these statements via its
 218                     <methodname>addOnLoad()</methodname> and
 219                     <methodname>onLoadCapture()</methodname> methods. In some
 220                     cases, it makes sense to push these into your layer file
 221                     instead of rendering them via your view scripts.
 222                 </para>
 223
 224                 <para>
 225                     By default, these are not rendered; to enable them, pass the
 226                     <property>consumeOnLoad</property> configuration key during
 227                     instantiation:
 228                 </para>
 229
 230                 <programlisting language="php"><![CDATA[
 231 $build = new Zend_Dojo_BuildLayer(array(
 232     'view'          => $view,
 233     'layerName'     => 'custom.main',
 234     'consumeOnLoad' => true,
 235 ));
 236 ]]></programlisting>
 237
 238                 <para>
 239                     Alternately, you can use the
 240                     <methodname>setConsumeOnLoad()</methodname> method after
 241                     instantiation:
 242                 </para>
 243
 244                 <programlisting language="php"><![CDATA[
 245 $build->setConsumeOnLoad(true);
 246 ]]></programlisting>
 247             </sect4>
 248
 249             <sect4 id="zend.dojo.build-layers.usage.options.javascript">
 250                 <title>Including captured JavaScript in the generated layer</title>
 251
 252                 <para>
 253                     The <methodname>dojo()</methodname> view helper includes methods for
 254                     capturing arbitrary JavaScript to include in the
 255                     &lt;script&gt; tag containing the various
 256                     <command>dojo.require</command> and <command>dojo.addOnLoad</command>
 257                     statements. This can be useful when creating default data
 258                     stores or globally scoped objects used throughout your
 259                     application.
 260                 </para>
 261
 262                 <para>
 263                     By default, these are not rendered; to enable them, pass the
 264                     <property>consumeJavascript</property> configuration key during
 265                     instantiation:
 266                 </para>
 267
 268                 <programlisting language="php"><![CDATA[
 269 $build = new Zend_Dojo_BuildLayer(array(
 270     'view'              => $view,
 271     'layerName'         => 'custom.main',
 272     'consumeJavascript' => true,
 273 ));
 274 ]]></programlisting>
 275
 276                 <para>
 277                     Alternately, you can use the
 278                     <methodname>setConsumeJavascript()</methodname> method after
 279                     instantiation:
 280                 </para>
 281
 282                 <programlisting language="php"><![CDATA[
 283 $build->setConsumeJavascript(true);
 284 ]]></programlisting>
 285             </sect4>
 286         </sect3>
 287     </sect2>
 288
 289     <sect2 id="zend.dojo.build-layers.profiles">
 290         <title>Generating Build Profiles with Zend_Dojo_BuildLayer</title>
 291
 292         <para>
 293             One of the chief benefits of a Dojo module layer is that it
 294             facilitates the creation of a custom build.
 295             <classname>Zend_Dojo_BuildLayer</classname> has functionality for
 296             generate build profiles.
 297         </para>
 298
 299         <para>
 300             The simplest use case is to utilize the
 301             <methodname>generateBuildProfile()</methodname> method and send the
 302             output to a file:
 303         </para>
 304
 305         <programlisting language="php"><![CDATA[
 306 $build = new Zend_Dojo_BuildLayer(array(
 307     'view'      => $view,
 308     'layerName' => 'custom.main',
 309 ));
 310
 311 $profile   = $build->generateBuildProfile();
 312 $filename  = APPLICATION_PATH . '/../misc/scripts/custom.profile.js';
 313 file_put_contents($filename, $profile);
 314 ]]></programlisting>
 315
 316         <para>
 317             Just like generating layers, you may want to automate this via a
 318             <methodname>dispatchLoopShutdown()</methodname> plugin hook; you
 319             could even simply modify the one shown for generating layers to read
 320             as follows:
 321         </para>
 322
 323         <programlisting language="php"><![CDATA[
 324 class App_Plugin_DojoLayer extends Zend_Controller_Plugin_Abstract
 325 {
 326     public $layerScript  = APPLICATION_PATH
 327                          . '/../public/js/custom/main.js';
 328     public $buildProfile = APPLICATION_PATH
 329                          . '/../misc/scripts/custom.profile.js';
 330     protected $_build;
 331
 332     public function dispatchLoopShutdown()
 333     {
 334         if (!file_exists($this->layerScript)) {
 335             $this->generateDojoLayer();
 336         }
 337         if (!file_exists($this->buildProfile)) {
 338             $this->generateBuildProfile();
 339         }
 340     }
 341
 342     public function generateDojoLayer() { /* ... */ }
 343
 344     public function generateBuildProfile()
 345     {
 346         $profile = $this->getBuild()->generateBuildProfile();
 347         file_put_contents($this->buildProfile, $profile);
 348     }
 349
 350 }
 351 ]]></programlisting>
 352
 353         <para>
 354             As noted, with module layers, you should only create the file once.
 355         </para>
 356
 357         <sect3 id="zend.dojo.build-layers.profiles.options">
 358             <title>Build Profile options</title>
 359
 360             <para>
 361                 The above functionality will suffice for most situations. The
 362                 only way to customize build profile generation is to provide
 363                 additional build profile options to utilize.
 364             </para>
 365
 366             <para>
 367                 As an example, you may want to specify what type of
 368                 optimizations should be performed, whether or not to optimize
 369                 <acronym>CSS</acronym> files in the layer, whether or not to copy tests into the
 370                 build, etc. For a listing of available options, you should read
 371                 the <ulink url="http://docs.dojocampus.org/build/index">Dojo
 372                     Build documentation</ulink> and <ulink
 373                     url="http://dojotoolkit.org/reference-guide/dojo/index.html#package-system">accompanying
 374                 documentation</ulink>.
 375             </para>
 376
 377             <para>
 378                 Setting these options is trivial: use the
 379                 <methodname>addProfileOption()</methodname>,
 380                 <methodname>addProfileOptions()</methodname>, or
 381                 <methodname>setProfileOptions()</methodname> methods. The first
 382                 method adds a single key and value option pair, the second will add
 383                 several, and the third will overwrite any options with the list
 384                 of key and value pairs provided.
 385             </para>
 386
 387             <para>
 388                 By default, the following options are set:
 389             </para>
 390
 391             <programlisting language="javascript"><![CDATA[
 392 {
 393     action:        "release",
 394     optimize:      "shrinksafe",
 395     layerOptimize: "shrinksafe",
 396     copyTests:     false,
 397     loader:        "default",
 398     cssOptimize:   "comments"
 399 }
 400 ]]></programlisting>
 401
 402             <para>
 403                 You can pass in whatever key and value pairs you want; the Dojo
 404                 build script will ignore those it does not understand.
 405             </para>
 406
 407             <para>
 408                 As an example of setting options:
 409             </para>
 410
 411             <programlisting language="php"><![CDATA[
 412 // A single option:
 413 $build->addProfileOption('version', 'zend-1.3.1');
 414
 415 // Several options:
 416 $build->addProfileOptions(array(
 417     'loader'   => 'xdomain',
 418     'optimize' => 'packer',
 419 ));
 420
 421 // Or overwrite options:
 422 $build->setProfileOptions(array(
 423     'version'  => 'custom-1.3.1',
 424     'loader'   => 'shrinksafe',
 425     'optimize' => 'shrinksafe',
 426 ));
 427 ]]></programlisting>
 428         </sect3>
 429     </sect2>
 430 </sect1>