documentation/manual/pl/module_specs/Zend_ProgressBar_Adapter_JsPush.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20854 -->
   3 <!-- Reviewed: no -->
   4 <sect3 id="zend.progressbar.adapter.jspush">
   5     <title>Zend_ProgressBar_Adapter_JsPush</title>
   6
   7     <para>
   8         <classname>Zend_ProgressBar_Adapter_JsPush</classname> to adapter pozwalający na
   9         aktualizację paska postępu w przeglądarce poprzez JavaScript Push. To oznacza, że
  10         nie jest potrzebne nowe połączenie na potrzeby przesyłu danych o postępie operacji.
  11         Proces pracujący po stronie serwera komunikuje się bezpośrednio z przeglądarką
  12         użytkownika.
  13     </para>
  14
  15     <para>
  16         Opcje adaptera można ustawiać za pomocą metod <code>set*</code> albo przez podanie
  17         tablicy asocjacyjnej lub obiektu <classname>Zend_Config</classname> w pierwszym parametrze
  18         konstruktora. Dostępne opcje to:
  19     </para>
  20
  21     <itemizedlist>
  22         <listitem>
  23             <para>
  24                 <code>updateMethodName</code>: Metoda JavaScript, która zostanie wywołana
  25                 przy każdej aktualizacji paska postępu. Domyślnie jest to
  26                 <classname>Zend_ProgressBar_Update</classname>.
  27             </para>
  28         </listitem>
  29
  30         <listitem>
  31             <para>
  32                 <code>finishMethodName</code>: Metoda JavaScript, która zostanie wywołana
  33                 po zakończeniu prowadzonej operacji. Domyślna wartość to
  34                 <constant>NULL</constant>, co oznacza brak reakcji.
  35             </para>
  36         </listitem>
  37     </itemizedlist>
  38
  39     <para>
  40         Użycie tego adaptera jest dość proste. Na początku należy utworzyć pasek postępu w
  41         przeglądarce za pomocą poleceń JavaScript lub <acronym>HTML</acronym>. Następnie należy
  42         zdefiniować metodę JavaScript wywoływaną przy aktualizacji oraz (opcjonalnie)
  43         po skończeniu działania. Obie powinny przyjmować pojedynczy argument - obiekt
  44         <acronym>JSON</acronym>. Aby otworzyć połączenie należy wywołać długo trwającą akcję
  45         w ukrytym obiekcie <code>iframe</code> lub <code>object</code>. Podczas wykonywania
  46         tego procesu przy każdej aktualizacji adapter będzie wywoływał odpowiednią metodę
  47         przekazując do niej obiekt <acronym>JSON</acronym> o następujących parametrach:
  48     </para>
  49
  50     <itemizedlist>
  51         <listitem>
  52             <para>
  53                 <code>current</code>: Obecna wartość absolutna
  54             </para>
  55         </listitem>
  56
  57         <listitem>
  58             <para>
  59                 <code>max</code>: Maksymalna wartość absolutna
  60             </para>
  61         </listitem>
  62
  63         <listitem>
  64             <para>
  65                 <code>percent</code>: Obliczony procent postępu
  66             </para>
  67         </listitem>
  68
  69         <listitem>
  70             <para>
  71                 <code>timeTaken</code>: Czas trwania procesu (do obecnej chwili)
  72             </para>
  73         </listitem>
  74
  75         <listitem>
  76             <para>
  77                 <code>timeRemaining</code>: Oszacowanie czasu pozostałego do końca
  78             </para>
  79         </listitem>
  80
  81         <listitem>
  82             <para>
  83                 <code>text</code>: Opcjonalna wiadomość dotycząca stanu postępu
  84             </para>
  85         </listitem>
  86     </itemizedlist>
  87
  88     <example id="zend.progressbar-adapter.jspush.example">
  89         <title>Podstawowy przykład kodu po stronie klienta</title>
  90
  91         <para>
  92             Ten przykład ilustruje prosty kod <acronym>HTML</acronym>, <acronym>CSS</acronym>
  93             oraz JavaScript do użytku z adapterem JsPush
  94         </para>
  95
  96         <programlisting language="html"><![CDATA[
  97 <div id="zend-progressbar-container">
  98     <div id="zend-progressbar-done"></div>
  99 </div>
 100
 101 <iframe src="long-running-process.php" id="long-running-process"></iframe>
 102 ]]></programlisting>
 103
 104         <programlisting language="css"><![CDATA[
 105 #long-running-process {
 106     position: absolute;
 107     left: -100px;
 108     top: -100px;
 109
 110     width: 1px;
 111     height: 1px;
 112 }
 113
 114 #zend-progressbar-container {
 115     width: 100px;
 116     height: 30px;
 117
 118     border: 1px solid #000000;
 119     background-color: #ffffff;
 120 }
 121
 122 #zend-progressbar-done {
 123     width: 0;
 124     height: 30px;
 125
 126     background-color: #000000;
 127 }
 128 ]]></programlisting>
 129
 130         <programlisting language="javascript"><![CDATA[
 131 function Zend_ProgressBar_Update(data)
 132 {
 133     document.getElementById('zend-progressbar-done').style.width = data.percent + '%';
 134 }
 135 ]]></programlisting>
 136
 137         <para>
 138             Powyższy kod tworzy prosty pojemnik z czarną granicą oraz blok wskazujący
 139             zaawansowanie procesu. Należy pamiętać by nie ukrywać elementów
 140             <code>iframe</code> lub <code>object</code> poprzez <code>display: none;</code>
 141             ponieważ w takiej sytuacji niektóre przeglądarki jak Safari 2 w ogóle nie pobiorą
 142             tych elementów.
 143         </para>
 144
 145         <para>
 146             Zamiast własnoręcznie tworzyć pasek postępu, można skorzystać z jednej z wielu
 147             dostępnych bibliotek JavaScript, takich jak Dojo czy jQuery. Np.:
 148         </para>
 149
 150         <itemizedlist>
 151             <listitem>
 152                 <para>
 153                     Dojo: <ulink
 154                         url="http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/user-assistance-and-feedback/progress-bar" />
 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>Odstęp czasowy pomiędzy aktualizacjami</title>
 180
 181         <para>
 182             Należy upewnić się, że nie jest tworzona zbyt duża ilość aktualizacji. Każda z nich
 183             powinna przesyłać dane o wielkości co najmniej 1kB. Dla przeglądarki Safari jest to
 184             niezbędny warunek do wykonania polecenia wywołania funkcji. Internet Explorer ma
 185             podobne ograniczenie - w jego przypadku jest to 256 Bajtów.
 186         </para>
 187     </note>
 188 </sect3>
 189 <!--
 190 vim:se ts=4 sw=4 et:
 191 -->