<?xml version='1.0' encoding='UTF-8'?>
<section>
<sectioninfo>
<keywordset>
<keyword>rich:column</keyword>
<keyword>colspan</keyword>
<keyword>breakBefore</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.Column</entry>
          </row>
          <row>
            <entry>component-class</entry>
            <entry>org.richfaces.component.html.HtmlColumn</entry>
          </row>
          <row>
          <entry>component-family</entry>
          <entry>org.richfaces.Column</entry>
          </row>
          <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.ColumnRenderer</entry>
          </row>          
          <row>
            <entry>tag-class</entry>
            <entry>org.richfaces.taglib.ColumnTag</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
 
  <section>
    <title>Creating the Component with a Page Tag</title>
    <para>To create the simplest variant of <property>column</property> on a page, use the following syntax:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <rich:dataTable var="set">
        <rich:column>
            <h:outputText value="#{set.property1}"/>
        </rich:column>
        <!--Set of another columns and header/footer facets-->
    </rich:dataTable>
...
]]></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.HtmlColumn;
...
HtmlColumn myColumn = new HtmlColumn();
...
]]></programlisting>
</section>
<section>
<title>Details of Usage</title>
<para>To output a simple table, the <emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> component is used the same way as the standard 
<emphasis role="bold"><property>&lt;h:column&gt;</property></emphasis>, i.e. the following code on a page is used:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
<programlisting role="XML"><![CDATA[...
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> 
        <rich:column>
            <f:facet name="header">State Flag</f:facet>
            <h:graphicImage value="#{cap.stateFlag}"/>
        </rich:column>
        <rich:column>
            <f:facet name="header">State Name</f:facet>
            <h:outputText value="#{cap.state}"/>
        </rich:column>
        <rich:column >
            <f:facet name="header">State Capital</f:facet>
            <h:outputText value="#{cap.name}"/>
        </rich:column>
        <rich:column>
        <f:facet name="header">Time Zone</f:facet>
            <h:outputText value="#{cap.timeZone}"/>
        </rich:column>
    </rich:dataTable>
...
]]></programlisting>
 <para>The result is:</para>
 <figure>
     <title>Generated <emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> component</title>
      <mediaobject> 
        <imageobject>
            <imagedata fileref="images/column2.png"/>
        </imageobject>
    </mediaobject>
    </figure>
<para>Now, in order to group columns with text information into one row in one column with a flag, use
 the <emphasis ><property>&quot;colspan&quot;</property></emphasis> attribute, which is similar to an HTML one, specifying that the first column contains 3 columns.
  In addition, it&apos;s necessary to specify that the next column begins from the first row with the help of the
   <emphasis ><property>&quot;breakBefore&quot;</property></emphasis> attribute = true.</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
   <programlisting role="XML"><![CDATA[...
     <rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> 
        <rich:column colspan="3">
            <h:graphicImage value="#{cap.stateFlag}"/>
        </rich:column>
        <rich:column breakBefore="true"> 
            <h:outputText value="#{cap.state}"/>
        </rich:column>
        <rich:column >
            <h:outputText value="#{cap.name}"/>
        </rich:column>
        <rich:column>
            <h:outputText value="#{cap.timeZone}"/>
        </rich:column>
    </rich:dataTable>
...
]]></programlisting>
<para>As a result the following structure is rendered:</para>
<figure>
    <title><emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> modified with colspan and breakbefore attributes</title>
      <mediaobject> 
        <imageobject>
            <imagedata fileref="images/column3.png"/>
        </imageobject>
    </mediaobject>
    </figure>
     <para>The same way is used for <property>columns</property> grouping with the <emphasis ><property>&quot;rowspan&quot;</property></emphasis> 
    attribute that is similar to an HTML one responsible for rows quantity definition occupied with the 
    current one. The only thing to add in the example is an instruction to move onto the next row for each next after the second column.</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"> 
        <rich:column rowspan="3">
            <f:facet name="header">State Flag</f:facet>
            <h:graphicImage value="#{cap.stateFlag}"/>
        </rich:column>
        <rich:column> 
            <f:facet name="header">State Info</f:facet>
            <h:outputText value="#{cap.state}"/>
        </rich:column>
        <rich:column breakBefore="true">
            <h:outputText value="#{cap.name}"/>
        </rich:column>
        <rich:column breakBefore="true">
            <h:outputText value="#{cap.timeZone}"/>
        </rich:column>
    </rich:dataTable>
