<section role="NotInToc" id="rich_column">
   <title>
				&lt;
				rich:column
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.0.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
      <title>Description</title>
      <para>The component is meant for row rendering in UIData components.</para>
      <figure>
        <title>
            <emphasis role="bold">
               <property>&lt;rich:column&gt;</property>
            </emphasis> component</title>
         <mediaobject> 
            <imageobject>
               <imagedata fileref="images/column_init.png"/>
            </imageobject>
         </mediaobject>
      </figure>
    </section>
   <section>
      <title>Key Features</title> 
      <itemizedlist>
         <listitem>
            <para>Completely skinned table rows and child elements</para>
         </listitem>
         <listitem>
            <para>Possibility to combine columns with the help of <emphasis>
                  <property>&quot;colspan&quot;</property>
               </emphasis>
            </para>
         </listitem>
         <listitem>
            <para>Possibility to combine rows with the help of <emphasis>
                  <property>"rowspan"</property>
               </emphasis> and <emphasis>
                  <property>"breakBefore"</property>
               </emphasis>
            </para>
         </listitem>
         <listitem>
            <para>
               <link linkend="sort">Sorting column values</link>
            </para>
         </listitem>
         <listitem>
            <para>
               <link linkend="filter">Filtering column values</link>
            </para>
         </listitem>
      </itemizedlist>
      <important>
        <title>Important</title>
        <para>
          The <property>&quot;colspan&quot;</property>, <property>&quot;rowspan&quot;</property>, and <property>&quot;breakbefore&quot;</property> attributes only affect columns in a <emphasis role="bold"><property>&lt;rich:dataTable&gt;</property></emphasis>, not those in a <emphasis role="bold"><property>&lt;rich:extendedDataTable&gt;</property></emphasis>.
        </para>
      </important>
   </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>. See the example of the component usage below:</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 id="col_grouping">Now, in order to group columns with text information into one row in one
                              column with a flag, use the <emphasis>
                                        <property>"colspan"</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 
                              <code>breakBefore="true"</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 row 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">In the Dynamic Columns Wiki article</ulink> you
                              can find additional information about dynamic columns.</para>
          </section>
   <section id="sortAndFilter">
                    <title>Sorting and Filtering</title>
                    <section id="sort">
                              <title>Sorting</title>
                              <para> In order to sort the columns you should use the <emphasis><property>&quot;sortBy&quot;</property></emphasis> attribute that indicates what values to be sorted. This attribute can be used only with the <emphasis role="bold"><property>&lt;rich:dataTable&gt;</property></emphasis> component. Expressions in the <emphasis><property>&quot;sortBy&quot;</property></emphasis> attribute can refer only to the variable declared with the <emphasis><property>&quot;var&quot;</property></emphasis> attribute, not to those declared with other attributes such as the <emphasis><property>&quot;rowKeyVar&quot;</property></emphasis> attribute. 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;sortExpression&quot;</property>
                              </emphasis> attribute defines a bean property which is used
                                        for sorting a column. This attribute can be used only with the <emphasis role="bold">
               <property>&lt;rich:scrollableDataTable&gt;</property>
            </emphasis> component.
                                        See the example of the attribute usage below.
                              </para>
                              <para>
                                        <emphasis role="bold">Example:</emphasis>
                              </para>
                              <programlisting role="XML"><![CDATA[...
<rich:scrollableDataTable
		value="#{dataTableScrollerBean.allCars}" sortMode="single"
		var="category">
		<rich:column sortExpression="#{category.make}">
			<f:facet name="header">
				<h:outputText styleClass="headerText" value="Make" />
			</f:facet>
			<h:outputText value="#{category.make}" />
		</rich:column>
		<rich:column>
			<f:facet name="header">
				<h:outputText styleClass="headerText" value="Model" />
			</f:facet>
			<h:outputText value="#{category.model}" />
		</rich:column>
		<rich:column>
			<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;sortExpression&quot;</property>
                                        </emphasis> attribute usage</title>
                                        <mediaobject>
                                                  <imageobject>
                                                            <imagedata fileref="images/column7.png"
                                                            />
                                                  </imageobject>
                                        </mediaobject>
                              </figure>-->
                              <para>The <emphasis>
                                                  <property>&quot;selfSorted&quot;</property>
                                        </emphasis> attribute is meant for adding the possibility of
                                        automatic sorting by clicking on 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>The 
                                        <emphasis>
                                                  <property>&quot;sortOrder&quot;</property>
                                        </emphasis> attribute is used for changing the sort order of
                                        columns by means of external controls. </para>
                              <para>Possible values are:</para>
                              <itemizedlist>
                                        <listitem>
                                                  <para>&quot;ASCENDING&quot; - column is
                                                  sorted in ascending order</para>
                                        </listitem>
                                        <listitem>
                                                  <para>&quot;DESCENDING&quot; - column is
                                                  sorted in descending order</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>"sortOrder"</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>If the values of the columns are complex, the <emphasis>
                    		<property>"sortOrder"</property>
                    	</emphasis> attribute should point to a bean property containing the sort order. 
                    				See how it's done in the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/columns.jsf?c=columns&amp;tab=usage">LiveDemo</ulink>
                    				for <emphasis role="bold">
               <property>&lt;rich:columns&gt;</property>
            </emphasis>.</para>                                                                                                                                                                                                                                                                                          
         <para>You can customize the sorting's icon element using
                              "rich-sort-icon" class.</para>
                              <note>
                                        <title>Note</title>
                                        <para>
                                                  In order to sort a column with the values not in English you can add the <code>org.richfaces.datatableUsesViewLocale</code> context parameter in your web.xml. 
                                                  Its value should be "true". 
                                        </para>
                              </note>
                             <!--  <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-->
                             <note>
                                 <title>Note:</title>
                                           <para>
                                                     The <emphasis>
                  <property>"sortBy"</property>
               </emphasis> and the <emphasis>
                  <property>"selfSorted"</property>
               </emphasis> attributes used with the <emphasis role="bold">
                  <property>&lt;rich:dataTable&gt;</property>
               </emphasis> component. 
                                                     Also the <emphasis>
                  <property>"selfSorted"</property>
               </emphasis> can be used with the <emphasis role="bold">
                  <property>&lt;rich:extendedDataTable&gt;</property>
               </emphasis>.
                                           </para>
                                       <para> The <emphasis>
                                                 <property>"sortable"</property>
                                       </emphasis> and the <emphasis>
                  <property>"sortExpression"</property>
               </emphasis> attributes used with the <emphasis role="bold">
                                                 <property>&lt;rich:scrollableDataTable&gt;</property>
                                       </emphasis> component.</para>
                             </note>
                    </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 the <emphasis>
                                                  <property>"filterBy"</property>
                                                  </emphasis> attribute at a column you want
                                                  to be filterable. This attribute defines
                                                  iterable object property which is used
                                                  when filtering performed. Expressions in the <emphasis><property>&quot;filterBy&quot;</property></emphasis> attribute can refer only to the variable declared with the <emphasis><property>&quot;var&quot;</property></emphasis> attribute, not to those declared with other attributes such as the <emphasis><property>&quot;rowKeyVar&quot;</property></emphasis> attribute.</para>
                                                  <para> The <emphasis>
                                                  <property>"filterValue"</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>"filterValue"</property>
                                                  </emphasis> attribute isn't
                                                  empty from the beginning table is
                                                  filtered on the first rendering. </para>
                                                  <para> You can customize the input form using
                                                  "rich-filter-input"
                                                  CSS class. </para>
                                                  <para> In order to change filter event you could
                                                  use <emphasis>
                                                  <property>"filterEvent"</property>
                                                  </emphasis> attribute on column, e.g.
                                                  "onblur"(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="200px">
		<f:facet name="header">
            <h:outputText value="Sorting Example"/>
        </f:facet>
        <rich:column filterBy="#{cap.state}" filterEvent="onkeyup">
				<f:facet name="header">
                	<h:outputText value="State Name"/>
            	</f:facet>
               <h:outputText value="#{cap.state}"/>
        </rich:column> 
        <rich:column filterBy="#{cap.name}" filterEvent="onkeyup">
			<f:facet name="header">
                <h:outputText value="State Capital"/>
            </f:facet>
            <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>"filterExpression"</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>"filterMethod"</property>
                                                  </emphasis> attribute is defined with
                                                  method binding. This method accepts on
                                                  Object parameter and returns boolean
                                                  value. Thus, this method also could be
                                                  used to check if the object satisfies
                                                  filtering condition or not. The usage of this
                                                  attribute is the best way for
                                                  implementing your own complex business
                                                  logic. </para>
                                        	<para>See a simple example of <emphasis>
                                        		<property>"filterExpression"</property>
                                        	</emphasis> and <emphasis>
                                        		<property>"filterMethod"</property>
                                        	</emphasis> attributes usage on the 
                                        		RichFaces <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/filteringFeature.jsf?tab=ex-usage&amp;cid=4110192">LiveDemo page</ulink>.</para>
   
                                        </listitem>
                              </itemizedlist>
                    </section>
          </section>
   <section>
      <title>Reference Data</title>
      <para>
         <ulink url="&tlddoc;rich/column.html">Table of 
							&lt;rich:column&gt; 
							 attributes</ulink>.
						</para>
      <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.renderkit.CellRenderer</entry>
                                        </row>
                                        <row>
                                                  <entry>tag-class</entry>
                                                  <entry>org.richfaces.taglib.ColumnTag</entry>
                                        </row>
                              </tbody>
                    </tgroup>
          </table>
      <table>
                              <title>Facets</title>
                              <tgroup cols="2">
                                        <thead>
                                                  <row>
                                                            <entry>Facet name</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>
   	<para>Custom style classes as well as skin parameters for  <emphasis role="bold">
   		<property>&lt;rich:column&gt;</property></emphasis> are the same as for the  <link linkend="dataTableRefData"><emphasis role="bold">
   			<property>&lt;rich:dataTable&gt;</property></emphasis> component.</link></para>
							<para>You can find all necessary information about style classes redefinition in 
						<link linkend="customstyles">Definition of Custom Style Classes</link> 
							section.</para>
						</section>
   <section>
                    <title>Relevant Resources Links</title>
                    <para>Visit 
					the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataTable.jsf?c=column">Column</ulink> page at 
					RichFaces LiveDemo for examples of the component usage and their sources.</para>
					<para>
						See the example on how to use the <emphasis>
							<property>&quot;rendered&quot;</property></emphasis> attribute of <emphasis role="bold">
							<property>&lt;rich:column&gt;</property></emphasis> in the 
						<ulink url="http://www.jboss.org/community/docs/DOC-9607">RichFaces Cookbook article</ulink>. 
					</para>
          </section>
</section>
