Zend_ProgressBar
Zend_ProgressBar
Programmer's Reference Guide

Zend_ProgressBar

Introduction

Zend_ProgressBar est un composant pour créer et mettre à jour les barres de progression dans différents environnements. Il consiste en un backend unique, qui affiche la progression au travers de l'un des multiples adaptateurs. A chaque mise à jour, il prend un chemin absolu et un message d'état, et appelle ensuite l'adaptateur avec certaines valeurs précalculées comme le pourcentage et le temps restant estimé.

Utilisation basique de Zend_Progressbar

Zend_ProgressBar est assez simple d'utilisation. Vous créez simplement une nouvelle instance de Zend_Progressbar, en définissant des valeurs minimum et maximum, et en choisissant un adaptateur pour afficher les données. Si vous voulez travailler avec un fichier, vous pouvez faire comme ceci :

  1. $progressBar = new Zend_ProgressBar(0, $fileSize, $adapter);
  2.  
  3. while (!feof($fp)) {
  4.     // Faire quelque chose
  5.  
  6.     $progressBar->update($currentByteCount);
  7. }
  8.  
  9. $progressBar->finish();

Dans un premier temps, une instance de Zend_ProgressBar, avec une valeur minimum de 0, une valeur maximum correspondant à la taille totale du fichier et un adaptateur spécifique. Ensuite on travaille avec le fichier et à chaque boucle la barre de progression est mise à jour avec le nombre d'octets courant. A la fin de la boucle, le statut de la barre de progression est réglé à terminé.

Zend_ProgressBar possède aussi une méthode refresh() qui recalcule le temps restant estimé et met à jour l'adaptateur. Ceci est pratique quand il n'y a aucune donnée à mettre à jour mais que vous souhaitez que la barre de progression soit mise à jour.

Adaptateurs standard

Zend_ProgressBar est fourni avec les deux adaptateurs suivants :

Zend_ProgressBar_Adapter_Console

Zend_ProgressBar_Adapter_Console est un adaptateur de type texte pour les terminaux. Il peut automatiquement détecter la largeur du terminal mais supporte aussi des largeurs personnalisées. Vous pouvez définir quels éléments seront affichés avec la barre de progression et personnaliser leur ordre. Vous pouvez aussi définir le style de la barre de progression elle-même.

Note: Reconnaissance automatique de la largeur de la console
 shell_exec est nécessaire pour que ceci fonctionne sur les systèmes de type *nix. Sur Windows, il y a toujours un terminal fixe de 80 caractères de large, donc la reconnaissance automatique n'est pas nécessaire.

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

  • outputStream : un flux de sortie différent, si vous ne souhaitez pas utiliser STDOUT. Peut être n'importe quel autre flux come php://stderr ou un chemin vers un fichier.

  • width : soit un entier ou la constante AUTO de Zend_Console_ProgressBar.

  • elements : soit NULL par défaut ou un tableau avec au moins l'une des constantes de Zend_Console_ProgressBar suivantes comme valeur :

    • ELEMENT_PERCENT : la valeur courante en pourcentage.

    • ELEMENT_BAR : la barre qui va représenter le pourcentage.

    • ELEMENT_ETA : le calcul automatique du temps restant estimé (NDT. : "Estimated Time for Accomplishment"). Cet élément est affiché pour la première fois qu'après cinq secondes, car durant ce temps, il n'est pas possible de calculer des résultats précis.

    • ELEMENT_TEXT : un message de statut optionnel concernant le processus courant.

  • textWidth : largeur en caractères de l'élément ELEMENT_TEXT. Par défaut vaut 20.

  • charset : encodage de l'élément ELEMENT_TEXT. Par défaut vaut "utf-8".

  • barLeftChar : un caractère qui est utilisé du côté gauche de l'indicateur de la barre de progression.

  • barRightChar : un caractère qui est utilisé du côté droit de l'indicateur de la barre de progression.

  • barIndicatorChar : un caractère qui est utilisé pour l'indicateur de la barre de progression. Celui-ci peut être vide.

Zend_ProgressBar_Adapter_JsPush

Zend_ProgressBar_Adapter_JsPush 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.

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

  • updateMethodName : la méthode Javascript qui sera appelée à chaque mise à jour. La valeur par défaut est Zend_ProgressBar_Update.

  • finishMethodName : la méthode Javascript qui sera appelée lorsque le statut terminé sera atteint. La valeur par défaut est NULL, qui veut dire que rien n'est fait.

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 JSON en tant qu'unique argument. Ensuite vous appelez une page Web avec un processus chronophage dans une balise iframe ou object masqué. Pendant que le processus tourne, l'adaptateur appelle la méthode de mise à jour à chaque mise à jour avec un objet JSON, contenant le paramètres suivants :

  • current : la valeur courante

  • max : la valeur maximum

  • percent : le pourcentage calculé

  • timeTaken : le temps depuis quand le processus courant est en marche

  • timeRemaining : le temps estimé pour que le processus se termine

  • text : le message de statut optionnel, si fourni

Example #1 Exemple basique du fonctionnement côté-client

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

  1. <div id="zend-progressbar-container">
  2.     <div id="zend-progressbar-done"></div>
  3. </div>
  4.  
  5. <iframe src="long-running-process.php" id="long-running-process"></iframe>
  1. #long-running-process {
  2.     position: absolute;
  3.     left: -100px;
  4.     top: -100px;
  5.  
  6.     width: 1px;
  7.     height: 1px;
  8. }
  9.  
  10. #zend-progressbar-container {
  11.     width: 100px;
  12.     height: 30px;
  13.  
  14.     border: 1px solid #000000;
  15.     background-color: #ffffff;
  16. }
  17.  
  18. #zend-progressbar-done {
  19.     width: 0;
  20.     height: 30px;
  21.  
  22.     background-color: #000000;
  23. }
  1. function Zend_ProgressBar_Update(data)
  2. {
  3.     document.getElementById('zend-progressbar-done').style.width = data.percent + '%';
  4. }

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'iframe ou l'object par display: none;, car dans ce cas les navigateurs comme Safari 2 ne chargeront pas le contenu réel.

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 :

  • Dojo : http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/user-assistance-and-feedback/progress-bar

  • jQuery : http://t.wits.sg/2008/06/20/jquery-progress-bar-11/

  • MooTools : http://davidwalsh.name/dw-content/progress-bar.php

  • Prototype : http://livepipe.net/control/progressbar

Note: Intervalle de mise à jour
 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.

Zend_ProgressBar_Adapter_JsPull

Zend_ProgressBar_Adapter_JsPull est l'opposé de jsPush, car il requiert de venir récupérer les nouvelles mises à jour, plutôt que d'envoyer les mises à jour vers le navigateur. Généralement, vous devriez utiliser l'adaptateur avec l'option de persistance de Zend_ProgressBar. Lors de l'appel, l'adaptateur envoie une chaîne JSON vers le navigateur, qui est comparable à la chaîne JSON envoyée par l'adaptateur jsPush. La seule différence est qu'il contient un paramètre supplémentaire "finished", qui vaut FALSE quand update() est appelée ou TRUE quand finish() est appelée.

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

  • exitAfterSend : sort de la requête courante après que les données aient été envoyées au navigateur. Vaut TRUE par défaut.

Zend_ProgressBar
Zend_ProgressBar
Programmer's Reference Guide