<section role="NotInToc" id="rich_columns">
   <title>
				&lt;
				rich:columns
				&gt;
				<emphasis role="since">
         <superscript> available since <emphasis role="version">3.2.0</emphasis>
         </superscript>
      </emphasis>
   </title>
   <section>
        <title>Description</title>
        <para>The <emphasis role="bold">
            <property>&lt;rich:columns&gt;</property>
        </emphasis> is a component, that allows you to create a <property>dynamic</property> set of columns from your model.</para>
       
        <figure>
            <title>
            <emphasis role="bold">
               <property>&lt;rich:columns&gt;</property>
            </emphasis> component</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/columns_init.png"/>
                </imageobject>
            </mediaobject>
        </figure>
        
    </section>
   <section>
        <title>Key Features</title>    
        <itemizedlist>
            <listitem>
            <para>Highly customizable look and feel</para>
         </listitem>
            <listitem>
            <para>Dynamic tables creation</para>
         </listitem>
            <listitem>
            <para>Possibility to combine columns with the help of <emphasis>
                  <property>"colspan"</property>
               </emphasis> and <emphasis>
                  <property>"breakBefore"</property>
               </emphasis>
            </para>
         </listitem>
            <listitem>
            <para>Possibility to combine rows with the help of <emphasis>
                  <property>"rowspan"</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>
    </section>
   <section>
                    <title>Details of Usage</title>
                    <para> The <emphasis role="bold">
                                        <property>&lt;rich:columns&gt;</property>
                              </emphasis> component gets a list from data model and outputs
                              a corresponding set of columns inside <emphasis role="bold">
                                        <property>&lt;rich:dataTable&gt;</property>
                              </emphasis> on a page. It is possible to use <emphasis>
                                        <property>"header"</property>
                              </emphasis> and <emphasis>
                                        <property>"footer"</property>
                              </emphasis> facets with <emphasis role="bold">
                                        <property>&lt;rich:columns&gt;</property>
                              </emphasis> component. </para>
                    <para> The <emphasis>
                                        <property>"value"</property>
                              </emphasis> and <emphasis>
                                        <property>"var"</property>
                              </emphasis> attributes are used to access the values of collection. </para>
                    <para>The simple example is placed below.</para>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{dataTableScrollerBean.model}" var="model" width="750">
			<rich:columns value="#{dataTableScrollerBean.columns}" var="columns"
				index="ind" id="column#{ind}"> 
				<f:facet name="header">
					<h:outputText value="#{columns.header}" />
				</f:facet>
			
				<h:outputText value="#{model[ind].model} " />
				<h:outputText value="#{model[ind].mileage} miles " />
				<h:outputText value="#{model[ind].price}$" />		
			</rich:columns>	
</rich:dataTable>                    	
...]]></programlisting>
                    <para> The <emphasis>
                                        <property>"columns"</property>
                              </emphasis> attribute defines the count of columns.</para>
                    <para> The <emphasis>
                                 <property>"rowspan"</property>
                              </emphasis> attribute defines the number of rows to be displayed. If
                              the value of this attribute is zero, all remaining rows in the table
                              are displayed on a page. </para>
                    <para> The <emphasis>
                                        <property>"begin"</property>
                              </emphasis> attribute contains the first iteration item. Note, that
                              iteration begins from zero. </para>
                    <para> The <emphasis>
                                        <property>"end"</property>
                              </emphasis> attribute contains the last iteration item. </para>
                    <para> With the help of the attributes described above you can customize the
                              output, i.e. define which columns and how many rows appear on a page. </para>
               
                    <para> The <emphasis role="bold">
                                        <property>&lt;rich:columns&gt;</property>
                              </emphasis> component does not prevent to use <emphasis role="bold">
                                        <property>&lt;rich:column&gt;</property>
                              </emphasis>. In the following example one column renders in any way
                              and another columns are picked from the model.</para>
                   
   	<para>
   		<emphasis role="bold">Example:</emphasis>
   	</para>
                    <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{dataTableScrollerBean.model}" var="model" width="500px" rows="5">
		<f:facet name="header">
	    		<h:outputText value="Cars Available"></h:outputText>
		</f:facet>
		<rich:columns value="#{dataTableScrollerBean.columns}" var="columns" index="ind">
	    		<f:facet name="header">
		       			<h:outputText value="#{columns.header}" />
				</f:facet>
				<h:outputText value="#{model[ind].model} " />
		</rich:columns>
		<rich:column>
				<f:facet name="header">
		       			<h:outputText value="Price" />
				</f:facet>
               <h:outputText value="Price" />
		</rich:column>
		<rich:columns value="#{dataTableScrollerBean.columns}" var="columns" index="ind">
	    		<f:facet name="header">
		       			<h:outputText value="#{columns.header}" />
				</f:facet>
				<h:outputText value="#{model[ind].mileage}$" />
		</rich:columns>
