<?xml version='1.0' encoding='UTF-8'?>

<section>
          <sectioninfo>
                    <keywordset>
                              <keyword>rich:scrollableDataTable</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.component.ScrollableDataTable</entry>
                                        </row>
                                        <row>
                                                  <entry>component-class</entry>
                                                  <entry>org.richfaces.component.html.HtmlScrollableDataTable</entry>
                                        </row>
                                        <row>
                                                  <entry>component-family</entry>
                                                  <entry>org.richfaces.component.ScrollableDataTable</entry>
                                        </row>
                                        <row>
                                                  <entry>renderer-type</entry>
                                                  <entry>org.richfaces.renderkit.html.ScrollableDataTableRenderer</entry>
                                        </row>
                                        <row>
                                                  <entry>tag-class</entry>
                                                  <entry>org.richfaces.taglib.ScrollableDataTableTag</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[...
    <rich:scrollableDataTable value="#{dataTableScrollerBean.allCars}" var="category">
        <!--...//Set of columns and header/footer facets-->
    </rich:scrollableDataTable>
...
]]></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.HtmlScrollableDataTable;
...
HtmlScrollableDataTable myScrollableDataTable = new HtmlScrollableDataTable();
...
]]></programlisting>
          </section>

          <section>
                    <title>Details of Usage</title>
                    <para> The component represents on a page as a scrollable table with some fixed
                              (non-scrollable) rows ( with header and footer) and columns. Like
                              other tables <emphasis role="bold">
                                        <property>&lt;rich:scrollableDataTable&gt;</property>
                              </emphasis> also has optional footer and header that could be
                              implemented using the corresponding facets. Columns of the table are
                              optionally resizable. Resizing is available using "drag and drop" of
                              the column vertical borders. There is possibility to expand or
                              collapse the columns through JS API on the client side. You can define
                              the number of the fixed columns from the left side using attribute <emphasis>
                                        <property>&quot;frozenColCount&quot;</property>
                              </emphasis> that is not scrolled via horizontal scroll. </para>
                    <para> There is possibility to increase component performance using attribute <emphasis>
                                        <property>&quot;hideWhenScrolling&quot;</property>
                              </emphasis>. If attribute value is &quot;true&quot; data is
                              hidden during scrolling. </para>

                    <para> It&apos;s possible to select the whole row with onclick on the row or
                              some set of rows. Selection is optional and availability of such
                              feature is defined on the component. There are two ways to select a
                              few rows: </para> <itemizedlist>
                                        <listitem>
                                                  <para>Just clicking the columns one by one.</para>
                                        </listitem>
                                        <listitem>
                                                  <para>Clicking some row with the SHIFT button
                                                  hold. In this case all the rows starting
                                                  from last selected up to clicked should
                                                  be selected.</para>
                                        </listitem>
                              </itemizedlist>
                    

                    <para> The columns provides the possibility of expanding/collapsing on the
                              client side through the next JS API:</para> <itemizedlist>
                                        <listitem>
                                                  <para><code>collapse(columnId)</code> - Performs
                                                  the collapse action for the column with
                                                  the corresponding id</para>
                                        </listitem>
                              </itemizedlist> 
                              <para> It&apos;s possible to sort the table content after
                              clicks on the header. The feature is optional. Every column should be
                              pointed to the comparator method that is used for sorting the table.
                              In case the <emphasis role="bold">
                                        <property>&lt;rich:scrollableDataTable&gt;</property>
                              </emphasis> is already sorted by some column and the header of this
                              column has been clicked again - the sorting is reversed. </para>
                    <para>After sorting selection that was made before is reset</para>

                    <para>
                              <emphasis role="bold">The typical variant of using:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
<rich:scrollableDataTable value="#{modelBuilder.model}" var="issues"
			frozenColCount="1"
			first="0"
			rows="40" 
			width="300px"
			height="396px">
	<rich:column width="100px">
		<f:facet name="header" >
			<h:outputText value="State"/>
		</f:facet>
		<h:outputText value="#{issues.cell1}"/>
		<f:facet name="footer">
			<h:outputText value="State"/>
		</f:facet>
	</rich:column>		
	<!--...//Set of columns and header/footer facets-->