...
]]></programlisting>
<para>As a result:</para>
<figure>
    <title><emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> generated with rowspan attribute</title>
      <mediaobject> 
        <imageobject>
            <imagedata fileref="images/column4.png"/>
        </imageobject>
    </mediaobject>
    </figure>
    <para>Hence, additionally to a standard output of a particular row provided with the <emphasis role="bold"><property>&lt;h:column&gt;</property></emphasis> 
    component, it becomes possible to group easily the rows with special HTML attribute.</para>
    <para>The columns also could be grouped in a particular way with the help of the <emphasis role="bold"><property>&lt;h:columnGroup&gt;</property></emphasis>
        component that is described in <link linkend="columnGroup">the following chapter</link>.</para>
</section>
    
    <section id="sortAndFilter">
        <title>Sorting and Filtering</title>
        <section>
            <title>Sorting</title>
            <para>
                In order to sort the columns you could use <emphasis><property>&quot;sortBy&quot;</property></emphasis> attribute 
                which defines a bean property which is used for sorting of a column. See the following example.
            </para>
            <para>
                <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="XML"><![CDATA[...
<h:form>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px">
        <f:facet name="header">
            <h:outputText value="Sorting Example"/>
        </f:facet>
        <rich:column sortBy="#{cap.state}">
            <f:facet name="header">
                <h:outputText value="State Name"/>
            </f:facet>
            <h:outputText value="#{cap.state}"/>
        </rich:column> 
        <rich:column sortBy="#{cap.name}">
            <f:facet name="header">
                <h:outputText value="State Capital"/>
            </f:facet>
            <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...]]></programlisting>
            <para>This is result:</para>
            <figure>
                <title>
                    <emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> with <emphasis><property>&quot;sortBy&quot;</property></emphasis> attribute
                </title>
                <mediaobject> 
                    <imageobject>
                        <imagedata fileref="images/columnsort1.png"/>
                    </imageobject>
                </mediaobject>
            </figure>
            
            <para>
                In order to change sort order you could use <emphasis><property>&quot;sortOrder&quot;</property></emphasis> attribute. 
            </para>
            <para>Possible values are:</para>
            <itemizedlist>
                <listitem>
                    &quot;ASCENDING&quot; - column is sorted in ascending
                </listitem>
                <listitem>
                    &quot;DESCENDING&quot; - column is sorted in descending
                </listitem>
                <listitem>
                    &quot;UNSORTED&quot; - column isn&apos;t sorted
                </listitem>
            </itemizedlist>
            <para>
                If you don&apos;t use <emphasis><property>&quot;sortOrder&quot;</property></emphasis>  attribute then the first column is sorted in ascending.
            </para>
            <para>
                In order to change the sort order, you could double-click on the header of column, which you want to sort.
            </para>          
            <para>
                <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="XML"><![CDATA[...
<h:form>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px">
        <f:facet name="header">
            <h:outputText value="Sorting Example"/>
        </f:facet>
        <rich:column sortBy="#{cap.state}" sortOrder="ASCENDING">
            <f:facet name="header">
                <h:outputText value="State Name"/>
            </f:facet>
            <h:outputText value="#{cap.state}"/>
        </rich:column> 
        <rich:column sortBy="#{cap.name}" sortOrder="DESCENDING">
            <f:facet name="header">
                <h:outputText value="State Capital"/>
            </f:facet>
            <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...]]></programlisting>
            <para>Below you can see the result:</para>
            <figure>
                <title><emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> with <emphasis><property>&quot;sortOrder&quot;</property></emphasis> attribute</title>
                <mediaobject> 
                    <imageobject>
                        <imagedata fileref="images/columnsort2.png"/>
                    </imageobject>
                </mediaobject>
            </figure>  
            
            <para>
                In the example above the first column is sorted in descending order. But if recurring rows appear in the table the relative second column are sorted in ascending order.   
            </para>
            <para>
                The <emphasis><property>&quot;sortPriority&quot;</property></emphasis> attribute
                defines a set of column <property>ids</property> in the order the columns could be set. 
             </para>
            <para>
                If the columns sort order changed externally sort priorities could be used to define which columns will be sorted first.
            </para>
            <!--para>
                Note that  <emphasis><property>&quot;sortPriority&quot;</property></emphasis> attribute is defined in 
                the <emphasis role="bold"><property>&lt;rich:dataTable&gt;</property></emphasis> component!
            </para-->
            <para>
                <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="XML"><![CDATA[...
<h:form>
    <rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px" sortPriority="#{bean.sortPriority}">
        <f:facet name="header">
            <h:outputText value="Sorting Example"/>
        </f:facet>
        <rich:column sortBy="#{cap.state}">
            <f:facet name="header">
                <h:outputText value="State Name"/>
            </f:facet>
            <h:outputText value="#{cap.state}"/>
        </rich:column> 
        <rich:column sortBy="#{cap.name}">
            <f:facet name="header">
                <h:outputText value="State Capital"></h:outputText>
            </f:facet>
            <h:outputText value="#{cap.name}"/> 
        </rich:column>
    </rich:dataTable>
</h:form>
...]]></programlisting>
            <para>
                You could manage if the header of the column is clickable, icons rendered and sorting is fired after click on the header
                with the help of the following attributes:
            </para>
                <itemizedlist>
                    <listitem>
                        <para>
                            The <emphasis><property>&quot;selfSorted&quot;</property></emphasis> attribute 
                            which is defined in <emphasis role="bold"><property>&lt;rich:dataTable&gt;</property></emphasis> component.
                            Default value is &quot;true&quot;. In the example below the second column is unavailable for sorting.
                        </para>
                        <para>
                            <emphasis role="bold">Example:</emphasis>
                        </para>
                        <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
        <rich:column>
                <f:facet name="header">
                        <h:outputText value="State Flag"/>
                </f:facet>
                <h:graphicImage value="#{cap.stateFlag}"/> 
        </rich:column>
        <rich:column sortBy="#{cap.state}" selfSorted="false"> 
                <f:facet name="header">
                        <h:outputText value="State Name"/>
                </f:facet>
                <h:outputText value="#{cap.state}"/>
        </rich:column> 
