documentation/manual/en/module_specs/Zend_ProgressBar_Adapter_JsPush.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.progressbar.adapter.jspush">
   4     <title>Zend_ProgressBar_Adapter_JsPush</title>
   5
   6     <para>
   7         <classname>Zend_ProgressBar_Adapter_JsPush</classname> is an adapter which let's
   8         you update a progressbar in a browser via Javascript Push. This means
   9         that no second connection is required to gather the status about a
  10         running process, but that the process itself sends its status directly
  11         to the browser.
  12     </para>
  13
  14     <para>
  15         You can set the adapter options either via the <code>set*</code> methods
  16         or give an array or a <classname>Zend_Config</classname> instance with options as first
  17         parameter to the constructor. The available options are:
  18     </para>
  19
  20     <itemizedlist>
  21         <listitem>
  22             <para>
  23                 <code>updateMethodName</code>: The javascript method which
  24                 should be called on every update. Default value is
  25                 <classname>Zend_ProgressBar_Update</classname>.
  26             </para>
  27         </listitem>
  28
  29         <listitem>
  30             <para>
  31                 <code>finishMethodName</code>: The javascript method which
  32                 should be called after finish status was set. Default value is
  33                 <constant>NULL</constant>, which means nothing is done.
  34             </para>
  35         </listitem>
  36     </itemizedlist>
  37
  38     <para>
  39         The usage of this adapter is quite simple. First you create a progressbar
  40         in your browser, either with JavaScript or previously created with plain
  41         <acronym>HTML</acronym>. Then you define the update method and optionally the finish method
  42         in JavaScript, both taking a json object as single argument. Then you
  43         call a webpage with the long-running process in a hidden
  44         <code>iframe</code> or <code>object</code> tag. While the process is
  45         running, the adapter will call the update method on every update with
  46         a json object, containing the following parameters:
  47     </para>
  48
  49     <itemizedlist>
  50         <listitem>
  51             <para>
  52                 <code>current</code>: The current absolute value
  53             </para>
  54         </listitem>
  55
  56         <listitem>
  57             <para>
  58                 <code>max</code>: The max absolute value
  59             </para>
  60         </listitem>
  61
  62         <listitem>
  63             <para>
  64                 <code>percent</code>: The calculated percentage
  65             </para>
  66         </listitem>
  67
  68         <listitem>
  69             <para>
  70                 <code>timeTaken</code>: The time how long the process ran yet
  71             </para>
  72         </listitem>
  73
  74         <listitem>
  75             <para>
  76                 <code>timeRemaining</code>: The expected time for the process to finish
  77             </para>
  78         </listitem>
  79
  80         <listitem>
  81             <para>
  82                 <code>text</code>: The optional status message, if given
  83             </para>
  84         </listitem>
  85     </itemizedlist>
  86
  87     <example id="zend.progressbar-adapter.jspush.example">
  88         <title>Basic example for the client-side stuff</title>
  89
  90         <para>
  91             This example illustrates a basic setup of <acronym>HTML</acronym>,
  92             <acronym>CSS</acronym> and JavaScript for the JsPush adapter
  93         </para>
  94
  95         <programlisting language="html"><![CDATA[
  96 <div id="zend-progressbar-container">
  97     <div id="zend-progressbar-done"></div>
  98 </div>
  99
 100 <iframe src="long-running-process.php" id="long-running-process"></iframe>
 101 ]]></programlisting>
 102
 103         <programlisting language="css"><![CDATA[
 104 #long-running-process {
 105     position: absolute;
 106     left: -100px;
 107     top: -100px;
 108
 109     width: 1px;
 110     height: 1px;
 111 }
 112
 113 #zend-progressbar-container {
 114     width: 100px;
 115     height: 30px;
 116
 117     border: 1px solid #000000;
 118     background-color: #ffffff;
 119 }
 120
 121 #zend-progressbar-done {
 122     width: 0;
 123     height: 30px;
 124
 125     background-color: #000000;
 126 }
 127 ]]></programlisting>
 128
 129         <programlisting language="javascript"><![CDATA[
 130 function Zend_ProgressBar_Update(data)
 131 {
 132     document.getElementById('zend-progressbar-done').style.width =
 133          data.percent + '%';
 134 }
 135 ]]></programlisting>
 136
 137         <para>
 138             This will create a simple container with a black border and a
 139             block which indicates the current process. You should not hide
 140             the <code>iframe</code> or <code>object</code> by <code>display: none;</code>,
 141             as some browsers like Safari 2 will not load the actual content then.
 142         </para>
 143
 144         <para>
 145             Instead of creating your custom progressbar, you may want to use
 146             one of the available JavaScript libraries like Dojo, jQuery etc.
 147             For example, there are:
 148         </para>
 149
 150         <itemizedlist>
 151             <listitem>
 152                 <para>
 153                     Dojo: <ulink
 154                         url="http://dojotoolkit.org/reference-guide/dijit/ProgressBar.html"/>
 155                 </para>
 156             </listitem>
 157
 158             <listitem>
 159                 <para>
 160                     jQuery: <ulink url="http://t.wits.sg/2008/06/20/jquery-progress-bar-11/" />
 161                 </para>
 162             </listitem>
 163
 164             <listitem>
 165                 <para>
 166                     MooTools: <ulink url="http://davidwalsh.name/dw-content/progress-bar.php" />
 167                 </para>
 168             </listitem>
 169
 170             <listitem>
 171                 <para>
 172                     Prototype: <ulink url="http://livepipe.net/control/progressbar" />
 173                 </para>
 174             </listitem>
 175         </itemizedlist>
 176     </example>
 177
 178     <note>
 179         <title>Interval of updates</title>
 180
 181         <para>
 182             You should take care of not sending too many updates, as every update
 183             has a min-size of 1kb. This is a requirement for the Safari browser
 184             to actually render and execute the function call. Internet Explorer
 185             has a similar limitation of 256 bytes.
 186         </para>
 187     </note>
 188 </sect3>
 189 <!--
 190 vim:se ts=4 sw=4 et:
 191 -->