<?xml version='1.0' encoding='UTF-8'?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>scroller</keyword>
      <keyword>rich:datascroller</keyword>
      <keyword>Htmldatascroller</keyword>
      <keyword>tables</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.Datascroller</entry>
        </row>
        <row>
          <entry>component-class</entry>
          <entry>org.richfaces.component.html.HtmlDatascroller</entry>
        </row>
        <row>
          <entry>component-family</entry>
          <entry>org.richfaces.Datascroller</entry>
        </row>
        <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.DataScrollerRenderer</entry>
        </row>
        <row>
          <entry>tag-class</entry>
          <entry>org.richfaces.taglib.DatascrollerTag</entry>
        </row>
      </tbody>
    </tgroup>
  </table>

  <section>
    <title>Creating the Component with a Page Tag</title>
    <para>Here is a simple example as it could be used on a page:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <h:dataTable id="table">
        ...
    </h:dataTable>
    ...
    <rich:datascroller for="table"/>
...
]]></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.HtmlDatascroller;
...	
HtmlDatascroller myScroll = new HtmlDatascroller();
...
]]></programlisting>
  </section>
  <section>
    <title>Details of Usage</title>
    <para>The <emphasis role="bold">
      <property>&lt;rich:datascroller&gt;</property>
    </emphasis> component provides table scrolling functionalitity the same as TOMAHAWK scroller but
      with Ajax requests usage.</para>
    <para>The component should be placed into footer of the parent table or be bound to it with the <emphasis>
      <property>&quot;for&quot;</property>
    </emphasis> attribute. Note, that <emphasis><property>&quot;for&quot;</property></emphasis> is evaluated on view build, not on view render, that is why it will ignore JSTL tags.</para>
    <para>The table should also have the defined <emphasis>
      <property>&quot;rows&quot;</property>
    </emphasis> attribute limiting the quantity of inputted table rows.</para>
    <para>The scroller could limit the maximum quantity of rendered links on the table pages with
      the help of the <emphasis>
        <property>&quot;maxPages&quot;</property>
      </emphasis> attribute.</para>
    <para>Component provides two controllers groups for switching:</para>
    <itemizedlist>
      <listitem><para>Page numbers for switching onto a particular page</para></listitem>
      <listitem><para>The controls of fast switching: <emphasis>
        <property>&quot;first&quot;,</property>
      </emphasis>
        <emphasis>
          <property>&quot;last&quot;,</property>
        </emphasis>
        <emphasis>
          <property>&quot;next&quot;,</property>
        </emphasis>
        <emphasis>
          <property>&quot;previous&quot;,</property>
        </emphasis>
        <emphasis>
          <property>&quot;fastforward&quot;,</property>
        </emphasis>
        <emphasis>
          <property>&quot;fastrewind&quot;</property>
        </emphasis></para></listitem>
    </itemizedlist>
    <para>The controls of fast switching are created adding the facets component with the
      corresponding name:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[ ...
    <rich:datascroller for="table" maxPages="10">
        <f:facet name="first">
            <h:outputText value="First"/>
        </f:facet>
        <f:facet name="last">
            <h:outputText value="Last"/>
        </f:facet>
    </rich:datascroller>
...
]]></programlisting>
    <figure>
      <title><emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> controls of fast switching</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/datascroller2.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <para>The screenshot shows one controller from each group.</para>
    <para> There are also facets used to create the disabled states: 
      <code>&quot;first_disabled&quot;,</code>
      <code>&quot;last_disabled&quot;,</code>
      <code>&quot;next_disabled&quot;,</code>
      <code>&quot;previous_disabled&quot;,</code>
      <code>&quot;fastforward_disabled&quot;,</code>
      <code>&quot;fastrewind_disabled&quot;</code>. </para>
    <para>For the <code>&quot;fastforward&quot;/&quot;fastrewind&quot;</code>
    controls customization the additional <emphasis>
      <property>&quot;fastStep&quot;</property>
    </emphasis> attribute is used. The attribute indicates pages quantity to switch onto when fast
      scrolling is used. </para>
      
    <para>
    	The <emphasis><property>&quot;page&quot;</property></emphasis> is a value-binding attribute used to
    	define and save current page number. The example is placed below.
    </para>  
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<h:form id="myForm">
	<rich:dataTable id="carList" rows="7" value="#{dataTableScrollerBean.allCars}" var="category">
		<f:facet name="header">
			<rich:columnGroup>
				<h:column>
					<h:outputText value="Make" />
				</h:column>
				<h:column>
					<h:outputText value="Model" />
				</h:column>
				<h:column>
					<h:outputText value="Price" />
				</h:column>
			</rich:columnGroup>
		</f:facet>
		<h:column>
			<h:outputText value="#{category.make}" />
		</h:column>
		<h:column>
			<h:outputText value="#{category.model}" />
		</h:column>
		<h:column>
			<h:outputText value="#{category.price}" />
		</h:column>
	</rich:dataTable>
	<rich:datascroller id="sc2" for="carList" reRender="sc1" maxPages="7" page="#{dataTableScrollerBean.scrollerPage}" />
	<h:panelGrid>
		<h:panelGroup>
			<h:outputText value="Set current page number:" />
			<h:inputText value="#{dataTableScrollerBean.scrollerPage}" id="sc1" size="1"/>
			<h:commandButton value="Set" />	
		</h:panelGroup>
	</h:panelGrid>