</rich:dataTable>
...]]></programlisting>     
                    </listitem>
                    <listitem>
                        <para>
                            The <emphasis><property>&quot;sortable&quot;</property></emphasis> attribute which is used 
                            with <emphasis role="bold"><property>&lt;rich:scrollableDataTable&gt;</property></emphasis> component.
                            In the following example only the first column could be sorted.
                        </para>
                        <para>
                            <emphasis role="bold">Example:</emphasis>
                        </para>
                        <programlisting role="XML"><![CDATA[...
<rich:scrollableDataTable rowKeyVar="rkv" frozenColCount="1"
	    id="carList" columnClasses="col" value="#{dataTableScrollerBean.allCars}" var="category" 
	    sortMode="single" binding="#{dataTableScrollerBean.table}"
	    selection="#{dataTableScrollerBean.selection}">
        <rich:column id="make" sortable="true">
                <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>
...]]></programlisting>
                        <figure>
                            <title>The <emphasis><property>&quot;sortable&quot;</property></emphasis> attribute usage</title>
                            <mediaobject> 
                                <imageobject>
                                    <imagedata fileref="images/columnsort3.png"/>
                                </imageobject>
                            </mediaobject>
                        </figure>
                    </listitem>
                    </itemizedlist>

    <note>
        <title>Note:</title>
        <para>
           The <emphasis><property>&quot;sortExpression&quot;</property></emphasis> attribute that defines
            sorting property is deprecated! You could use the <emphasis><property>&quot;sortBy&quot;</property></emphasis> attribute
            for the same purpose.
        </para>
    </note>

            <para>
                Sorting could not be used together with pagination.
                Only row that currently on the client could be sorted.
            </para>
        </section>
        
        <section>
            <title>Filtering</title>
            
            <para>
                There are two ways to filter the column value: 
            </para>
            <itemizedlist>
                <listitem>
                    <para>
                        Using built-in filtering. It uses <property>startsWith()</property> function to make filtering. 
                        In this case you need to define <emphasis><property>&quot;filterBy&quot;</property></emphasis> attribute 
                        at column you want to be filterable. This attribute defines iterable object property which is used when filtering performed.
                    </para>
                    <para>
                        The <emphasis><property>&quot;filterValue&quot;</property></emphasis> attribute is used to get or change current filtering value. 
                        It could be defined with initial filtering value on the page or as value binding to get/change it on server.
                        If the <emphasis><property>&quot;filterValue&quot;</property></emphasis> attribute isn&apos;t empty from the beginning table is filtered on the first rendering.
                    </para>
                    <para>
                        In order to change filter event you could use <emphasis><property>&quot;filterEvent&quot;</property></emphasis> attribute 
                        on column (e.g. filterEvent = &quot;onblur&quot;).
                    </para>
                    <!--para>
                        The <emphasis><property>&quot;filterDefaultLabel&quot;</property></emphasis> attribute defines the label that appears instead of input field. 
                    </para-->
                    <para>Below you can see the example:</para>
                    <para>
                        <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="500px">
        <rich:column> 
                <f:facet name="header">
                        <h:graphicImage value="/images/ico_DataTable.gif"/>
                </f:facet>
                <h:graphicImage value="#{cap.stateFlag}"/>
        </rich:column>
        <rich:column filterBy="#{cap.state}" filterValue="#{filterName.filterBean}" filterEvent="onkeyup">
                <h:outputText value="#{cap.state}"/>
        </rich:column> 
        <rich:column filterBy="#{cap.name}" filterEvent="onkeyup">
                <h:outputText value="#{cap.name}"/> 
        </rich:column>
