<?xml version="1.0" encoding="UTF-8"?>
<section>
    <sectioninfo>
        <keywordset>
            <keyword>rich:progressBar</keyword>
            <keyword>progressBar</keyword>
        </keywordset>
    </sectioninfo>
    <table>
        <title>Component identification parameters</title>
        
        <tgroup cols="2">
            <thead>
                <row>
                    <entry>Name</entry>
                    <entry>Value</entry>
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>component-type</entry>
                    <entry>org.richfaces.ProgressBar</entry>
                </row>
                <!--row>
                    <entry>component-class</entry>
                    <entry></entry>
                </row-->
                <row>
                    <entry>component-family</entry>
                    <entry>org.richfaces.ProgressBar</entry>
                </row>
                <row>
                    <entry>renderer-type</entry>
                    <entry>org.richfaces.renderkit.ProgressBarRenderer</entry>
                </row>
                <row>
                    <entry>tag-class</entry>
                    <entry>org.richfaces.taglib.ProgressBarTag</entry>
                </row>
            </tbody>
        </tgroup>
    </table>
    <section>
        <title>Creating the Component with a Page Tag</title>
        <para>Here is a simple example of how the component can be used on a page: </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<rich:progressBar value="#{bean.incValue1}"/>
...]]></programlisting>
    </section>
    <section>
        <title>Creating the Component Dynamically Using Java</title>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.progressBar;
...	
HtmlProgressBar myProgressBar = new progressBar();
...]]></programlisting>
    </section>
    <!-- Start  Details of Usage-->
    <section>
        <title>Details of Usage</title>
        <para>    
            As it was mentioned above, the <emphasis role="bold"><property>&lt;rich:progressBar&gt;</property>  </emphasis>
            component displays the status of the ongoing process.  The component has a number of key attributes. 
        </para>
        <para>     
          The <emphasis><property>&quot;value&quot;</property></emphasis> attribute sets the current value of the process. Status of the process is calculated basing on  <emphasis><property> &quot;value&quot;</property></emphasis> attribute.  
        </para>     
      
        <para> The <emphasis role="bold"><property>&lt;rich:progressBar&gt;</property>  </emphasis> starts and finishes rendering its state being governed by   <emphasis><property>&quot;minValue&quot;</property></emphasis> (default value – &quot;0&quot;) 
            and <emphasis><property>&quot;maxValue&quot;</property></emphasis>  (default value is &quot;100&quot;) attributes relatively.  See the following example.</para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>      
        
        <programlisting role="XML"><![CDATA[...
<rich:progressBar value="#{bean.incValue}"  minValue="50"  maxValue="400"/>
...]]> </programlisting>   
      <para>
        The   <emphasis><property> &quot;label&quot;</property></emphasis>  attribute is responsible for displaying informational 
        data, information on the progress bar, if it&apos;s not displayed using  children components. 
        If this attribute is not set and the children components are not used either, no textual information 
        regarding ongoing process will be indicated. 
        In order to indicate the current status you need to pass the value to this attribute. Please  see an example.
      </para>         
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="XML"><![CDATA[...	
<rich:progressBar value="#{bean.incValue}" id="progrs" label="{value}%"/>
...]]></programlisting>
<para>
  Displaying information on a progress bar can be also performed using
  
  <property>&lt;h:outputText&gt;</property>  JSF tag  within 
  <emphasis role="bold"><property>&lt;rich:progressBar&gt;</property>  </emphasis> tags passing the progress value to the value of the JSF tag.  