</rich:scrollableDataTable>
...
]]></programlisting>

                    <para>The <emphasis>
                                        <property>&quot;selection&quot;</property>
                              </emphasis> attribute allows to get the row data when using
                                        <property>one and multi-selection rows mode</property>.</para>
                    <para>This attribute is a reference to object to the instance of
                              
                              <ulink url="http://www.jboss.org/file-access/default/members/jbossrichfaces/freezone/docs/apidoc_framework/org/richfaces/model/selection/Selection.html">     <code>org.richfaces.model.selection.Selection</code></ulink>.
                              interface
                    
                                                                  
                              interface, containing current collection of objects selected by you.</para>
                    <para>In the following example when you submit the form, current collection of
                              the selected objects is placed in the object&apos;s property. Then
                              on complete action the <emphasis role="bold">
                                        <property>&lt;rich:modalPanel&gt;</property>
                              </emphasis> with selected data is shown.</para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
		<h:form>
			<rich:spacer height="30" />
			<rich:scrollableDataTable rowKeyVar="rkv" frozenColCount="1" height="200px" 
				width="300px" id="carList" rows="40" columnClasses="col"
				value="#{dataTableScrollerBean.allCars}" var="category" sortMode="single"
				selection="#{dataTableScrollerBean.selection}">
				<rich:column id="make">
					<f:facet name="header"><h:outputText styleClass="headerText" value="Make" /></f:facet>
					<h:outputText value="#{category.make}" />
				</rich:column>
				<rich:column id="model">
					<f:facet name="header"><h:outputText styleClass="headerText" value="Model" /></f:facet>
					<h:outputText value="#{category.model}" />
				</rich:column>
				<rich:column id="price">
					<f:facet name="header"><h:outputText styleClass="headerText" value="Price" /></f:facet>
					<h:outputText value="#{category.price}" />
				</rich:column>
				</rich:scrollableDataTable>
			<rich:spacer height="20px"/>
			<a4j:commandButton value="Show Current Selection" reRender="table" 
				action="#{dataTableScrollerBean.takeSelection}" 
				oncomplete="javascript:Richfaces.showModalPanel('panel');"/>
		</h:form>
		<rich:modalPanel id="panel" autosized="true">
				<f:facet name="header">
					<h:outputText value="Selected Rows"/>
				</f:facet>
				<f:facet name="controls">
					<span style="cursor:pointer" onclick="javascript:Richfaces.hideModalPanel('panel')">X</span>
				</f:facet>
			<rich:dataTable value="#{dataTableScrollerBean.selectedCars}" var="sel" id="table">
				<rich:column>
					<f:facet name="header"><h:outputText value="Make" /></f:facet>
					<h:outputText value="#{sel.make}" />
				</rich:column>
				<rich:column id="model">
					<f:facet name="header"><h:outputText value="Model" /></f:facet>
					<h:outputText value="#{sel.model}" />
				</rich:column>
				<rich:column id="price">
					<f:facet name="header"><h:outputText value="Price" /></f:facet>
					<h:outputText value="#{sel.price}" />
				</rich:column>
				</rich:dataTable>
		</rich:modalPanel>
