<?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
                              <code>breakBefore=&quot;true&quot;</code>.</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 <emphasis>
                                                  <property>&quot;colspan&quot;</property>
                                        </emphasis> and <emphasis>
                                                  <property>&quot;breakbefore&quot;</property>
                                        </emphasis> 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 <emphasis>
                                                  <property>&quot;rowspan&quot;</property>
                                        </emphasis> 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>
                    <para><ulink url="http://wiki.jboss.org/wiki/DynamicColumns">Here</ulink> you
                              can find additional information about dynamic columns.</para>
          </section>

          <section>
                    <title>Sorting and Filtering</title>
                    <section id="sort">
                              <title>Sorting</title>
                              <para> In order to sort the columns you should use <emphasis>
                                                  <property>&quot;sortBy&quot;</property>
                                        </emphasis> attribute that indicates what values to be
                                        sorted. In order to sort the column you should click on its
                                        header. 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/column5.png"
                                                  />
                                                  </imageobject>
                                        </mediaobject>
                              </figure>
                              <para> The <emphasis>
                                                  <property>&quot;selfSorted&quot;</property>
                                        </emphasis> attribute that would add the possibility of
                                        automatic sorting by clicking the column header. 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>
                              <para>
                                        <emphasis>
                                                  <property>&quot;sortOrder&quot;</property>
                                        </emphasis> attribute is used for changing the sorting of
                                        columns by means of external controls. </para>
                              <para>Possible values are:</para>
                              <itemizedlist>
                                        <listitem>
                                                  <para> &quot;ASCENDING&quot; - column is
                                                  sorted in ascending </para>
                                        </listitem>
                                        <listitem>
                                                  <para> &quot;DESCENDING&quot; - column is
                                                  sorted in descending </para>
                                        </listitem>
                                        <listitem>
                                                  <para> &quot;UNSORTED&quot; - column
                                                  isn&apos;t sorted </para>
                                        </listitem>
                              </itemizedlist>
                              <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/column6.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>You can customize the sorting&apos;s icon element using
                                        &quot;rich-sort-icon&quot; class.</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> 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/column7.png"
                                                  />
                                                  </imageobject>
                                        </mediaobject>
                              </figure>
                              <para><emphasis>
                                                  <property>&quot;sortExpression&quot;</property>
                                        </emphasis> attribute defines a bean property which is used
                                        for sorting of a column. This attribute can be used only with the <emphasis role="bold"><property>&lt;rich:scrollableDataTable&gt;</property></emphasis> component.</para>
                    </section>

                    <section id="filter">
                              <title>Filtering</title>

                              <para> There are two ways to filter the column value: </para>
                              <itemizedlist>
                                        <listitem>
                                                  <para> Using built-in filtering. It uses
                                                  <code>startsWith()</code>
                                                  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> You can customize the input form using
                                                  &quot;rich-filter-input&quot;
                                                  CSS class. </para>
                                                  <para> In order to change filter event you could
                                                  use <emphasis>
                                                  <property>&quot;filterEvent&quot;</property>
                                                  </emphasis> attribute on column, e.g.
                                                  &quot;onblur&quot;(default
                                                  value). </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 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/column8.png"
                                                  />
                                                  </imageobject>
                                                  </mediaobject>
                                                  </figure>
                                        </listitem>
                                        <listitem>
                                                  <para> Using external filtering. In this case you
                                                  need to write your custom filtering
                                                  function or expression 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 (possible classes could be found in
                              the tables <link linkend="SPR"> above</link>) and define necessary
                              properties in them. </para>

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

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

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

                    <para>In the example cells font style was changed.</para>

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

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="CSS"><![CDATA[...
.myClass{
        font-weight: bolder;
}
...]]></programlisting>
                    <para>The <emphasis>
                                        <property>&quot;styleClass&quot;</property>
                              </emphasis> attribute for <emphasis role="bold">
                                        <property>&lt;rich:column&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:column styleClass="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/column_oc.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>

                    <para>As it could be seen on the picture above, the font weight for second
                              column was changed.</para>
          </section>

          <section>
                    <title>Relevant Resources Links</title>
                    <para>Vizit 
					<ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataTable.jsf?c=column">Column</ulink> page at 
					RichFaces live demo for examples of component usage and their sources.</para>
					<para>&quot;
					<ulink url="http://www.jboss.org/community/docs/DOC-9607">Using the "rendered" attribute of &lt;rich:column&gt;</ulink>&quot; article 
					in RichFaces cookbook at JBoss portal gives an example of code of the component usage case. 
					</para>
          </section>
</section>