</rich:dataTable>
...                              
                    ]]></programlisting>
   	
   	<para>The grouping some columns into one column or one row with the help of 
   						the <emphasis>
   							<property>&quot;colspan&quot;</property>,
   						</emphasis> <emphasis>
   							<property>&quot;rowspan&quot;</property>
   						</emphasis> and <emphasis>
   							<property>&quot;breakBefore&quot;</property></emphasis> attributes can be perform for <emphasis role="bold">
   								<property>&lt;rich:columns&gt;</property></emphasis> the same way as for the
   						<link linkend="col_grouping"><emphasis role="bold">
   								<property>&lt;rich:columnt&gt;</property></emphasis> component</link>.</para>
                    <note>
                              <title>Note:</title>
                              <para> The <emphasis role="bold">
                                                  <property>&lt;rich:columns&gt;</property>
                                        </emphasis> tag is initialized during components tree
                                        building process. This process precedes page rendering at
                                        "Render Response" JSF phase. To be
                                        rendered properly the component needs all it variables to be
                                        initialized while the components tree is being building. A
                                                  <emphasis>javax.servlet.jsp.JspTagException</emphasis>
                                        occurs if <emphasis role="bold">
                                                  <property>&lt;rich:columns&gt;</property>
                                        </emphasis> uses variables passed from other components, if
                                        these variables are initialized during rendering. Thus, when
                                                  <emphasis role="bold">
                                                  <property>&lt;rich:columns&gt;</property>
                                        </emphasis> is asking for such variables they do not already
                                        exist. Use <property>&lt;c:forEach&gt;</property>
                                        JSP standard tag as workaround. Compare two examples below. </para>
                              <para> This code calls the exception: </para>
                              <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{bean.data}" var="var">
		<rich:columns value="#{var.columns}">
       			...
       	</rich:columns>
</rich:dataTable>
...]]></programlisting>
                              <para> This code works properly: </para>
                              <programlisting role="XML"><![CDATA[...
<c:forEach items="#{bean.data}" var="var">
		<rich:columns value="#{var.columns}">
        		...
       	</rich:columns>
</c:forEach>
...]]></programlisting>
                    </note>


      <note>
         <title>Note:</title>
          <para>Since 3.3.0GA <emphasis role="bold">
               <property>&lt;rich:columns&gt;</property>
            </emphasis> requires explicit definition of <emphasis>
               <property>"id"</property>
            </emphasis> for children components to ensure that  decode process works properly.
                    The  example of how you can define unique <emphasis>
               <property>"id"</property>
            </emphasis> for children component: </para>
           <programlisting role="XML"><![CDATA[...
<rich:columns value="#{bean.columns}" var="col" index="ind" ... >
		<h:inputText id="input#{ind}" value="">
				<a4j:support id="support#{ind}" event="onchange" reRender="someId" />
		</h:inputText>
</rich:columns> 
...]]></programlisting> 
          <para>Only if <emphasis>
               <property>"id"</property>
            </emphasis> defined as shown above Ajax after onchange event will be processed as expected. </para>      

      </note>



          	<para>Sorting and filtering for the <emphasis role="bold">
            <property>&lt;rich:columns&gt;</property>
         </emphasis> component works the same 
          		as for <emphasis role="bold">
            <property>&lt;rich:column&gt;</property>
         </emphasis>. See the <link linkend="sortAndFilter">"Sorting and Filtering"</link> section.</para>

          </section>
   <section>
      <title>Reference Data</title>
      <para>
         <ulink url="&tlddoc;rich/columns.html">Table of 
							&lt;rich:columns&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></entry>
					</row>
					<row>
					<entry>component-family</entry>
					<entry></entry>
					</row>
					<row>
					<entry>renderer-type</entry>
					<entry></entry>
					</row-->
                                        <row>
                                                  <entry>tag-class</entry>
                                                  <entry> org.richfaces.taglib.ColumnsTagHandler
                                                  </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:columns&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>On the  
                    	<ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataTable.jsf?c=columns">component LiveDemo page </ulink> 
                    	you can find an additional information on the <emphasis role="bold">
                                        <property>&lt;rich:columns&gt;</property>
                              </emphasis> component usage.</para>
          </section>
</section>
