repo_zf1/documentation/manual/en/module_specs/Zend_ProgressBar.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.progressbar.introduction" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Zend_ProgressBar</title>

    <sect2 id="zend.progressbar.whatisit">
        <title>Introduction</title>

        <para>
            <classname>Zend_ProgressBar</classname> is a component to create and update
            progressbars in different environments. It consists of a single
            backend, which outputs the progress through one of the multiple
            adapters. On every update, it takes an absolute value and optionally
            a status message, and then calls the adapter with some precalculated
            values like percentage and estimated time left.
        </para>
    </sect2>

    <sect2 id="zend.progressbar.basic">
        <title>Basic Usage of Zend_Progressbar</title>

        <para>
            <classname>Zend_ProgressBar</classname> is quite easy in its usage. You
            simply create a new instance of <classname>Zend_Progressbar</classname>, defining a
            min- and a max-value, and choose an adapter to output the data. If
            you want to process a file, you would do something like:
        </para>

        <programlisting language="php"><![CDATA[
$progressBar = new Zend_ProgressBar($adapter, 0, $fileSize);

while (!feof($fp)) {
    // Do something

    $progressBar->update($currentByteCount);
}

$progressBar->finish();
]]></programlisting>

        <para>
            In the first step, an instance of <classname>Zend_ProgressBar</classname> is
            created, with a specific adapter, a min-value of 0 and a max-value
            of the total filesize. Then a file is processed and in every loop
            the progressbar is updated with the current byte count. At the end
            of the loop, the progressbar status is set to finished.
        </para>

        <para>
            You can also call the <methodname>update()</methodname> method of
            <classname>Zend_ProgressBar</classname> without arguments, which just
            recalculates ETA and notifies the adapter. This is useful when there
            is no data update but you want the progressbar to be updated.
        </para>
    </sect2>

    <sect2 id="zend.progressbar.persistent">
        <title>Persistent progress</title>

        <para>
            If you want the progressbar to be persistent over multiple requests,
            you can give the name of a session namespace as fourth argument
            to the constructor. In that case, the progressbar will not notify
            the adapter within the constructor, but only when you call
            <methodname>update()</methodname> or <methodname>finish()</methodname>. Also the current
            value, the status text and the start time for ETA calculation will
            be fetched in the next request run again.
        </para>
    </sect2>

    <sect2 id="zend.progressbar.adapters">
        <title>Standard adapters</title>

        <para>
            <classname>Zend_ProgressBar</classname> comes with the following three adapters:

            <itemizedlist mark="opencircle">
                <listitem>
                    <para>
                        <link
                            linkend="zend.progressbar.adapter.console">Zend_ProgressBar_Adapter_Console</link>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <link
                            linkend="zend.progressbar.adapter.jspush">Zend_ProgressBar_Adapter_JsPush</link>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <link
                            linkend="zend.progressbar.adapter.jspull">Zend_ProgressBar_Adapter_JsPull</link>
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <xi:include href="Zend_ProgressBar_Adapter_Console.xml" />
        <xi:include href="Zend_ProgressBar_Adapter_JsPush.xml" />
        <xi:include href="Zend_ProgressBar_Adapter_JsPull.xml" />
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->