documentation/manual/en/module_specs/Zend_Dojo-View-Dojo.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.dojo.view.dojo">
   4     <title>dojo() View Helper</title>
   5
   6     <para>
   7         The <methodname>dojo()</methodname> view helper is intended to simplify setting up
   8         the Dojo environment, including the following responsibilities:
   9     </para>
  10
  11     <itemizedlist>
  12         <listitem>
  13             <para>
  14                 Specifying either a <acronym>CDN</acronym> or a local path to a Dojo install.
  15             </para>
  16         </listitem>
  17
  18         <listitem><para>Specifying paths to custom Dojo modules.</para></listitem>
  19         <listitem><para>Specifying <command>dojo.require</command> statements.</para></listitem>
  20         <listitem><para>Specifying dijit stylesheet themes to use.</para></listitem>
  21
  22         <listitem>
  23             <para>Specifying <command>dojo.addOnLoad()</command> events.</para>
  24         </listitem>
  25     </itemizedlist>
  26
  27     <para>
  28         The <methodname>dojo()</methodname> view helper implementation is an example of a
  29         placeholder implementation. The data set in it persists between view
  30         objects and may be directly echoed from your layout script.
  31     </para>
  32
  33     <example id="zend.dojo.view.dojo.usage">
  34         <title>dojo() View Helper Usage Example</title>
  35
  36         <para>
  37             For this example, let's assume the developer will be using Dojo from
  38             a local path, will require several dijits, and will be
  39             utilizing the Tundra dijit theme.
  40         </para>
  41
  42         <para>
  43             On many pages, the developer may not utilize Dojo at all. So, we
  44             will first focus on a view script where Dojo is needed and then on the
  45             layout script, where we will setup some of the Dojo environment and
  46             then render it.
  47         </para>
  48
  49         <para>
  50             First, we need to tell our view object to use the Dojo view helper
  51             paths. This can be done in your bootstrap or an early-running
  52             plugin; simply grab your view object and execute the following:
  53         </para>
  54
  55         <programlisting language="php"><![CDATA[
  56 $view->addHelperPath('Zend/Dojo/View/Helper/', 'Zend_Dojo_View_Helper');
  57 ]]></programlisting>
  58
  59         <para>
  60             Next, the view script. In this case, we're going to specify
  61             that we will be using a FilteringSelect -- which will consume a
  62             custom store based on QueryReadStore, which we'll call
  63             'PairedStore' and store in our 'custom' module.
  64         </para>
  65
  66         <programlisting language="php"><![CDATA[
  67 <?php // setup data store for FilteringSelect ?>
  68 <div dojoType="custom.PairedStore" jsId="stateStore"
  69     url="/data/autocomplete/type/state/format/ajax"
  70     requestMethod="get"></div>
  71
  72 <?php // Input element: ?>
  73 State: <input id="state" dojoType="dijit.form.FilteringSelect"
  74     store="stateStore" pageSize="5" />
  75
  76 <?php // setup required dojo elements:
  77 $this->dojo()->enable()
  78              ->setDjConfigOption('parseOnLoad', true)
  79              ->registerModulePath('custom', '../custom/')
  80              ->requireModule('dijit.form.FilteringSelect')
  81              ->requireModule('custom.PairedStore'); ?>
  82 ]]></programlisting>
  83
  84         <para>
  85             In our layout script, we'll then check to see if Dojo is enabled,
  86             and, if so, we'll do some more general configuration and assemble
  87             it:
  88         </para>
  89
  90         <programlisting language="php"><![CDATA[
  91 <?php echo $this->doctype() ?>
  92 <html>
  93 <head>
  94     <?php echo $this->headTitle() ?>
  95     <?php echo $this->headMeta() ?>
  96     <?php echo $this->headLink() ?>
  97     <?php echo $this->headStyle() ?>
  98 <?php if ($this->dojo()->isEnabled()){
  99     $this->dojo()->setLocalPath('/js/dojo/dojo.js')
 100                  ->addStyleSheetModule('dijit.themes.tundra');
 101     echo $this->dojo();
 102    }
 103 ?>
 104     <?php echo $this->headScript() ?>
 105 </head>
 106 <body class="tundra">
 107     <?php echo $this->layout()->content ?>
 108     <?php echo $this->inlineScript() ?>
 109 </body>
 110 </html>
 111 ]]></programlisting>
 112
 113         <para>
 114             At this point, you only need to ensure that your files are in the
 115             correct locations and that you've created the end point action for
 116             your FilteringSelect!
 117         </para>
 118     </example>
 119
 120     <note>
 121         <title>UTF-8 encoding used by default</title>
 122
 123         <para>
 124             By default, Zend Framework uses <acronym>UTF-8</acronym> as its default encoding, and,
 125             specific to this case, <classname>Zend_View</classname> does as well. Character encoding
 126             can be set differently on the view object itself using the
 127             <methodname>setEncoding()</methodname> method (or the <property>encoding</property>
 128             instantiation parameter). However, since <classname>Zend_View_Interface</classname> does
 129             not define accessors for encoding, it's possible that if you are using a custom view
 130             implementation with the Dojo view helper, you will not have a
 131             <methodname>getEncoding()</methodname> method, which is what the view helper uses
 132             internally for determining the character set in which to encode.
 133         </para>
 134
 135         <para>
 136             If you do not want to utilize <acronym>UTF-8</acronym> in such a situation, you will
 137             need to implement a <methodname>getEncoding()</methodname> method in your custom view
 138             implementation.
 139         </para>
 140     </note>
 141
 142     <sect3 id="zend.dojo.view.dojo.declarative">
 143         <title>Programmatic and Declarative Usage of Dojo</title>
 144
 145         <para>
 146             Dojo allows both <emphasis>declarative</emphasis> and
 147             <emphasis>programmatic</emphasis> usage of many of its features.
 148             <emphasis>Declarative</emphasis> usage uses standard <acronym>HTML</acronym> elements
 149             with non-standard attributes that are parsed when the page is
 150             loaded. While this is a powerful and simple syntax to utilize, for
 151             many developers this can cause issues with page validation.
 152         </para>
 153
 154         <para>
 155             <emphasis>Programmatic</emphasis> usage allows the developer to
 156             decorate existing elements by pulling them by ID or <acronym>CSS</acronym> selectors
 157             and passing them to the appropriate object constructors in Dojo.
 158             Because no non-standard <acronym>HTML</acronym> attributes are used, pages continue to
 159             validate.
 160         </para>
 161
 162         <para>
 163             In practice, both use cases allow for graceful degradation when
 164             javascript is disabled or the various Dojo script resources are
 165             unreachable. To promote standards and document validation,
 166             Zend Framework uses programmatic usage by default; the various view
 167             helpers will generate javascript and push it to the
 168             <methodname>dojo()</methodname> view helper for inclusion when rendered.
 169         </para>
 170
 171         <para>
 172             Developers using this technique may also wish to explore the option
 173             of writing their own programmatic decoration of the page. One
 174             benefit would be the ability to specify handlers for dijit events.
 175         </para>
 176
 177         <para>
 178             To allow this, as well as the ability to use declarative syntax,
 179             there are a number of static methods available to set this behavior
 180             globally.
 181         </para>
 182
 183         <example id="zend.dojo.view.dojo.declarative.usage">
 184             <title>Specifying Declarative and Programmatic Dojo Usage</title>
 185
 186             <para>
 187                 To specify declarative usage, simply call the static
 188                 <methodname>setUseDeclarative()</methodname> method:
 189             </para>
 190
 191             <programlisting language="php"><![CDATA[
 192 Zend_Dojo_View_Helper_Dojo::setUseDeclarative();
 193 ]]></programlisting>
 194
 195             <para>
 196                 If you decide instead to use programmatic usage, call the static
 197                 <methodname>setUseProgrammatic()</methodname> method:
 198             </para>
 199
 200             <programlisting language="php"><![CDATA[
 201 Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();
 202 ]]></programlisting>
 203
 204             <para>
 205                 Finally, if you want to create your own programmatic rules, you
 206                 should specify programmatic usage, but pass in the value '-1';
 207                 in this situation, no javascript for decorating any dijits used
 208                 will be created.
 209             </para>
 210
 211             <programlisting language="php"><![CDATA[
 212 Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);
 213 ]]></programlisting>
 214         </example>
 215     </sect3>
 216
 217     <sect3 id="zend.dojo.view.dojo.themes">
 218         <title>Themes</title>
 219
 220         <para>
 221             Dojo allows the creation of themes for its dijits (widgets). You may
 222             select one by passing in a module path:
 223         </para>
 224
 225         <programlisting language="php"><![CDATA[
 226 $view->dojo()->addStylesheetModule('dijit.themes.tundra');
 227 ]]></programlisting>
 228
 229         <para>
 230             The module path is discovered by using the character '.' as a
 231             directory separator and using the last value in the list as the name
 232             of the <acronym>CSS</acronym> file in that theme directory to use; in the example
 233             above, Dojo will look for the theme in
 234             '<filename>dijit/themes/tundra/tundra.css</filename>'.
 235         </para>
 236
 237         <para>
 238             When using a theme, it is important to remember to pass the theme
 239             class to, at the least, a container surrounding any dijits you are
 240             using; the most common use case is to pass it in the body:
 241         </para>
 242
 243         <programlisting language="html"><![CDATA[
 244 <body class="tundra">
 245 ]]></programlisting>
 246     </sect3>
 247
 248     <sect3 id="zend.dojo.view.dojo.layers">
 249         <title>Using Layers (Custom Builds)</title>
 250
 251         <para>
 252             By default, when you use a <command>dojo.require</command> statement, dojo will make a
 253             request back to the server to grab the appropriate javascript file.
 254             If you have many dijits in place, this results in many requests to
 255             the server -- which is not optimal.
 256         </para>
 257
 258         <para>
 259             Dojo's answer to this is to provide the ability to create
 260             <emphasis>custom builds</emphasis>. Builds do several things:
 261         </para>
 262
 263         <itemizedlist>
 264             <listitem>
 265                 <para>
 266                     Groups required files into <emphasis>layers</emphasis>; a layer
 267                     lumps all required files into a single JS file. (Hence the name
 268                     of this section.)
 269                 </para>
 270             </listitem>
 271
 272             <listitem>
 273                 <para>
 274                     "Interns" non-javascript files used by dijits (typically,
 275                     template files). These are also grouped in the same JS file as
 276                     the layer.
 277                 </para>
 278             </listitem>
 279
 280             <listitem>
 281                 <para>
 282                     Passes the file through ShrinkSafe, which strips whitespace and
 283                     comments, as well as shortens variable names.
 284                 </para>
 285             </listitem>
 286         </itemizedlist>
 287
 288         <para>
 289             Some files can not be layered, but the build process will create a
 290             special release directory with the layer file and all other files.
 291             This allows you to have a slimmed-down distribution customized for
 292             your site or application needs.
 293         </para>
 294
 295         <para>
 296             To use a layer, the <methodname>dojo()</methodname> view helper has a
 297             <methodname>addLayer()</methodname> method for adding paths to required layers:
 298         </para>
 299
 300         <programlisting language="html"><![CDATA[
 301 $view->dojo()->addLayer('/js/foo/foo.js');
 302 ]]></programlisting>
 303
 304         <para>
 305             For more information on creating custom builds, please <ulink
 306                 url="http://dojotoolkit.org/book/dojo-book-0-9/part-4-meta-dojo/package-system-and-custom-builds">refer
 307                 to the Dojo build documentation</ulink>.
 308         </para>
 309     </sect3>
 310
 311     <sect3 id="zend.dojo.view.dojo.methods">
 312         <title>Methods Available</title>
 313
 314         <para>
 315             The <methodname>dojo()</methodname> view helper always returns an instance of
 316             the dojo placeholder container. That container object has the
 317             following methods available:
 318         </para>
 319
 320         <itemizedlist>
 321             <listitem>
 322                 <para>
 323                     <methodname>setView(Zend_View_Interface $view)</methodname>: set a view instance
 324                     in the container.
 325                 </para>
 326             </listitem>
 327
 328             <listitem>
 329                 <para><methodname>enable()</methodname>: explicitly enable Dojo integration.</para>
 330             </listitem>
 331
 332             <listitem>
 333                 <para><methodname>disable()</methodname>: disable Dojo integration.</para>
 334             </listitem>
 335
 336             <listitem>
 337                 <para>
 338                     <methodname>isEnabled()</methodname>: determine whether or not Dojo integration
 339                     is enabled.
 340                 </para>
 341             </listitem>
 342
 343             <listitem>
 344                 <para>
 345                     <methodname>requireModule($module)</methodname>: setup a
 346                     <command>dojo.require</command> statement.
 347                 </para>
 348             </listitem>
 349
 350             <listitem>
 351                 <para>
 352                     <methodname>getModules()</methodname>: determine what modules have been
 353                     required.
 354                 </para>
 355             </listitem>
 356
 357             <listitem>
 358                 <para>
 359                     <methodname>registerModulePath($module, $path)</methodname>:
 360                     register a custom Dojo module path.
 361                 </para>
 362             </listitem>
 363
 364             <listitem>
 365                 <para>
 366                     <methodname>getModulePaths()</methodname>: get list of registered module paths.
 367                 </para>
 368             </listitem>
 369
 370             <listitem>
 371                 <para>
 372                     <methodname>addLayer($path)</methodname>: add a layer (custom build) path to
 373                     use.
 374                 </para>
 375             </listitem>
 376
 377             <listitem>
 378                 <para>
 379                     <methodname>getLayers()</methodname>: get a list of all registered layer paths
 380                     (custom builds).
 381                 </para>
 382             </listitem>
 383
 384             <listitem>
 385                 <para>
 386                     <methodname>removeLayer($path)</methodname>: remove the layer
 387                     that matches <varname>$path</varname> from the list of registered
 388                     layers (custom builds).
 389                 </para>
 390             </listitem>
 391
 392             <listitem>
 393                 <para>
 394                     <methodname>setCdnBase($url)</methodname>: set the base <acronym>URL</acronym>
 395                     for a <acronym>CDN</acronym>; typically, one of the
 396                     <constant>Zend_Dojo::CDN_BASE_AOL</constant> or
 397                     <constant>Zend_Dojo::CDN_BASE_GOOGLE</constant>, but it only needs
 398                     to be the <acronym>URL</acronym> string prior to the version number.
 399                 </para>
 400             </listitem>
 401
 402             <listitem>
 403                 <para>
 404                     <methodname>getCdnBase()</methodname>: retrieve the base <acronym>CDN</acronym>
 405                     url to utilize.
 406                 </para>
 407             </listitem>
 408
 409             <listitem>
 410                 <para>
 411                     <methodname>setCdnVersion($version = null)</methodname>: set
 412                     which version of Dojo to utilize from the <acronym>CDN</acronym>.
 413                 </para>
 414             </listitem>
 415
 416             <listitem>
 417                 <para>
 418                     <methodname>getCdnVersion()</methodname>: retrieve what
 419                     version of Dojo from the <acronym>CDN</acronym> will be used.
 420                 </para>
 421             </listitem>
 422
 423             <listitem>
 424                 <para>
 425                     <methodname>setCdnDojoPath($path)</methodname>: set the relative
 426                     path to the <filename>dojo.js</filename> or <filename>dojo.xd.js</filename>
 427                     file on a <acronym>CDN</acronym>; typically, one of the
 428                     <constant>Zend_Dojo::CDN_DOJO_PATH_AOL</constant> or
 429                     <constant>Zend_Dojo::CDN_DOJO_PATH_GOOGLE</constant>, but it only
 430                     needs to be the path string following the version number.
 431                 </para>
 432             </listitem>
 433
 434             <listitem>
 435                 <para>
 436                     <methodname>getCdnDojoPath()</methodname>: retrieve the last path segment of the
 437                     <acronym>CDN</acronym> url pointing to the <filename>dojo.js</filename> file.
 438                 </para>
 439             </listitem>
 440
 441             <listitem>
 442                 <para>
 443                     <methodname>useCdn()</methodname>: tell the container to
 444                     utilize the <acronym>CDN</acronym>; implicitly enables integration.
 445                 </para>
 446             </listitem>
 447
 448             <listitem>
 449                 <para>
 450                     <methodname>setLocalPath($path)</methodname>: tell the container
 451                     the path to a local Dojo install (should be a path relative
 452                     to the server, and contain the <filename>dojo.js</filename> file itself);
 453                     implicitly enables integration.
 454                 </para>
 455             </listitem>
 456
 457             <listitem>
 458                 <para>
 459                     <methodname>getLocalPath()</methodname>: determine what local
 460                     path to Dojo is being used.
 461                 </para>
 462             </listitem>
 463
 464             <listitem>
 465                 <para>
 466                     <methodname>useLocalPath()</methodname>: is the integration
 467                     utilizing a Dojo local path?
 468                 </para>
 469             </listitem>
 470
 471             <listitem>
 472                 <para>
 473                     <methodname>setDjConfig(array $config)</methodname>: set
 474                     dojo or dijit configuration values (expects assoc array).
 475                 </para>
 476             </listitem>
 477
 478             <listitem>
 479                 <para>
 480                     <methodname>setDjConfigOption($option, $value)</methodname>: set
 481                     a single dojo or dijit configuration value.
 482                 </para>
 483             </listitem>
 484
 485             <listitem>
 486                 <para>
 487                     <methodname>getDjConfig()</methodname>: get all dojo or dijit configuration
 488                     values.
 489                 </para>
 490             </listitem>
 491
 492             <listitem>
 493                 <para>
 494                     <methodname>getDjConfigOption($option, $default = null)</methodname>: get a
 495                     single dojo or dijit configuration value.
 496                 </para>
 497             </listitem>
 498
 499             <listitem>
 500                 <para>
 501                     <methodname>addStylesheetModule($module)</methodname>: add a
 502                     stylesheet based on a module theme.
 503                 </para>
 504             </listitem>
 505
 506             <listitem>
 507                 <para>
 508                     <methodname>getStylesheetModules()</methodname>: get stylesheets
 509                     registered as module themes.
 510                 </para>
 511             </listitem>
 512
 513             <listitem>
 514                 <para>
 515                     <methodname>addStylesheet($path)</methodname>: add a local
 516                     stylesheet for use with Dojo.
 517                 </para>
 518             </listitem>
 519
 520             <listitem>
 521                 <para><methodname>getStylesheets()</methodname>: get local Dojo stylesheets.</para>
 522             </listitem>
 523
 524             <listitem>
 525                 <para>
 526                     <methodname>addOnLoad($spec, $function = null)</methodname>: add
 527                     a lambda for <command>dojo.onLoad</command> to call. If one argument is passed,
 528                     it is assumed to be either a function name or a javascript
 529                     closure. If two arguments are passed, the first is assumed
 530                     to be the name of an object instance variable and the second
 531                     either a method name in that object or a closure to utilize
 532                     with that object.
 533                 </para>
 534             </listitem>
 535
 536             <listitem>
 537                 <para>
 538                     <methodname>prependOnLoad($spec, $function = null)</methodname>:
 539                     exactly like <methodname>addOnLoad()</methodname>, excepts prepends to
 540                     beginning of onLoad stack.
 541                 </para>
 542             </listitem>
 543
 544             <listitem>
 545                 <para>
 546                     <methodname>getOnLoadActions()</methodname>: retrieve all
 547                     <command>dojo.onLoad</command> actions registered with the container. This will
 548                     be an array of arrays.
 549                 </para>
 550             </listitem>
 551
 552             <listitem>
 553                 <para>
 554                     <methodname>onLoadCaptureStart($obj = null)</methodname>:
 555                     capture data to be used as a lambda for <command>dojo.onLoad()</command>.
 556                     If <varname>$obj</varname> is provided, the captured JS code will be considered
 557                     a closure to use with that Javascript object.
 558                 </para>
 559             </listitem>
 560
 561             <listitem>
 562                 <para>
 563                     <methodname>onLoadCaptureEnd($obj = null)</methodname>: finish
 564                     capturing data for use with <command>dojo.onLoad()</command>.
 565                 </para>
 566             </listitem>
 567
 568             <listitem>
 569                 <para>
 570                     <methodname>javascriptCaptureStart()</methodname>:
 571                     capture arbitrary javascript to be included with Dojo JS
 572                     (onLoad, require, etc. statements).
 573                 </para>
 574             </listitem>
 575
 576             <listitem>
 577                 <para>
 578                     <methodname>javascriptCaptureEnd()</methodname>: finish capturing javascript.
 579                 </para>
 580             </listitem>
 581
 582             <listitem>
 583                 <para>
 584                     <methodname>__toString()</methodname>: cast the container to a
 585                     string; renders all <acronym>HTML</acronym> style and script elements.
 586                 </para>
 587             </listitem>
 588         </itemizedlist>
 589     </sect3>
 590 </sect2>
 591 <!--
 592 vim:se ts=4 sw=4 et:
 593 -->