home *** CD-ROM | disk | FTP | other *** search
/ Enter 2004 June / ENTER.ISO / files / xampp-win32-1.4.5-installer.exe / xampp / beginner.pkg < prev    next >
Encoding:
Text File  |  2004-03-24  |  8.0 KB  |  253 lines
  1. <refentry id="{@id}">
  2.  <refnamediv>
  3.   <refname>Beginner Guide</refname>
  4.   <refpurpose>learn how to use HTML_Progress, basic features</refpurpose>
  5.  </refnamediv>
  6.  <refsynopsisdiv>
  7.   <refsynopsisdivinfo>
  8.    <author>
  9.     by Laurent Laville
  10.     <authorblurb>{@link mailto:pear@laurent-laville.org}</authorblurb>
  11.    </author>
  12.    <copyright>November 2003, Laurent Laville</copyright>
  13.    <releaseinfo>HTML_Progress 1.0+</releaseinfo>
  14.   </refsynopsisdivinfo>
  15.  </refsynopsisdiv>
  16.  {@toc}
  17.  <refsect1 id="{@id basics}">
  18.   <title>HTML_Progress Basics</title>
  19.   <refsect2 id="{@id starting}">
  20.    <title>Starting out from scratch</title>
  21.    <para>
  22.     {@tutorial gettingstarted.pkg#inahurry} you've seen that such code below is not enough 
  23.     to run properly a Progress Bar.
  24.    </para>
  25.    <para>
  26.     <programlisting role="php">
  27.     <![CDATA[
  28. <?php
  29. require_once ('HTML/Progress.php');
  30.  
  31. $bar = new HTML_Progress();
  32.  
  33. echo $bar->toHtml(); 
  34. ?>
  35.     ]]>
  36.     </programlisting>
  37.    </para>
  38.    <para>You got only : 
  39.     <graphic fileref="../media/screenshots/inahurry.png"></graphic></para>
  40.    <para>
  41.     Why ? what's wrong with previous code ? It's very simple, HTML_Progress needs some CSS
  42.     class-selector to work fine. So if you send to browser the necessary styles, all will be ok.
  43.    </para>
  44.    <para>
  45.     <programlisting role="php">
  46.     <![CDATA[
  47. <?php
  48. require_once ('HTML/Progress.php');
  49.  
  50. $bar = new HTML_Progress();
  51. ?>
  52. <style type="text/css">
  53. <!--
  54. <?php echo $bar->getStyle(); ?>
  55. // -->
  56. </style>
  57.  
  58. <?php
  59. echo $bar->toHtml(); 
  60. ?>
  61.     ]]>
  62.     </programlisting>
  63.    </para>
  64.    <para>And the result will be : 
  65.     <graphic fileref="../media/screenshots/scratch1.png"></graphic></para>
  66.   </refsect2>
  67.   <refsect2 id="{@id using}">
  68.    <title>Running HTML_Progress</title>
  69.    <para>
  70.     Now you know how to show a basic progress bar, what should we do to run it ?
  71.    </para>
  72.    <para>
  73.     Let's begin by a simple empty loop. Your code should be something like that :
  74.    </para>
  75.    <para>
  76.     <programlisting role="php">
  77.     <![CDATA[
  78. <?php
  79. require_once ('HTML/Progress.php');
  80.  
  81. $bar = new HTML_Progress();
  82. ?>
  83. <style type="text/css">
  84. <!--
  85. <?php echo $bar->getStyle(); ?>
  86. // -->
  87. </style>
  88.  
  89. <?php
  90. echo $bar->toHtml(); 
  91.  
  92. do {
  93.     $bar->display();
  94.     if ($bar->getPercentComplete() == 1) {
  95.         break;   // the progress bar has reached 100%
  96.     }
  97.     $bar->incValue();
  98. } while(1);
  99. ?>
  100.     ]]>
  101.     </programlisting>
  102.    </para>
  103.    <para>
  104.     What's wrong out there ? The progress bar is running but nothing change on browser screen.
  105.     As for previous error, HTML_Progress needs some CSS class-selector, and also some JavaScript
  106.     code to work fine. Adds few more lines, and example will be at end :
  107.    </para>
  108.    <para>
  109.     <programlisting role="php">
  110.     <![CDATA[
  111. <?php
  112. require_once ('HTML/Progress.php');
  113.  
  114. $bar = new HTML_Progress();
  115.  
  116. $ui =& $bar->getUI();
  117. ?>
  118. <style type="text/css">
  119. <!--
  120. <?php echo $bar->getStyle(); ?>
  121. // -->
  122. </style>
  123. <script type="text/javascript">
  124. <!--
  125. <?php echo $ui->getScript(); ?>
  126. //-->
  127. </script>
  128.  
  129. <?php
  130. echo $bar->toHtml(); 
  131.  
  132. do {
  133.     $bar->display();
  134.     if ($bar->getPercentComplete() == 1) {
  135.         break;   // the progress bar has reached 100%
  136.     }
  137.     $bar->incValue();
  138. } while(1);
  139. ?>
  140.     ]]>
  141.     </programlisting>
  142.    </para>
  143.    <para>
  144.     <caution>As default increment of HTML_Progress is only +1(%), it may took few seconds before you
  145.     could see the first cell color changed.
  146.     </caution>
  147.    </para>
  148.    <para>
  149.     The empty loop was produced by a <emphasis>do ... while(1)</emphasis>, with 3 HTML_Progress
  150.     methods:
  151.     <unorderedlist>
  152.      <listitem><para>{@link HTML_Progress::display()}, to show new progress result</para>
  153.      </listitem>
  154.      <listitem><para>{@link HTML_Progress::getPercentComplete()}, to test end loop</para>
  155.      </listitem>
  156.      <listitem><para>{@link HTML_Progress::incValue()}, to ajust new progress value</para>
  157.      </listitem>
  158.     </unorderedlist>
  159.    </para>
  160.   </refsect2>
  161.   <tip><title></title>
  162.    To avoid that browser run under quirk mode, i suggest you to puts such DTD lines on each 
  163.    of your xHTML document.
  164.    <para>
  165.     <example>
  166.     <![CDATA[
  167. <!DOCTYPE html
  168.     PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  169.     "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  170.  
  171. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
  172. ...
  173. </html>
  174.     ]]>
  175.     </example>
  176.    </para>
  177.   </tip>
  178.  </refsect1>
  179.  <refsect1 id="{@id look-and-feel}">
  180.   <title>Changing look and feel</title>
  181.   <refsect2 id="{@id cell-style}">
  182.    <title>Progress Bar Cell element</title>
  183.    <para>Here you can decide if you want to have a basic bar length (10 cells), less or more.
  184.     You may also have possibility to change all the default values.
  185.    </para>
  186.    <para>There are 2 main methods to add and customize the cells of a Progress Bar :
  187.     <unorderedlist>
  188.      <listitem><para>{@link HTML_Progress_UI::setCellCount()}, 
  189.       more details on {@tutorial ui.setcellcount.cls}, where you'll find a full example.</para>
  190.      </listitem>
  191.      <listitem><para>{@link HTML_Progress_UI::setCellAttributes()}, 
  192.       more details on {@tutorial ui.setcellattributes.cls}, where you'll find a full example.</para>
  193.      </listitem>
  194.     </unorderedlist> 
  195.    </para>
  196.   </refsect2>
  197.   <refsect2 id="{@id border-style}">
  198.    <title>Progress Bar Border element</title>
  199.    <para>Here you can decide whether to paint or not a border, around the progress bar.
  200.     You may also have possibility to change all the default values.
  201.    </para>
  202.    <para>There are 2 main methods to add and customize the border of a Progress Bar :
  203.     <unorderedlist>
  204.      <listitem><para>{@link HTML_Progress::setBorderPainted()}, 
  205.       more details on {@tutorial progress.setborderpainted.cls}, where you'll find a full example.</para>
  206.      </listitem>
  207.      <listitem><para>{@link HTML_Progress_UI::setBorderAttributes()}, 
  208.       more details on {@tutorial ui.setborderattributes.cls}, where you'll find a full example.</para>      
  209.      </listitem>
  210.     </unorderedlist> 
  211.    </para>
  212.   </refsect2>
  213.   <refsect2 id="{@id string-style}">
  214.    <title>Progress Bar String element</title>
  215.    <para>Here you can decide whether to paint or not a custom string, with new value of progress bar.
  216.     You may also have possibility to change all the default values.
  217.    </para>
  218.    <para>There are 3 main methods to add and customize the string of a Progress Bar :
  219.     <unorderedlist>
  220.      <listitem><para>{@link HTML_Progress::setStringPainted()}, 
  221.       more details on {@tutorial progress.setstringpainted.cls}, where you'll find a full example.</para>      
  222.      </listitem>
  223.      <listitem><para>{@link HTML_Progress::setString()}, 
  224.       more details on {@tutorial progress.setstring.cls}, where you'll find a full example.</para>      
  225.      </listitem>
  226.      <listitem><para>{@link HTML_Progress_UI::setStringAttributes()}, 
  227.       more details on {@tutorial ui.setstringattributes.cls}, where you'll find a full example.</para>      
  228.      </listitem>
  229.     </unorderedlist> 
  230.    </para>
  231.   </refsect2>
  232.   <refsect2 id="{@id progress-style}">
  233.    <title>Progress Bar element</title>
  234.    <para>Here you have possibility to change all the default values (background color, width, height,
  235.     orientation, fill way ...)
  236.    </para>
  237.    <para>There is only 3 main methods to customize a Progress Bar :
  238.     <unorderedlist>
  239.      <listitem><para>{@link HTML_Progress_UI::setProgressAttributes()}, 
  240.       more details on {@tutorial ui.setprogressattributes.cls}, where you'll find a full example.</para>      
  241.      </listitem>
  242.      <listitem><para>{@link HTML_Progress_UI::setOrientation()}, 
  243.       more details on {@tutorial ui.setorientation.cls}, where you'll find a full example.</para>      
  244.      </listitem>
  245.      <listitem><para>{@link HTML_Progress_UI::setFillWay()}, 
  246.       more details on {@tutorial ui.setfillway.cls}, where you'll find a full example.</para>      
  247.      </listitem>
  248.     </unorderedlist> 
  249.    </para>
  250.   </refsect2>
  251.  </refsect1>
  252. </refentry>
  253.