repo_zf1/documentation/manual/fr/module_specs/Zend_ProgressBar_Adapter_JsPush.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.progressbar.adapter.jspush">
    <title>Zend_ProgressBar_Adapter_JsPush</title>

    <para>
        <classname>Zend_ProgressBar_Adapter_JsPush</classname> est un adaptateur qui vous
        permet de mettre à jour une barre de progression dans un navigateur au travers de
        Javascript. Ceci veut dire qu'une seconde connexion n'est pas nécessaire pour recueillir le
        statut du processus courant, mais que le processus lui-même envoie son statut directement au
        navigateur.
    </para>

    <para>
        Vous pouvez paramétrer les options de l'adaptateur soit avec les méthodes
        <code>set*</code> soit en fournissant un tableau ("array") ou une instance de
        <classname>Zend_Config</classname> contenant les options en tant que premier paramètre du
        constructeur. Les options disponibles sont :
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <code>updateMethodName</code> : la méthode Javascript qui sera appelée à
                chaque mise à jour. La valeur par défaut est
                <classname>Zend_ProgressBar_Update</classname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>finishMethodName</code> : la méthode Javascript qui sera appelée lorsque
                le statut terminé sera atteint. La valeur par défaut est <constant>NULL</constant>, qui veut
                dire que rien n'est fait.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        L'utilisation de cet adaptateur est assez simple. Premièrement vous créez une barre de
        progression pour le navigateur, soit avec Javascript ou auparavant en pur HTML. Ensuite vous
        définissez une méthode de mise à jour et optionnellement une méthode de finalisation en
        Javascript, les deux acceptant un objet <acronym>JSON</acronym> en tant qu'unique argument. Ensuite vous
        appelez une page Web avec un processus chronophage dans une balise <code>iframe</code> ou
        <code>object</code> masqué. Pendant que le processus tourne, l'adaptateur appelle la méthode
        de mise à jour à chaque mise à jour avec un objet <acronym>JSON</acronym>, contenant le paramètres suivants
        :
    </para>

    <itemizedlist>
        <listitem>
            <para><code>current</code> : la valeur courante</para>
        </listitem>

        <listitem>
            <para><code>max</code> : la valeur maximum</para>
        </listitem>

        <listitem>
            <para><code>percent</code> : le pourcentage calculé</para>
        </listitem>

        <listitem>
            <para>
                <code>timeTaken</code> : le temps depuis quand le processus courant est en
                marche
            </para>
        </listitem>

        <listitem>
            <para>
                <code>timeRemaining</code> : le temps estimé pour que le processus se
                termine
            </para>
        </listitem>

        <listitem>
            <para><code>text</code> : le message de statut optionnel, si fourni</para>
        </listitem>
    </itemizedlist>

    <example id="zend.progressbar-adapter.jspush.example">
        <title>Exemple basique du fonctionnement côté-client</title>

        <para>
            Cet exemple illustre un paramétrage basique du HTML, <acronym>CSS</acronym> et JavaScript pour
            l'adaptateur JsPush :
        </para>

        <programlisting language="html"><![CDATA[
<div id="zend-progressbar-container">
    <div id="zend-progressbar-done"></div>
</div>

<iframe src="long-running-process.php" id="long-running-process"></iframe>
]]></programlisting>

        <programlisting language="css"><![CDATA[
#long-running-process {
    position: absolute;
    left: -100px;
    top: -100px;

    width: 1px;
    height: 1px;
}

#zend-progressbar-container {
    width: 100px;
    height: 30px;

    border: 1px solid #000000;
    background-color: #ffffff;
}

#zend-progressbar-done {
    width: 0;
    height: 30px;

    background-color: #000000;
}
]]></programlisting>

        <programlisting language="javascript"><![CDATA[
function Zend_ProgressBar_Update(data)
{
    document.getElementById('zend-progressbar-done').style.width =
        data.percent + '%';
}
]]></programlisting>

        <para>
            Ceci créera un simple conteneur avec une bordure noire et un bloc qui indique le
            niveau du processus courant. Vous ne devez pas masquer l'<code>iframe</code> ou
            l'<code>object</code> par <code>display: none;</code>, car dans ce cas les navigateurs
            comme Safari 2 ne chargeront pas le contenu réel.
        </para>

        <para>
            Plutôt que de créer votre barre de progression personnalisée, vous pouvez utiliser
            une de celles disponibles dans les librairies JavaScript comme Dojo, jQuery etc. Par
            exemple, il existe :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Dojo : <ulink
                    url="http://dojotoolkit.org/reference-guide/dijit/ProgressBar.html"></ulink>
                </para>
            </listitem>

            <listitem>
                <para>
                    jQuery : <ulink
                    url="http://t.wits.sg/2008/06/20/jquery-progress-bar-11/"></ulink>
                </para>
            </listitem>

            <listitem>
                <para>
                    MooTools : <ulink
                    url="http://davidwalsh.name/dw-content/progress-bar.php"></ulink>
                </para>
            </listitem>

            <listitem>
                <para>
                    Prototype : <ulink
                    url="http://livepipe.net/control/progressbar"></ulink>
                </para>
            </listitem>
        </itemizedlist>
    </example>

    <note>
        <title>Intervalle de mise à jour</title>

        <para>
            Vous devez faire attention à ne pas envoyer trop de mises à jour, puisque chaque
            mise à jour a une taille minimum de 1ko. Ceci est requis par le navigateur Safari pour
            rendre et exécuter l'appel de fonction. Internet Explorer possède une limitation
            similaire mais à 256 octets.
        </para>
    </note>
</sect3>