</h:form>      
...
]]></programlisting>

	<para>
	 In the example above you can enter the page number you want and set it by clicking 
	 on the <emphasis role="bold"><property>&lt;h:commandButton&gt;</property></emphasis>. By the way, 
	 if you use <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> page links
	 the input field rerenders and current page number changes.
	</para>
	<para>
	 This is a result:
	</para>
	<figure>
      <title>The <emphasis><property>&quot;page&quot;</property></emphasis> attribute usage</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/datascroller3.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <!--
    	The <emphasis><property>&quot;pageIndexVar&quot;</property></emphasis> and <emphasis>
      <property>&;pagesVar&quot;</property>
    </emphasis> attributes provide an ability to show the current page and the number of pages in
      the <emphasis role="bold">
      <property>&lt;rich:datascroller&gt;</property>
    </emphasis>. 
    -->
    
    
    <para>
	    The <emphasis><property>&quot;pageIndexVar&quot;</property></emphasis> 
	    and <emphasis><property>&quot;pagesVar&quot;</property></emphasis> attributes 
	    define a request scope variables and provide an ability to show the current page
	    and the number of pages in the 
	    <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis>.
    </para>
    <para>
    	These attributes are used for definition the names of variables, 
    	that is used in the facet with name <emphasis><property>&quot;pages&quot;</property></emphasis>.
    	An example can be found below: </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<h:form>
	<rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5">
		<rich:column>
			<h:outputText value="#{cap.name}" />
		</rich:column>
		<f:facet name="footer">
			<rich:datascroller pageIndexVar="pageIndex" pagesVar="pages">
				<f:facet name="pages">
					<h:outputText value="#{pageIndex} / #{pages}" />
				</f:facet>
			</rich:datascroller>
		</f:facet>
	</rich:dataTable>