</para>
    
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      
      <programlisting role="XML"><![CDATA[...
<rich:progressBar value="#{bean.incValue1}" >
    <h:outputText value="#{bean.incValue1}"></h:outputText>
</rich:progressBar>
...]]> </programlisting>  
     
      
      
      <para>  
      The   <emphasis><property> &quot;progressVar&quot;</property></emphasis> attribute serves to provide an option for a
      value substitution on the page. It defines a variable that contains the 
      data taken from 
      <emphasis><property>&quot;value&quot;</property></emphasis> attribute. 
      The sole purpose of the 
      <emphasis><property> &quot;progressVar&quot;</property></emphasis> 
      attribute is to provide a way to use the data placed into the 
      <emphasis><property>&quot;value&quot;</property></emphasis> attribute. 
      Please study carefully the following code example:
      
      

    </para>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      
       <programlisting role="XML"><![CDATA[...
<rich:progressBar value="#{bean.incValue1}" enabled="#{bean.enabled1}" id="progrs1" progressVar="progress">
    <h:outputText value="{progress}%"></h:outputText>
</rich:progressBar>
...]]> </programlisting>  
      
      
      <para>
 In the shown example 
   <emphasis><property> &quot;progressVar&quot;</property></emphasis> attribute
  gets the &quot;progress&quot; value which contains data taken from 
 <emphasis><property>&quot;value&quot;</property></emphasis>
   attribute of  a 
  <emphasis role="bold"><property>&lt;rich:progressBar&gt;</property>  </emphasis>
        and transfers the received data to the &quot;value&quot; attribute of <property>&lt;h:outputText&gt;</property>  JSF tag, to make the data appear on the page. 
      </para>