...]]></programlisting>
                    <para>This is a result:</para>
                    <figure>
                              <title>The <emphasis>
                                                  <property>&quot;selection&quot;</property>
                                        </emphasis> attribute usage</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata
                                                  fileref="images/scrollableDataTable2.png"
                                                  />
                                        </imageobject>
                              </mediaobject>
                    </figure>
                    <para><ulink
                                        url="http://wiki.jboss.org/wiki/RichFacesCookbook/ScrollableDataTableSelectionUsage"
                                        >On RichFaces LiveDemo page </ulink> you can find fuller example of use of this
                              attribute with example bean.</para>
                    <para> The <emphasis role="bold">
                                        <property>&lt;rich:scrollableDataTable&gt;</property>
                              </emphasis> component has the following extra attributes for event
                              processing on the client:</para> <itemizedlist>
                                        <listitem>
                                                  <para>
                                                  <emphasis>
                                                  <property>&quot;onselectionchange&quot;</property>
                                                  </emphasis>
                                                  </para>
                                        </listitem>
                                        <!-- <listitem>
                                                  <para>
                                                  <emphasis>
                                                  <property>&quot;oncomplete&quot;</property>
                                                  </emphasis>
                                                  </para>
                                                  </listitem>  -->
                                        <listitem>
                                                  <para>
                                                  <emphasis>
                                                  <property>&quot;onRowClick&quot;</property>
                                                  </emphasis>
                                                  </para>
                                        </listitem>
                                        <listitem>
                                                  <para>
                                                  <emphasis>
                                                  <property>&quot;onRowDblClick&quot;</property>
                                                  </emphasis>
                                                  </para>
                                        </listitem>
                                        <listitem>
                                                  <para>
                                                  <emphasis>
                                                  <property>&quot;onRowMouseUp&quot;</property>
                                                  </emphasis>
                                                  </para>
                                        </listitem>
                                        <listitem>
                                                  <para>
                                                  <emphasis>
                                                  <property>&quot;onRowMouseDown&quot;</property>
                                                  </emphasis>
                                                  </para>
                                        </listitem>
                              </itemizedlist>
                   
                    <para>Information about sorting and filtering you can find in RichFaces Developer guide section about<link linkend="sort"
                                        >sorting</link>.</para>
                    <para> Information about the <emphasis>
                                        <property>&quot;process&quot;</property>
                    </emphasis> attribute usage you can find in the 
                              <link linkend="process"> &quot;Decide what to process&quot; </link> guide section. </para>
                    <note>
                    	<title>Note:</title>
                    	<para>
                    	If you want to use specific features such as pagination on database level you should pass to the 
                    		<emphasis><property>&quot;value&quot;</property></emphasis> of the 
                    		<emphasis role="bold"><property>&lt;rich:scrollableDataTable&gt;</property></emphasis> component
                    		an object which class extends <code>org.richfaces.model.ScrollableTableDataModel</code>.
                    	</para>
                    </note>
          </section>


          <section>
                    <title>JavaScript API</title>
                    <table>
                              <title>JavaScript API</title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Function</entry>

                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>

                                        <tbody>

                                                  <row>
                                                  <entry>collapse(columnId)</entry>

                                                  <entry>Performs a collapse action for
                                                  column with corresponding
                                                  Id</entry>
                                                  </row>

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

          </section>

          <section>
                    <title>Facets</title>
                    <table>
                              <title>Facets</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                            <entry>Facet</entry>
                                                            <entry>Description</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                            <entry>header</entry>
                                                            <entry>Defines the header content</entry>
                                                  </row>
                                                  <row>
                                                            <entry>footer</entry>
                                                            <entry>Defines the footer content</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table> 
          </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:scrollableDataTable&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:scrollableDataTable&gt;</property>
                                                  </emphasis> component</para>
                              </listitem>
                    </itemizedlist>
          </section>

          <section>
                    <title>Skin Parameters Redefinition</title>
                    <table>
                              <title>Skin parameters for all table</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>tableBorderColor</entry>
                                                  <entry>border-color</entry>
                                                  </row>
                                                  <row>
                                                  <entry>tableBorderWidth</entry>
                                                  <entry>border-width</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameters for header rows and cells</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>headerBackgroundColor</entry>
                                                  <entry>background-color</entry>
                                                  </row>

                                                  <row>
                                                  <entry>headerTextColor</entry>
                                                  <entry>color</entry>
                                                  </row>
                                                  <row>
                                                  <entry>generalFamilyFont</entry>
                                                  <entry>font-family</entry>
                                                  </row>
                                                  <row>
                                                  <entry>generalSizeFont</entry>
                                                  <entry>font-size</entry>
                                                  </row>
                                                  <row>
                                                  <entry>tableBorderWidth</entry>
                                                  <entry>border-bottom-width</entry>
                                                  </row>
                                                  <row>
                                                  <entry>tableBorderColor</entry>
                                                  <entry>border-bottom-color</entry>
                                                  </row>
                                                  <row>
                                                  <entry>tableBorderWidth</entry>
                                                  <entry>border-right-width</entry>
                                                  </row>
                                                  <row>
                                                  <entry>tableBorderColor</entry>
                                                  <entry>border-right-color</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameters for footer rows and cells</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>tableSubfooterBackgroundColor</entry>
                                                  <entry>background-color</entry>
                                                  </row>
                                                  <row>
                                                  <entry>generalFamilyFont</entry>
                                                  <entry>font-family</entry>
                                                  </row>
                                                  <row>
                                                  <entry>generalSizeFont</entry>
                                                  <entry>font-size</entry>
                                                  </row>

                                                  <row>
                                                  <entry>tableBorderColor</entry>
                                                  <entry>border-right-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 for column cells </title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>tableBorderColor</entry>
                                                  <entry>border-right-color</entry>
                                                  </row>
                                                  <row>
                                                  <entry>tableBorderColor</entry>
                                                  <entry>border-bottom-color</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameters for active rows</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Skin parameters</entry>
                                                  <entry>CSS properties</entry>
                                                  </row>
                                        </thead>
                                        <tbody>
                                                  <row>
                                                  <entry>tabDisabledTextColor</entry>
                                                  <entry>color</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <table>
                              <title>Skin parameters for selected rows</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>
                                        </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>Classes names</title>

                              <mediaobject>
                                        <imageobject>
                                                  <imagedata
                                                  fileref="images/scrollableDataTable_cn.png"
                                                  scale="90"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <table id="scrdattableC">
                              <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-sdt</entry>

                                                  <entry>Defines styles for a component
                                                  appearance</entry>
                                                  </row>

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

                    <table>
                              <title>Classes names that define footer and header elements</title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>

                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>

                                        <tbody>

                                                  <row>
                                                  <entry>rich-sdt-header-cell</entry>

                                                  <entry>Defines styles for header
                                                  cells</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sdt-header-row</entry>

                                                  <entry>Defines styles for a header
                                                  raw</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sdt-column-cell</entry>

                                                  <entry>Defines styles for column
                                                  cells</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-sdt-footer-cell</entry>

                                                  <entry>Defines styles for footer
                                                  cells</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sdt-footer-row</entry>

                                                  <entry>Defines styles for a footer
                                                  raw</entry>
                                                  </row>
                                                  <row>
                                                  <entry>rich-sdt-hsep</entry>

                                                  <entry>Defines styles for header
                                                  separators</entry>
                                                  </row>

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

                    <table>
                              <title>Classes names that define different states</title>

                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                  <entry>Class name</entry>

                                                  <entry>Description</entry>
                                                  </row>
                                        </thead>

                                        <tbody>

                                                  <row>
                                                  <entry>rich-sdt-row-active</entry>

                                                  <entry>Defines styles for an active
                                                  row</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sdt-row-selected</entry>

                                                  <entry>Defines styles for a selected
                                                  row</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sdt-column-sort-up</entry>

                                                  <entry>Defines styles for ascending
                                                  sorted column</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sdt-column-sort-down</entry>

                                                  <entry>Defines styles for descending
                                                  sorted column</entry>
                                                  </row>
                                        </tbody>
                              </tgroup>
                    </table>

                    <para>In order to redefine styles for all <emphasis role="bold">
                                        <property>&lt;rich:scrollableDataTable&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="scrdattableC"> above</link>) and define
                              necessary properties in them. </para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
