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

<section>
  <sectioninfo>
    <keywordset>
      <keyword>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>Dynamical creation from Java code</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 (header, footer) and columns.
	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.
	User can define the number of the fixed columns  from the left side using attribute <emphasis><property>&quot;frozenColCount&quot;</property></emphasis> that will not be 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 'true' data will be hidden during scrolling. 
	</para>
	
	<para>
	It'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:
	<itemizedlist>
			<listitem>Just clicking the columns one by one.</listitem>
			<listitem>Clicking some row with the SHIFT button hold.
	In this case all the rows starting from last selected up to clicked should be selected.</listitem>
	</itemizedlist>
	</para>
	
	<para>
	The columns provides the possibility of expanding/collapsing on the client side through the next JS API:
	
	<itemizedlist>
			<listitem>doCollapse(columnId) - Performs the collapse action for the column with the corresponding id</listitem>
	</itemizedlist>

	It'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 will be used for sorting the table.
	
	In case the <property>&lt;rich:scrollableDataTable&gt;</property> is already sorted by some
	column and the header of this column has been clicked again - the sorting will be
	reversed.
	</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>
Finally, the component has the following extra attributes for event processing on the client:
	<itemizedlist>
			<listitem>onselectionchange</listitem>
			<listitem>oncomplete</listitem>
			<listitem>onRowClick</listitem>
			<listitem>onRowDblClick</listitem>
			<listitem>onRowMouseUp</listitem>
			<listitem>onRowMouseDown</listitem>
	</itemizedlist>

</para>	
   </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 element</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 element</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 row and cells</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <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>tableBorderColor</entry>
            <entry>border-bottom-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    
    <table>
      <title>Skin parameters for selected row and cells</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>
    
    <figure>
      <title>Classes names</title>
      
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/sdt.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <para>On the screenshot, there are classes names defining specified elements.</para>
    
    <table>
      <title>Classes names that define 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 the styles for the 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-footer-cell</entry>
            
            <entry>Defines styles for footer cells</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 rows and cells appearance</title>
      
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            
            <entry>Description</entry>
          </row>
        </thead>
        
        <tbody>
          
          <row>
            <entry>rich-sdt-column-cell</entry>
            
            <entry>Defines styles for column cells</entry>
          </row>
          
          <row>
            <entry>rich-sdt-row-selected</entry>
            
            <entry>Defines styles for selected row</entry>
          </row>
          
          <row>
            <entry>rich-sdt-row-active</entry>
            
            <entry>Defines styles for active row</entry>
          </row>
          
        </tbody>
      </tgroup>
    </table>
    
    <para>In order to redefine the style 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 and define the necessary properties in them.</para>
    
    <para>To change the style of particular <emphasis role="bold">
      <property>&lt;rich:scrollableDataTable&gt;</property>
    </emphasis> components define your own style classes in the corresponding <emphasis
      role="bold">
      <property>&lt;rich:scrollableDataTable&gt;</property>
    </emphasis>attributes.</para>
  </section>
   
  <section>
    <title>Relevant resources links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/scrollableDataTable.jsf?c=scrollableDataTable">Here</ulink>
      you can see the example of <emphasis role="bold">&lt;rich:scrollableDataTable&gt;</emphasis> usage. </para>
  </section> 
</section>