<!--Macrosubs-->
      
      
      
      
      <para>
        The <emphasis role="bold"><property>&lt;rich:progressBar&gt;</property>  </emphasis>
        component provides  3 predefined macrosubstitution parameters: 
       
        <itemizedlist>
          <listitem>
            <para><property><emphasis><property>{value}</property></emphasis></property>  contains <emphasis><property>&quot;value&quot;</property></emphasis></para>
          </listitem>
          <listitem>
            <para><property><emphasis><property>{minValue}</property></emphasis></property>  contains <emphasis><property>&quot;minValue&quot;</property></emphasis></para>
          </listitem>
          <listitem>
            <para><property><emphasis><property>{maxValue}</property></emphasis></property>  contains <emphasis><property>&quot;maxValue&quot;</property></emphasis></para>
          </listitem>
        </itemizedlist>
           
        You can use them as follows: 
      </para>
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="XML"><![CDATA[...
<rich:progressBar value="#{bean.incValue1}" minValue="400" maxValue="900">
        <h:outputText value="Min value is {minValue}, current value is {value}, max value is {maxValue}"></h:outputText>
</rich:progressBar> 
 ...]]> </programlisting>    
      <figure>
        <title>Macrosubstitution</title>  
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/progressbar_macrosubs.png"/>
          </imageobject>
        </mediaobject>     
      </figure> 




 <!--END of  Macrosubs-->
      <!-- Parameters-->
      <para>
        The <emphasis><property>&quot;parameters&quot;</property></emphasis>
        is also a special attribute that can be used for substitutional purposes.      
        All you need is to define a value of your own parameter
        (e.g parameters=&quot;param:&apos;#{bean.incValue1}&apos;&quot;)
        and you can use it to pass the data. 
           </para> 
        
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
        
        <programlisting role="XML"><![CDATA[...
<progressBar:progressBar value="#{bean.incValue1}" parameters="param:'#{bean.incValue1}'">
    <h:outputText value="{param}%"></h:outputText>
</progressBar:progressBar>
...]]> </programlisting>     
        
      
      
      <!-- END Parameters-->




      <para> The <emphasis><property>&quot;interval&quot;</property></emphasis>attribute defines the frequency of status polling. Polling is active while the component is operational. </para>   
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        
 <programlisting role="XML"><![CDATA[...
<rich:progressBar value="#{bean.incValue}" id="progrs" interval="900"/>
...]]> </programlisting>     
      
      
      
      
        <para> The <emphasis><property>&quot;parameters&quot;</property></emphasis>attribute allows to send some
            dynamical data to the component which is displayed in the informational part.
            Parameters can be passed through <emphasis><property>&quot;parameters&quot;</property></emphasis> attribute, or from component control.</para>   
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<rich:progressBar progressVar="progress" parameters="param1:'1'"  >
		<h:outputText="{param1} task #{progress} %"/>
</rich:progressBar>
...]]> </programlisting>     

        <para>
     The component can also employ  <emphasis><property> &quot;initial&quot;</property></emphasis> and <emphasis><property> &quot;complete&quot;</property></emphasis>
     facets to display the states of the process: <emphasis><property> &quot;initial&quot;</property></emphasis> facet is displayed when the progress value is less or equal to <emphasis><property> &quot;minValue&quot;</property></emphasis>
     , and the  <emphasis><property> &quot;complete&quot;</property></emphasis> facet is shown when the value is greater or equal to <emphasis><property> &quot;maxValue&quot;</property></emphasis>. Please see an example below.  
        </para>
        <para>
            <emphasis role="bold">Example:</emphasis>
        </para>
        <programlisting role="XML"><![CDATA[...
<rich:progressBar value="#{bean.incValue1}" >
    <f:facet name="initial">
        <h:outputText value="Process not started"></h:outputText>
    </f:facet>
    <f:facet name="complete">
        <h:outputText value="Process completed"></h:outputText>
    </f:facet>
</rich:progressBar> 
 ...]]> </programlisting>       
        <para> However, the usage of these facets is optional. If you omit them nothing will be displayed.
        </para>
        <para>The <emphasis role="bold"><property>&lt;rich:progressBar&gt;</property>  </emphasis> component can be used in two modes: Ajax (default) and Client.  In order to define the mode you need to  use <emphasis><property>&quot;mode&quot;</property></emphasis> attribute. 
        </para>   
        <itemizedlist>
             <listitem>
                 <para><property>Ajax</property> - polling is activated when the component is enabled to check its value. </para>
             </listitem>
            <listitem>
                <para><property>Client</property> - component updates after its value changed through JavaScript API. </para>
            </listitem>
        </itemizedlist>
        
                  
    </section>
    <!-- End. Details of Usage-->
    
    <!-- JavaScript API-->  
 <section>
        <title>JavaScript API</title>
        <table> 
            <title>JavaScript API</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Function</entry>
                        <entry>Description</entry>
                      
                    </row>
                </thead>
                <tbody>
                    <!--Sorting API -->
                    <row>
                        <entry>enable()</entry>
                        <entry>Begins polling for ajax mode </entry>
             
                    </row>
                    <row>
                        <entry>disable()</entry>
                        <entry>Stops polling for ajax mode</entry>
          
                    </row>
                    
                    <row>
                        <entry>setValue(value)</entry>
                        <entry>Updates the progress of the process</entry>
                        
                    </row>
                    <row>
                        <entry>setLabel(label)</entry>
                        <entry>Update the label for the process</entry>
                        
                    </row>
                    
                    
                    
                    
                </tbody>
            </tgroup>
        </table>
    </section>
    <!-- End of JavaScript API-->   
    
    <!-- Look-and-Feel Customization-->  
    
    <section>
        <title>Look-and-Feel Customization</title>
        <para>For skinnability implementation, the components use a <emphasis>
            <property>style class redefinition method.</property>
        </emphasis> Default style classes are mapped on <emphasis>
            <property>skin parameters.</property>
        </emphasis></para>
        <para>There are two ways to redefine the appearance of all <emphasis role="bold">
            <property>&lt;rich:progressBar&gt;</property>
        </emphasis> components at once: <itemizedlist>
            <listitem>Redefine the corresponding skin parameters</listitem>
            <listitem> Add to your style sheets style classes used by a <emphasis role="bold">
                <property>&lt;rich:progressBar&gt;</property>
            </emphasis> component</listitem>
        </itemizedlist>
        </para>
    </section>
       
  <!-- Skin Parameters Redefinition-->  
 <section>
    <title>Skin Parameters Redefinition</title>

    <table>
      <title>Skin parameters redefinition for the &quot;completed&quot; part of the bar with no label</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>selectControlColor</entry>

            <entry>background-color</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for the &quot;completed&quot; part of the bar with a label used</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-color</entry>
          </row>

           </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for the “completed” part of the bar with a label used</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>selectControlColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>controlBackgroundColor</entry>

            <entry>color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for the &quot;remained&quot; part of the bar</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>controlBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>controlTextColor</entry>

            <entry>color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for the bar itself with a label used</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>panelBorderColor</entry>

            <entry>border-color</entry>
          </row>

          <row>
            <entry>generalFamilyFont</entry>

            <entry>font-family</entry>
          </row>

          <row>
            <entry>headerFamilyFont</entry>

            <entry>font-family</entry>
          </row>

          <row>
            <entry>generalSizeFont</entry>

            <entry>font-size</entry>
          </row>

          <row>
            <entry>controlTextColor</entry>

            <entry>color</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for the bar itself with no label used</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>controlBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>panelBorderColor</entry>

            <entry>border-color</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    
  </section>
  <!-- END Skin Parameters Redefinition-->  

  <!-- Definition of Custom Style Classes-->  

  <section>
    <title>Definition of Custom Style Classes</title>
    <para>On the screenshot there are classes names that define styles for component elements.</para>
    
    <figure>
      <title>Classes names</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/progressbarClasses.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <table>
      <title>Classes names for the bar</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>rich-progress-bar-shell</entry>
            <entry>Defines styles for the background and the borders of the bar when label is not used</entry>
          </row>
          
          <row>
            <entry>rich-progress-bar-shell-dig</entry>
            <entry>Defines styles for background, font and border settings when label is used</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    
    <table>
      <title>Classes names that define &quot;completed&quot; part of the bar</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          
          <row>
            <entry>rich-progress-bar-uploaded</entry>
            <entry>Defines styles for of &quot;completed&quot; progress area with no labels used</entry>
          </row>
          <row>
            <entry>rich-progress-bar-uploaded-dig</entry>
            <entry>Defines styles for that &quot;completed&quot; progress area with labels used </entry>
          </row>
          
          <row>
            <entry>rich-progress-bar-completed</entry>
            <entry>Defines styles for the &quot;completed&quot; progress area with a label used</entry>
          </row>
          
          
        </tbody>
      </tgroup>
    </table>
    
    
    
    <table>
      <title>Classes names that define &quot;remained&quot; part of the progress area</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          
          <row>
            <entry>rich-progress-bar-remained</entry>
            <entry>Defines styles for the &quot;remained&quot; part of the bar</entry>
          </row>
  
          
          
        </tbody>
      </tgroup>
    </table>
    <para>In order to redefine styles for all <emphasis role="bold">
      <property>&lt;rich:progressBar&gt;</property>
    </emphasis> components on a page using CSS, it&apos;s enough to create classes with the
      same names (possible classes could be found in the tables <link linkend="tab_cn3"> above</link>) and define necessary properties in them. </para> 
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-progress-bar-remained{									
    background-color: #ebf3fd;							
}	
...]]></programlisting>  
    
    <para>This is the result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/progressbarRedefinedClasses.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <para>In the example the &quot;remained&quot; part of progress area is modified with a background-color CSS property.</para>
    
    
    
    
    
    <para>It&apos;s aslo possible to change styles of a particular 
      <emphasis role="bold"> <property>&lt;rich:progressBar&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"><property>&lt;rich:progressBar&gt;</property></emphasis> <property>styleClass</property> attributes. An example is placed below:</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.RremainClass{  background-color: #ebf3fd;}
...]]></programlisting>  
    <para>The <emphasis><property>&quot;styleClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:progressBar&gt; </property></emphasis> is defined as it’s shown in the example below:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[<rich:progressBar value="#{bean.incValue1}" styleClass="remainClass" />
]]></programlisting>    
    
    <para>This is a result:</para>
    
    <figure>
      <title>Modificaton of a look and feel with own classes and <emphasis><property>styleClass</property></emphasis> attributes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/progressbarRedefinedClasses.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above, the font style for output text was changed.</para>
    
    
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/progressbar.jsf?c=progressbar">Here</ulink>
      you can see the example of <emphasis role="bold">
        <property>&lt;rich:progressBar&gt;</property>
      </emphasis> usage and sources for the given example. </para>
   
  </section>
</section>