.rich-sdt-header-cell{
    font-style:italic;
}
...]]></programlisting>

                    <para>This is a result:</para>

                    <figure>
                              <title>Redefinition styles with predefined classes</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata
                                                  fileref="images/scrollableDataTable_pc.png"
                                                  />
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>In the example the font style for header cell was changed.</para>

                    <para>Also it&apos;s possible to change styles of particular <emphasis
                                        role="bold">
                                        <property>&lt;rich:scrollableDataTable&gt;</property>
                              </emphasis> component. In this case you should create own style
                              classes and use them in corresponding <emphasis role="bold">
                                        <property>&lt;rich:scrollableDataTable&gt;</property>
                              </emphasis>
                              <property>styleClass</property> attributes. An example is placed
                              below:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
.myClass{
    background-color:#ffead9;
}
...]]></programlisting>
                    <para>The <emphasis>
                                        <property>&quot;selectedClass&quot;</property>
                              </emphasis> attribute for <emphasis role="bold">
                                        <property>&lt;rich:scrollableDataTable&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:scrollableDataTable ... selectedClass="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/scrollableDataTable_oc.png"
                                                  />
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>As it could be seen on the picture above, background color for selected
                              item was changed.</para>



          </section>

          <section>
                    <title>Relevant Resources Links</title>
                    <para>
                              <ulink
                                        url="http://livedemo.exadel.com/richfaces-demo/richfaces/scrollableDataTable.jsf?c=scrollableDataTable"
                                        >On the component LiveDemo page</ulink> you can see the example of <emphasis
                                        role="bold">
                                        <property>&lt;rich:scrollableDataTable&gt;</property>
                                        </emphasis> usage. </para>
                    <para>Cookbook article <ulink url="http://www.jboss.org/community/docs/DOC-11857">
                              Scrollable dataTable Selection Usage
                    </ulink> provides a simple example of how you can use the "selection" attribute in order to get row selection in rich:scrollableDataTable. </para>
          </section>
</section>
