documentation/manual/en/module_specs/Zend_ProgressBar.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.progressbar.introduction" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>Zend_ProgressBar</title>
   5
   6     <sect2 id="zend.progressbar.whatisit">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_ProgressBar</classname> is a component to create and update
  11             progressbars in different environments. It consists of a single
  12             backend, which outputs the progress through one of the multiple
  13             adapters. On every update, it takes an absolute value and optionally
  14             a status message, and then calls the adapter with some precalculated
  15             values like percentage and estimated time left.
  16         </para>
  17     </sect2>
  18
  19     <sect2 id="zend.progressbar.basic">
  20         <title>Basic Usage of Zend_Progressbar</title>
  21
  22         <para>
  23             <classname>Zend_ProgressBar</classname> is quite easy in its usage. You
  24             simply create a new instance of <classname>Zend_Progressbar</classname>, defining a
  25             min- and a max-value, and choose an adapter to output the data. If
  26             you want to process a file, you would do something like:
  27         </para>
  28
  29         <programlisting language="php"><![CDATA[
  30 $progressBar = new Zend_ProgressBar($adapter, 0, $fileSize);
  31
  32 while (!feof($fp)) {
  33     // Do something
  34
  35     $progressBar->update($currentByteCount);
  36 }
  37
  38 $progressBar->finish();
  39 ]]></programlisting>
  40
  41         <para>
  42             In the first step, an instance of <classname>Zend_ProgressBar</classname> is
  43             created, with a specific adapter, a min-value of 0 and a max-value
  44             of the total filesize. Then a file is processed and in every loop
  45             the progressbar is updated with the current byte count. At the end
  46             of the loop, the progressbar status is set to finished.
  47         </para>
  48
  49         <para>
  50             You can also call the <methodname>update()</methodname> method of
  51             <classname>Zend_ProgressBar</classname> without arguments, which just
  52             recalculates ETA and notifies the adapter. This is useful when there
  53             is no data update but you want the progressbar to be updated.
  54         </para>
  55     </sect2>
  56
  57     <sect2 id="zend.progressbar.persistent">
  58         <title>Persistent progress</title>
  59
  60         <para>
  61             If you want the progressbar to be persistent over multiple requests,
  62             you can give the name of a session namespace as fourth argument
  63             to the constructor. In that case, the progressbar will not notify
  64             the adapter within the constructor, but only when you call
  65             <methodname>update()</methodname> or <methodname>finish()</methodname>. Also the current
  66             value, the status text and the start time for ETA calculation will
  67             be fetched in the next request run again.
  68         </para>
  69     </sect2>
  70
  71     <sect2 id="zend.progressbar.adapters">
  72         <title>Standard adapters</title>
  73
  74         <para>
  75             <classname>Zend_ProgressBar</classname> comes with the following three adapters:
  76
  77             <itemizedlist mark="opencircle">
  78                 <listitem>
  79                     <para><xref linkend="zend.progressbar.adapter.console" /></para>
  80                 </listitem>
  81
  82                 <listitem><para><xref linkend="zend.progressbar.adapter.jspush" /></para></listitem>
  83                 <listitem><para><xref linkend="zend.progressbar.adapter.jspull" /></para></listitem>
  84             </itemizedlist>
  85         </para>
  86
  87         <xi:include href="Zend_ProgressBar_Adapter_Console.xml" />
  88         <xi:include href="Zend_ProgressBar_Adapter_JsPush.xml" />
  89         <xi:include href="Zend_ProgressBar_Adapter_JsPull.xml" />
  90     </sect2>
  91 </sect1>
  92 <!--
  93 vim:se ts=4 sw=4 et:
  94 -->