</rich:dataTable>
...]]></programlisting>     
                    <para>
                        This is the result:
                    </para>
                    <figure>
                        <title>Built-in filtering feature usage</title>
                        <mediaobject> 
                            <imageobject>
                                <imagedata fileref="images/columnFilt1.png"/>
                            </imageobject>
                        </mediaobject>
                    </figure>  
                </listitem>
                <listitem>
                    <para>
                        Using external filtering. In this case you need to write your custom filtering function and define controls.
                    </para>
                    <para>
                        The <emphasis><property>&quot;filterExpression&quot;</property></emphasis> attribute is used to define expression evaluated to boolean value. 
                        This expression checks if the object satisfies filtering condition.
                    </para>
                    <para>
                        The <emphasis><property>&quot;filterMethod&quot;</property></emphasis> attribute is defined with method binding.
                        This method accepts on Object parameter and return boolean value. 
                        So, this method also could be used to check if the object satisfies filtering condition. 
                        The usage of this attribute is the best way for implementing your own complex business logic. 
                    </para>
                    <para>See the following example:</para>
                    <para>
                        <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table">
        <rich:column filterMethod="#{filteringBean.filterStates}">
                <f:facet name="header">
                        <h:inputText value="#{filteringBean.filterValue}" id="input">
                                <a4j:support event="onkeyup" reRender="table"
                                                     ignoreDupResponses="true" requestDelay="700" focus="input" />
                        </h:inputText>
                </f:facet>
                <h:outputText value="#{cap.state}" />
        </rich:column>
        <rich:column filterExpression="#{fn:containsIgnoreCase(cap.timeZone, filteringBean.filterZone)}">
                <f:facet name="header">
                        <h:selectOneMenu value="#{filteringBean.filterZone}">
                                <f:selectItems value="#{filteringBean.filterZones}" />
                                <a4j:support event="onchange" reRender="table" />
                        </h:selectOneMenu>
                </f:facet>
                <h:outputText value="#{cap.timeZone}" />
        </rich:column>
</rich:dataTable>
...]]></programlisting>
                </listitem>
            </itemizedlist>
        </section>
    </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:column&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:column&gt;</property>
             </emphasis> component</para>
         </listitem>
     </itemizedlist>
 </section>
    
    <section>
        <title>Skin Parameters Redefinition</title>
        
        <para>Skin parameters redefinition for <emphasis role="bold">
            <property>&lt;rich:column&gt;</property>
        </emphasis> are the same as for the <emphasis role="bold">
            <property>&lt;rich:dataTable&gt;</property>
        </emphasis> <link linkend="SPR">component</link>.</para>
    </section>
    
		 <section>
		 <title>Definition of Custom Style Classes</title>
		     
		     <para>Custom style classes for <emphasis role="bold">
		         <property>&lt;rich:column&gt;</property>
		     </emphasis> are the same as for  the <emphasis role="bold">
		         <property>&lt;rich:dataTable&gt;</property>
		     </emphasis> <link linkend="DofCCS">component</link>.
		     </para>
		 		 
		     <para>In order to redefine styles for all <emphasis role="bold">
		         <property>&lt;rich:column&gt;</property>
		     </emphasis> components on a page using CSS, it&apos;s enough to create classes with the
		         same names and define necessary properties in them.</para>
		     
		     <para>To change styles of particular <emphasis role="bold">
		         <property>&lt;rich:column&gt;</property>
		     </emphasis> components, define your own style classes in the corresponding <emphasis
		         role="bold">
		         <property>&lt;rich:column&gt;</property>
		     </emphasis>attributes.</para>
                                </section>
    
    <section>
        <title>Relevant Resources Links</title>
        <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataTable.jsf?c=column"
            >Here</ulink> you can see the example of <emphasis role="bold"
                ><property>&lt;rich:column&gt;</property></emphasis> usage and sources for the given example. </para>
    </section>          
</section>
  