</h:form>
...
]]></programlisting>
    <para> It&apos;s possible to insert optional separators between controls. For this purpose use a <emphasis>
      <property>&quot;controlSeparator&quot;</property>
    </emphasis> facet. An example is placed below. </para>
    <programlisting role="XML"><![CDATA[ ...
      <f:facet name="controlSeparator">
            <h:graphicImage value="/image/sep.png"/>
      </f:facet>
...
]]></programlisting>
    <para>
      Starting from 3.2.1 of RichFaces multiple <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> instances behavior and page bindings are corrected. Incorrect page after model changes handling is added. 
      Phase Listener called before RenderResponce scans the page for the <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> and performs the following operations:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Checks if the <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> is rendered. (If the checking generates an exception, the <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> is considered to be not rendered )
        </para>
      </listitem>
      <listitem>
        <para>
          If the <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> is rendered -  the table to which the <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> is attached gets the value of the page attribute of <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis>. 
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Information about the <emphasis><property>&quot;process&quot;</property></emphasis> attribute usage you can find <link linkend="process">here</link>.
    </para>
    <note>
      <title>Note:</title>
      <para>Make sure, that all <emphasis role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> components, defined for a table, have same values for <emphasis><property>&quot;pages&quot;</property></emphasis> attributes. 
        The page, specified in the last <emphasis><property>&quot;page&quot;</property></emphasis>, will be rendered in browser.
      </para>
    </note>
  </section>
  
  <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:datascroller&gt;</property>
    </emphasis> components at once:</para>
    
    <itemizedlist>
      <listitem>
        <para>Redefine the corresponding skin parameters</para>
      </listitem>
      
      <listitem>
        <para>Add to your style sheets <emphasis>
          <property>style classes</property>
        </emphasis> used by a <emphasis role="bold">
          <property>&lt;rich:datascroller&gt;</property>
        </emphasis> component</para>
      </listitem>
    </itemizedlist>
  </section>
  
  <section>
    <title>Skin Parameters Redefinition</title>
    <table>
      <title>Skin parameters redefinition for a wrapper element</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>tableBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a button</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>additionalBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
          <row>
            <entry>generalSizeFont</entry>
            <entry>font-size</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for an active button</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>generalTextColor</entry>
            <entry>border-top-color</entry>
          </row>
          <row>
            <entry>generalTextColor</entry>
            <entry>color</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
          <row>
            <entry>generalSizeFont</entry>
            <entry>font-size</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for an inactive button</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>headerBackgroundColor</entry>
            <entry>border-top-color</entry>
          </row>
          <row>
            <entry>headerBackgroundColor</entry>
            <entry>color</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
          <row>
            <entry>generalSizeFont</entry>
            <entry>font-size</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    </section>

    <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>Style classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/datascroller_cn.png"/>
        </imageobject>
      </mediaobject>
    </figure>

      <table id="tab_cn2">
      <title>Classes names that define a component appearance</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>rich-datascr</entry>
            <entry>Defines styles for a wrapper  &lt;div&gt; element of a datascroller</entry>
          </row>
          <row>
            <entry>rich-dtascroller-table</entry>
            <entry>Defines styles for a wrapper table element of a datascroller</entry>
          </row>
          <row>
            <entry>rich-datascr-button</entry>
            <entry>Defines styles for a button</entry>
          </row>
          
          <row>
            <entry>rich-datascr-ctrls-separator</entry>
            <entry>Defines styles for a separator between buttons</entry>
          </row>
        </tbody>

      </tgroup>
    </table>
    <table>
      <title>Classes names that define a buttons appearance</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>rich-datascr-act</entry>
            <entry>Defines styles for an active button</entry>
          </row>
          <row>
            <entry>rich-datascr-inact</entry>
            <entry>Defines styles for an inactive button</entry>
          </row>
          <row>
            <entry>rich-datascr-button-dsbld</entry>
            <entry>Defines styles for a disabled button</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
      
      <para>In order to redefine styles for all <emphasis role="bold">
        <property>&lt;rich:datascroller&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 table <link linkend="tab_cn2">above</link>) and define necessary properties in them. An example is placed below:</para>
      
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="CSS"><![CDATA[...
.rich-datascr-button{
    color: #CD6600;
}
...]]></programlisting>  
      
      <para>This is a result:</para>
      
      <figure>
        <title>Redefinition styles with predefined classes</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/datascroller_pc.png"/>
          </imageobject>
        </mediaobject>
      </figure>
      
      <para>In the example an input text font style was changed.</para>
      
      <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
        ><property>&lt;rich:datascroller&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
          ><property>&lt;rich:datascroller&gt;</property></emphasis> <emphasis role="italic"><property>styleClass</property></emphasis> attributes. An example is placed below:</para>
      
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="CSS"><![CDATA[...
.myClass{
    background-color: #C6E2FF;
}
...]]></programlisting>  
      <para>The <emphasis role="italic"><property>&quot;styleClass&quot;</property></emphasis> attribute for <emphasis role="bold"
        ><property>&lt;rich:datascroller&gt; </property></emphasis> is defined as it&apos;s shown in the example below:</para>
      
      <para>
        <emphasis role="bold">Example:</emphasis>
      </para>
      <programlisting role="XML"><![CDATA[<rich:datascroller ... selectedStyleClass="myClass"/>
]]></programlisting>    
      
      <para>This is a result:</para>
      
      <figure>
        <title>Redefinition styles with own classes and <emphasis><property>styleClass</property></emphasis> attributes</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="images/datascroller_oc.png"/>
          </imageobject>
        </mediaobject>
      </figure>  
      
      <para>As it could be seen on the picture above, background color of the selected cell on scroller  was changed.</para>   
      
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink
        url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataTableScroller.jsf?c=dataTableScroller"
        >Here</ulink> you can see the example of <emphasis role="bold"
        ><property>&lt;rich:datascroller&gt;</property></emphasis> usage and sources for the given example. </para>
    <para> The solution about how to do correct pagination using datascroller (load a part of data from
      database) can be found on the <ulink
        url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4060199#4060199"
        >RichFaces Users Forum</ulink>. </para>
    <para>How to use <emphasis role="bold"><property>&lt;rich:dataTable&gt;</property></emphasis> and <emphasis
      role="bold"><property>&lt;rich:datascroller&gt;</property></emphasis> in a context of Extended
      Data Model see <ulink
        url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;t=115636"
        >here</ulink>.</para>
  </section>
</section>
