Component reference docbook xml

gistfile1.txt

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">



<book lang="en">
  <bookinfo>
    
    <title>Component Reference</title>
    
    
    <date>2013-04-10</date>
    
    
    
    
    

  </bookinfo>
<chapter id="chap-Component_Reference-Introduction">
  <title>Introduction</title>
  <simpara>This book is a guide to the various components available in the RichFaces 5.0.0-SNAPSHOT framework. It includes descriptions of the role of the components, details on how best to use them, coded examples of their use, and basic references of their properties and attributes.</simpara>
<simpara>For full references for all component classes and properties, refer to the following supplementary documentation:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>VDL (View Definition Language) Documentation</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Available at link:http://docs.jboss.org/richfaces/latest_4_0_X/vdldoc/</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>API (Application Programming Interface) Documentation</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>RichFaces Components API</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Available at link:http://docs.jboss.org/richfaces/latest_4_0_X/javadoc/richfaces-components-api/</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>RichFaces Components UI</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Available at link:http://docs.jboss.org/richfaces/latest_4_0_X/javadoc/richfaces-components-ui/</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>RichFaces Core API</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Available at link:http://docs.jboss.org/richfaces/latest_4_0_X/javadoc/richfaces-core-api/</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>RichFaces Core Implementation</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Available at link:http://docs.jboss.org/richfaces/latest_4_0_X/javadoc/richfaces-core-impl/</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>For further examples for each component, refer to the RichFaces Showcaseat link:http://richfaces-showcase.appspot.com/.</simpara>
<section id="sect-Component_Reference-Introduction-Libraries">
  <title>Libraries</title>
  <simpara>The RichFaces framework is made up of two tag libraries: the <literal>a4j</literal> library and the <literal>rich</literal> library.</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>a4j</literal>  library
    </term>
    
    <listitem>
      
      <simpara>The <literal>a4j</literal> tag library provides core Ajax and utility components.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>rich</literal>  library
    </term>
    
    <listitem>
      
      <simpara>The <literal>rich</literal> tag library provides ready-made, self-contained, rich user-interface components. These components have built-in Ajax support. By default, the components don&#8217;t require additional configuration in order to send requests or update, but can also be customized by plugging in utility behaviors.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>

</chapter>
<chapter id="chap-Component_Reference-Common_Ajax_attributes">
  <title>Common Ajax attributes</title>
  <simpara>The Ajax components in the <literal>a4j</literal> library share common attributes to perform similar functionality. Most RichFaces components in the <literal>rich</literal> library that feature built-in Ajax support share these common attributes as well.</simpara>
<simpara>Most attributes have default values, so they need not be explicitly set for the component to function in its default state. These attributes can be altered to customize the behavior of the component if necessary.</simpara>
<section id="sect-Component_Reference-Common_Ajax_attributes-Data_processing">
  <title>Data processing</title>
  <simpara>The RichFaces Ajax script is built on a base of the JSF 2 Ajax script. As such, each time a request is sent, the data from the requesting component&#8217;s parent JSFform is submitted along with the XMLHTTPRequestobject. The form data contains values from the input element and auxiliary information such as state-saving data.</simpara>
<section id="sect-Component_Reference-Data_processing-execute">
  <title><literal>execute</literal></title>
  <simpara>The <literal>execute</literal> attribute allows JSFprocessing to be limited to defined components. The <literal>execute</literal> attribute can point to an <literal>id</literal> identifier of a specific component to process. Components can also be identified through the use of Expression Language ( EL).</simpara>
<simpara>Alternatively, the <literal>execute</literal> attribute accepts the following keywords:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>@all</literal>
    </term>
    
    <listitem>
      
      <simpara>Every component is processed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>@none</literal>
    </term>
    
    <listitem>
      
      <simpara>No components are processed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>@this</literal>
    </term>
    
    <listitem>
      
      <simpara>The requesting component with the <literal>execute</literal> attribute is processed. This is the default behavior for components.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>@form</literal>
    </term>
    
    <listitem>
      
      <simpara>The form that contains the requesting component is processed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>@region</literal>
    </term>
    
    <listitem>
      
      <simpara>The region that contains the requesting component is processed. Use the <literal>&lt;a4j:region&gt;</literal> component as a wrapper element to specify regions.
Some components make use of additional keywords. These are detailed under the relevant component entry in this book.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-Data_processing-bypassUpdates">
  <title><literal>bypassUpdates</literal></title>
  <simpara>If the <literal>bypassUpdates</literal> attribute is set to <literal>true</literal>, the Update Model phase of the request processing lifecycle is bypassed. This is useful if user input needs to be validated but the model does not need to be updated. This is the opposite functionality to the <literal>execute</literal> attribute in RichFaces.</simpara>

</section>

</section>
<section id="sect-Component_Reference-Common_Ajax_attributes-Rendering">
  <title>Rendering</title>
  <section id="sect-Component_Reference-Rendering-render">
  <title><literal>render</literal></title>
  <simpara>The <literal>render</literal> attribute provides a reference to one or more components on the page that need updating after an Ajax interaction. It uses the UIComponent.findComponent()algorithm to find the components in the component tree using their <literal>id</literal> identifiers as a reference. Components can be referenced by their <literal>id</literal> identifier alone, or by their <literal>clientId</literal> identifier to make locating components more efficient. <xref linkend="exam-Component_Reference-render-render_example"/> shows both ways of referencing components. Each command button will correctly render the referenced panel grids, but the second button locates the references more efficiently with explicit <literal>clientId</literal> paths.</simpara>
<example id="exam-Component_Reference-render-render_example">
  <title>render example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form id="form1"&gt;
    &lt;a4j:commandButton value="Basic reference" render="infoBlock, infoBlock2" /&gt;
    &lt;a4j:commandButton value="Specific reference" render=":infoBlock,:sv:infoBlock2" /&gt;
&lt;/h:form&gt;

&lt;h:panelGrid id="infoBlock"&gt;
    ...
&lt;/h:panelGrid&gt;

&lt;h:form id="sv"&gt;
    &lt;h:panelGrid id="infoBlock2"&gt;
        ...
    &lt;/h:panelGrid&gt;
&lt;/h:form&gt;
</programlisting>



</example>
<simpara>The value of the <literal>render</literal> attribute can also be an expression written using JavaServer Faces' Expression Language ( EL); this can either be a <literal>Set</literal>, <literal>Collection</literal>, <literal>Array</literal>, or <literal>String</literal>.</simpara>
<note>
  <title>Differences between JSFAjax and RichFaces Ajax</title>
  
<simpara>JSFevaluates all parameters during page rendering. As such, during a request from a page, all <literal>execute</literal> and <literal>render</literal> values are passed to the server from the client. In contrast, RichFaces evaluates these options at the server side during the current request.</simpara>
<simpara>This means that with JSF, making changes during a request to a <literal>render</literal> value defined with EL will not influence the request. RichFaces, however, will always use the newer values.</simpara>
<simpara>The RichFaces approach additionally increases data integrity. Parameters that are changed from the client side are re-evaluated on the server, where they cannot be changed.</simpara>

  
</note>
<important>
  <title>Conditionally-rendered component updates</title>
  
<simpara>A common problem with using <literal>render</literal> occurs when the referenced component is conditionally rendered via the <literal>rendered</literal> attribute. If a component is not initially rendered, it does not have any HTML representation in the Document Object Model ( DOM). As such, when RichFaces renders the component via Ajax, the page does not update as the place for the update is not known.</simpara>
<simpara>To work around this issue, wrap the component to be rendered in an <literal>&lt;a4j:outputPanel&gt;</literal> component. The <literal>&lt;a4j:outputPanel&gt;</literal> component will receive the update and render the component as required.</simpara>

  
</important>

</section>
<section id="sect-Component_Reference-Rendering-ajaxRendered">
  <title><literal>ajaxRendered</literal></title>
  <simpara>A component with <literal>ajaxRendered="true"</literal> will be re-rendered with <emphasis>every</emphasis> Ajax request, even when not referenced by the requesting component&#8217;s <literal>render</literal> attribute. This can be useful for updating a status display or error message without explicitly requesting it.</simpara>
<simpara>The <literal>ajaxRendered</literal> attribute&#8217;s functionality is the basis for the <literal>&lt;a4j:outputPanel&gt;</literal> component. The <literal>&lt;a4j:outputPanel&gt;</literal> component is designed to mark parts of the page for automatic updating. Refer to <xref linkend="sect-Component_Reference-Containers-a4joutputPanel"/> for details.</simpara>
<simpara>Automatic rendering of such components can be repressed by adding <literal>limitRender="true"</literal> to the requesting component, as described in <xref linkend="sect-Component_Reference-Rendering-limitRender"/>.</simpara>

</section>
<section id="sect-Component_Reference-Rendering-limitRender">
  <title><literal>limitRender</literal></title>
  <simpara>RichFaces Ajax-enabled components and Ajax behaviors with <literal>limitRender="true"</literal> specified will <emphasis>not</emphasis> cause components with <literal>ajaxRendered="true"</literal> to re-render, and only those components listed in the <literal>render</literal> attribute will be updated. This essentially overrides the <literal>ajaxRendered</literal> attribute in other components.</simpara>
<simpara><xref linkend="exam-Component_Reference-data-Data_reference_example"/> describes two command buttons, a panel grid rendered by the buttons, and an output panel showing error messages. When the first button is clicked, the output panel is rendered even though it is not explicitly referenced with the <literal>render</literal> attribute. The second button, however, uses <literal>limitRender="true"</literal> to override the output panel&#8217;s rendering and only render the panel grid.</simpara>
<example id="exam-Component_Reference-limitRender-Rendering_example">
  <title>Rendering example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form id="form1"&gt;
    &lt;a4j:commandButton value="Normal rendering" render="infoBlock" /&gt;
    &lt;a4j:commandButton value="Limited rendering" render="infoBlock" limitRender="true" /&gt;
&lt;/h:form&gt;

&lt;h:panelGrid id="infoBlock"&gt;
    ...
&lt;/h:panelGrid&gt;

&lt;a4j:outputPanel ajaxRendered="true"&gt;
    &lt;h:messages /&gt;
&lt;/a4j:outputPanel&gt;
</programlisting>



</example>

</section>

</section>
<section id="sect-Component_Reference-Common_Ajax_attributes-Queuing_and_traffic_control">
  <title>Queuing and traffic control</title>
  <section id="sect-Component_Reference-Queuing_and_traffic_control-requestDelay">
  <title><literal>requestDelay</literal></title>
  <simpara>The <literal>requestDelay</literal> attribute specifies an amount of time in milliseconds for the request to wait in the queue before being sent to the server. If a similar request is added to the queue before the delay is over, the original request is replaced with the new one.</simpara>

</section>
<section id="sect-Component_Reference-Queuing_and_traffic_control-ignoreDupResponses">
  <title><literal>ignoreDupResponses</literal></title>
  <simpara>When set to <literal>true</literal>, the <literal>ignoreDupResponses</literal> attribute causes responses from the server for the request to be ignored if there is another similar request in the queue. This avoids unnecessary updates on the client when another update is expected. The request is still processed on the server, but if another similar request has been queued then no updates are made on the client.</simpara>

</section>

</section>
<section id="sect-Component_Reference-Common_Ajax_attributes-Events_and_JavaScript_interactions">
  <title>Events and JavaScript interactions</title>
  <simpara>JSF provides global <literal>jsf.ajax.onError</literal> and <literal>jsf.ajax.onEvent</literal> events to define handlers (the <literal>jsf.ajax.onEvent</literal> event is used for all <literal>begin</literal>, <literal>success</literal>, and <literal>complete</literal> events). RichFaces adds event-specific attributes at the component level.</simpara>
<section id="sect-Component_Reference-Events_and_JavaScript_interactions-onsubmit">
  <title><literal>onbeforesubmit</literal></title>
  <simpara>The <literal>onbeforesubmit</literal> event attribute invokes the event listener <emphasis>before</emphasis> an Ajax request is sent. The request is canceled if the event listener defined for the <literal>onbeforesubmit</literal> event returns <literal>false</literal>.</simpara>

</section>
<section id="sect-Component_Reference-Events_and_JavaScript_interactions-onbegin">
  <title><literal>onbegin</literal></title>
  <simpara>The <literal>onbegin</literal> event attribute invokes the event listener <emphasis>after</emphasis> an Ajax request is sent.</simpara>

</section>
<section id="sect-Component_Reference-Events_and_JavaScript_interactions-onbeforedomupdate">
  <title><literal>onbeforedomupdate</literal></title>
  <simpara>The <literal>onbeforedomupdate</literal> event attribute invokes the event listener after an Ajax response has been returned but <emphasis>before</emphasis> the DOMtree of the browser is updated.</simpara>

</section>
<section id="sect-Component_Reference-Events_and_JavaScript_interactions-oncomplete">
  <title><literal>oncomplete</literal></title>
  <simpara>The <literal>oncomplete</literal> event attribute invokes the event listener after an Ajax response has been returned <emphasis>and</emphasis> the DOMtree of the browser has been updated.</simpara>
<section id="sect-Component_Reference-Events_and_JavaScript_interactions-data">
  <title><literal>data</literal></title>
  <simpara>The <literal>data</literal> attribute allows additional data to be handled with the <literal>oncomplete</literal> event. Use JSFExpression Language ( EL) to reference the property of the managed bean, and its value will be serialized in JavaScript Object Notation ( JSON) and returned to the client side. The property can then be referenced through the <literal>event.data</literal> variable in the event attribute definitions. Both primitive types and complex types such as arrays and collections can be serialized and used with <literal>data</literal>.</simpara>
<example id="exam-Component_Reference-data-Data_reference_example">
  <title>Data reference example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:commandButton value="Update" oncomplete="showTheName(event.data.name)" data="#{userBean.name}" /&gt;
</programlisting>



</example>

</section>

</section>
<section id="sect-Component_Reference-Events_and_JavaScript_interactions-onerror">
  <title><literal>onerror</literal></title>
  <simpara>The <literal>onerror</literal> event attribute invokes the event listener when an error has occurred during Ajax communications.</simpara>

</section>
<section id="sect-Component_Reference-Events_and_JavaScript_interactions-Registering_event_callbacks_with_jQuery">
  <title>Registering event callbacks with jQuery</title>
  <simpara>RichFaces allows one to register callbacks for the events listed above using jQuery:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>ajaxsubmit</literal>: triggered <emphasis>before</emphasis> an Ajax request is sent.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>ajaxbegin</literal>: triggered <emphasis>after</emphasis> an Ajax request is sent.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>ajaxbeforedomupdate</literal>: triggered after an Ajax response has been returned but <emphasis>before</emphasis> the DOM tree of the browser has been updated.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>ajaxcomplete</literal>: triggered after an Ajax response has been returned <emphasis>and</emphasis> the DOM tree of the browser has been updated.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>The event callback can be registered either on a form or a whole page:</simpara>


<programlisting language="Java" linenumbering="unnumbered">&lt;h:outputScript&gt;
jQuery(document).ready(function() {
	jQuery(#{rich:element('form_id')}).on("ajaxsubmit", function() {
	    // the callback will be triggered before the form is submitted using JSF AJAX
    	console.log("ajaxsubmit");
	});


    jQuery(document).on("ajaxcomplete", function() {
        // the callback will be triggered for each completed JSF AJAX for the current page
    	console.log("ajaxcomplete");
	});
}
&lt;/h:outputScript&gt;</programlisting>



</section>

</section>

</chapter>
<chapter id="part-Component_Reference-Ajax_control_components">
  <title>Ajax control components</title>
  <chapter id="chap-Component_Reference-Actions">
  <title>Actions</title>
  <simpara>This chapter details the basic components that respond to a user action and submit an Ajax request.</simpara>
<section id="sect-Component_Reference-Actions-a4jajax">
  <title><literal>&lt;a4j:ajax&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:ajax&gt;</literal> behavior allows Ajax capability to be added to a non-Ajax component. The non-Ajax component must implement the ClientBehaviorHolderinterface for all the event attributes that support behavior rendering.</simpara>
<section id="sect-Component_Reference-a4jajax-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;a4j:ajax&gt;</literal> behavior is placed as a direct child to the component that requires Ajax support.</simpara>
<simpara>Point the <literal>event</literal> attribute to the standard JSF event that triggers the behavior. If the <literal>event</literal> attribute is not defined, the behavior is triggered on the event that normally provides interaction behavior for the parent component.</simpara>
<example id="exam-Component_Reference-a4jajax-a4jajax_example">
  <title><literal>&lt;a4j:ajax&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:panelGrid columns="2"&gt;
    &lt;h:inputText id="myinput" value="#{userBean.name}"&gt;
        &lt;a4j:ajax event="keyup" render="outtext" /&gt;
    &lt;/h:inputText&gt;
    &lt;h:outputText id="outtext" value="#{userBean.name}" /&gt;
&lt;/h:panelGrid&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-a4jajax-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>client-behavior-renderer-type</literal>: <literal>org.ajax4jsf.behavior.Ajax</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-id</literal>: <literal>org.ajax4jsf.behavior.Ajax</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.AjaxHandler</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-class</literal>: <literal>org.ajax4jsf.component.behavior.AjaxBehavior</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client-behavior-renderer-class</literal>: <literal>org.ajax4jsf.renderkit.AjaxBehaviorRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Actions-a4jparam">
  <title><literal>&lt;a4j:param&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:param&gt;</literal> behavior combines the functionality of the JavaServer Faces ( JSF) components <literal>&lt;f:param&gt;</literal> and <literal>&lt;f:actionListener&gt;</literal>.</simpara>
<section id="sect-Component_Reference-a4jparam-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage of the <literal>&lt;a4j:param&gt;</literal> requires three main attributes:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>value</literal> attribute is the initial value of the parameter.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>assignTo</literal> attribute defines the bean property. The property is updated if the parent command component performs an action event during the <emphasis>Process Request</emphasis> phase.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara><xref linkend="exam-Component_Reference-a4jparam-a4jparam_example"/> shows a simple implementation along with the accompanying managed bean.</simpara>
<example id="exam-Component_Reference-a4jparam-a4jparam_example">
  <title><literal>&lt;a4j:param&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form id="form"&gt;
    &lt;a4j:commandButton value="Set name to Alex" reRender="rep"&gt;
        &lt;a4j:param name="username" value="Alex" assignTo="#{paramBean.name}"/&gt;
    &lt;/a4j:commandButton&gt;
    &lt;h:outputText id="rep" value="Name: #{paramBean.name}"/&gt;
&lt;/h:form&gt;
</programlisting>




<programlisting language="Java" linenumbering="unnumbered">public class ParamBean {
    private String name = "John";

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}
</programlisting>


<simpara>When the Set name to Alexbutton is pressed, the application sets the <literal>name</literal> parameter of the bean to <literal>Alex</literal>, and displays the name in the output field.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jparam-Interoperability">
  <title>Interoperability</title>
  <simpara>The <literal>&lt;a4j:param&gt;</literal> tag can be used with non-Ajax components in addition to Ajax components. This includes components which are working through the <literal>GET</literal> request, such as the <literal>&lt;h:link&gt;</literal> and <literal>&lt;h:button&gt;</literal> components. In this way, data model values can also be updated without any Java code on the server side.</simpara>
<simpara>The <literal>converter</literal> attribute can be used to specify how to convert the value before it is submitted to the data model. The property is assigned the new value during the <emphasis>Update Model</emphasis> phase.</simpara>
<note>
  <title>Validation failure</title>
  
<simpara>If the validation of the form fails, the <emphasis>Update Model</emphasis> phase will be skipped and the property will not be updated.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-a4jparam-Passing_client-side_parameters">
  <title>Passing client-side parameters</title>
  <simpara>Variables from JavaScript functions can be used for the <literal>value</literal> attribute. In such an implementation, the <literal>noEscape</literal> attribute should be set to <literal>true</literal>. Using <literal>noEscape="true"</literal>, the <literal>value</literal> attribute can contain any JavaScript expression or JavaScript function invocation, and the result will be sent to the server as the <literal>value</literal> attribute.</simpara>
<example id="exam-Component_Reference-a4jparam-Passing_client-side_parameters">
  <title>Passing client-side parameters</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form&gt;
   &lt;a4j:commandButton value="Show Screen Size" render="infoPanel"&gt;
      &lt;a4j:param name="w" value="screen.width"
                 assignTo="#{paramBean.screenWidth}" noEscape="true" /&gt;
      &lt;a4j:param name="h" value="screen.height"
                 assignTo="#{paramBean.screenHeight}" noEscape="true" /&gt;
   &lt;/a4j:commandButton&gt;

   &lt;h:panelGrid columns="2" id="infoPanel"&gt;
      &lt;h:outputText value="Width:" /&gt;
      &lt;h:outputText value="#{paramBean.screenWidth}" /&gt;
      &lt;h:outputText value="Height:" /&gt;
      &lt;h:outputText value="#{paramBean.screenHeight}" /&gt;
   &lt;/h:panelGrid&gt;
&lt;/h:form&gt;
</programlisting>


<simpara>The command button triggers the <literal>&lt;a4j:param&gt;</literal> behaviors and renders the output text. The <literal>&lt;a4j:param&gt;</literal> behaviors pass client-side parameters for the screen width and height through the backing bean. These parameters are then used to populate the output text values.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jparam-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Parameter</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIParameter</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Parameter</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.ParameterHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Actions-a4jactionListener">
  <title><literal>&lt;a4j:actionListener&gt;</literal></title>
  <simpara>Use the <literal>&lt;a4j:actionListener&gt;</literal> tag to register an <literal>ActionListener</literal> class on a parent action component. The class provided as a listener must implement the javax.faces.event.ActionListenerinterface. Multiple listener methods can be registered on an action component in this way.</simpara>
<simpara>The <literal>&lt;a4j:actionListener&gt;</literal> tag differs from the standard JSF tag by allowing a listener method to be defined instead of just a class. Use the <literal>listener</literal> attribute to define the listener method.</simpara>

</section>
<section id="sect-Component_Reference-Actions-a4jcommandButton">
  <title><literal>&lt;a4j:commandButton&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:commandButton&gt;</literal> component is similar to the JavaServer Faces ( JSF) <literal>&lt;h:commandButton&gt;</literal> component, but additionally includes Ajax support.</simpara>
<figure id="figu-Component_Reference-a4jcommandButton-a4jcommandButton">
  <title><literal>&lt;a4j:commandButton&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-a4jcommandButton-a4jcommandButton.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-a4jcommandButton-a4jcommandButton</phrase></textobject>
  </mediaobject>
</figure>
<note>
  <title>The <literal>&lt;a4j:commandButton&gt;</literal> component executes the complete form</title>
  
<simpara>Button controls are typically used to perform complete form submissions for data storing. As a consequence, the <literal>&lt;a4j:commandButton&gt;</literal> component has the <literal>execute="@form"</literal> setting by default. To limit rendering to a different scope, redefine the <literal>execute</literal> attribute.</simpara>

  
</note>
<section id="sect-Component_Reference-a4jcommandButton-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;a4j:commandButton&gt;</literal> requires only the <literal>value</literal> attribute to function. Use the <literal>value</literal> attribute to specify the text of the button.</simpara>
<simpara>By default, the <literal>&lt;a4j:commandButton&gt;</literal> uses the <literal>click</literal> event instead of the <literal>submit</literal> event.</simpara>

</section>
<section id="sect-Component_Reference-a4jcommandButton-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.CommandButton</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UICommandButton</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Command</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.CommandButtonRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Actions-a4jcommandLink">
  <title><literal>&lt;a4j:commandLink&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:commandLink&gt;</literal> component is similar to the JavaServer Faces ( JSF) <literal>&lt;h:commandLink&gt;</literal> component, except that it includes plugged-in Ajax behavior.</simpara>
<figure id="figu-Component_Reference-a4jcommandLink-a4jcommandLink">
  <title><literal>&lt;a4j:commandLink&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-a4jcommandLink-a4jcommandLink.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-a4jcommandLink-a4jcommandLink</phrase></textobject>
  </mediaobject>
</figure>
<note>
  <title>The <literal>&lt;a4j:commandLink&gt;</literal> component executes the complete form</title>
  
<simpara>Link controls are typically used to perform complete form submissions for data storing. As a consequence, the <literal>&lt;a4j:commandLink&gt;</literal> component has the <literal>execute="@form"</literal> setting by default. To limit rendering to a different scope, redefine the <literal>execute</literal> attribute.</simpara>

  
</note>
<section id="sect-Component_Reference-a4jcommandLink-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;a4j:commandLink&gt;</literal> requires only the <literal>value</literal> attribute to function. Use the <literal>value</literal> attribute to specify the text of the link.</simpara>
<simpara>The <literal>&lt;a4j:commandLink&gt;</literal> uses the <literal>click</literal> event instead of the <literal>submit</literal> event.</simpara>

</section>
<section id="sect-Component_Reference-a4jcommandLink-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.CommandLink</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UICommandLink</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Command</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.CommandLinkRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Actions-a4jjsFunction">
  <title><literal>&lt;a4j:jsFunction&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:jsFunction&gt;</literal> component performs Ajax requests directly from JavaScript code and retrieves server-side data. The server-side data is returned in JavaScript Object Notation ( JSON) format prior to the execution of any JavaScript code defined using the <literal>oncomplete</literal> attribute.</simpara>
<section id="sect-Component_Reference-a4jjsFunction-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;a4j:jsFunction&gt;</literal> component requires the <literal>data</literal> attribute. Use the <literal>data</literal> attribute to define where the retrieved server-side data is stored.</simpara>
<simpara><xref linkend="exam-Component_Reference-a4jjsFunction-a4jjsFunction_example"/> shows how an Ajax request can be initiated from the JavaScript and a partial page update performed. The JavaScript function can be invoked with the data returned by the Ajax response.</simpara>
<example id="exam-Component_Reference-a4jjsFunction-a4jjsFunction_example">
  <title><literal>&lt;a4j:jsFunction&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;table width="400"&gt;
   &lt;tbody&gt;
      &lt;tr&gt;
         &lt;td&gt;
            &lt;span onmouseover="updateName('Kate')"
                  onmouseout="updateName('')"&gt;Kate&lt;/span&gt;
         &lt;/td&gt;
         &lt;td&gt;
            &lt;span onmouseover="updateName('John')"
                  onmouseout="updateName('')"&gt;John&lt;/span&gt;
         &lt;/td&gt;
         &lt;td&gt;
            &lt;span onmouseover="updateName('Alex')"
                  onmouseout="updateName('')"&gt;Alex&lt;/span&gt;
         &lt;/td&gt;
      &lt;/tr&gt;
      &lt;tr&gt;
         &lt;td colspan="3"&gt;
            Name: &lt;b&gt;&lt;h:outputText id="showname" value="#{functionBean.text}" /&gt;&lt;/b&gt;
         &lt;/td&gt;
      &lt;/tr&gt;
   &lt;/tbody&gt;
&lt;/table&gt;
&lt;h:form&gt;
   &lt;a4j:jsFunction name="updateName" render="showname"&gt;
      &lt;a4j:param name="name" assignTo="#{functionBean.text}"/&gt;
   &lt;/a4j:jsFunction&gt;
&lt;/h:form&gt;
</programlisting>


<simpara>The output text for the name is changed depending on which table cell the user hovers over with the mouse. The <literal>&lt;a4j:jsFunction&gt;</literal> component manages the updating and display of the name.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jjsFunction-Parameters_and_JavaScript">
  <title>Parameters and JavaScript</title>
  <simpara>The <literal>&lt;a4j:jsFunction&gt;</literal> component allows the use of the <literal>&lt;a4j:param&gt;</literal> component or the JavaServer Faces <literal>&lt;f:param&gt;</literal> component to pass any number of parameters for the JavaScript function.</simpara>

</section>
<section id="sect-Component_Reference-a4jjsFunction-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Function</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIFunction</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Command</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.FunctionRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Actions-a4jpoll">
  <title><literal>&lt;a4j:poll&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:poll&gt;</literal> component allows periodical sending of Ajax requests to the server. It is used for repeatedly updating a page at specific time intervals.</simpara>
<section id="sect-Component_Reference-a4jpoll-Timing_options">
  <title>Timing options</title>
  <simpara>The <literal>interval</literal> attribute specifies the time in milliseconds between requests. The default for this value is 1000 ms (1 second).</simpara>
<simpara>The <literal>&lt;a4j:poll&gt;</literal> component can be enabled and disabled using the <literal>enabled</literal> attribute. Using Expression Language ( EL), the <literal>enabled</literal> attribute can point to a bean property to apply a particular attribute value.</simpara>

</section>
<section id="sect-Component_Reference-a4jpoll-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Poll</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPoll</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Poll</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PollRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.AjaxPollHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Actions-a4jpush">
  <title><literal>&lt;a4j:push&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:push&gt;</literal> component performs real-time updates on the client side from events triggered at the server side. The events are pushed out to the client through the RichFaces messaging queue. When the <literal>&lt;a4j:push&gt;</literal> component is triggered by a server event, it can in turn cause Ajax updates and changes.</simpara>
<simpara>The <literal>&lt;a4j:push&gt;</literal> component uses the Comet model for pushing data to the client.</simpara>
<section id="sect-Component_Reference-a4jpush-Setting_up_push">
  <title>Setting up Push</title>
  <simpara>Using the Push component requires configuration steps which depends on an environment in which the Push is used:</simpara>
<section id="sect-Component_Reference-a4jpush-Installing_runtime_dependencies">
  <title>Installing runtime dependencies</title>
  <simpara>The <literal>&lt;a4j:push&gt;</literal> uses an Atmosphere framework for transporting messages. In order to use the Atmosphere on the server-side, it is necessary to add Atmosphere libraries into a project.</simpara>
<simpara>In a Maven-based project, you should add <literal>atmosphere-runtime</literal> as a runtime dependency (its version is managed by <literal>richfaces-bom</literal> that your project should be importing, check "RichFaces Developer Guide" for details of starting with Maven-based project):</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;dependency&gt;
    &lt;groupId&gt;org.atmosphere&lt;/groupId&gt;
    &lt;artifactId&gt;atmosphere-runtime&lt;/artifactId&gt;
&lt;/dependency&gt;</programlisting>


<simpara>For non-Maven-based projects, it is necessary to add dependencies manually - check "RichFaces Developer Guide", section "Project libraries and dependencies" for details.</simpara>

</section>
<section id="sect-Component_Reference-a4jpush-Registering_Push_servlet">
  <title>Registering Push servlet</title>
  <simpara>The Push requires a <literal>PushServlet</literal> registered in web application and listening for Push client connections.</simpara>
<simpara>In the Servlets 3.0 and higher environments, the servlet will be registered automatically.</simpara>
<simpara>However in the Servlets 2.5 and lower environments, the servlet needs to be registered manually in <literal>web.xml</literal>:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;!-- Push Servlet - listens for user sessions --&gt;
&lt;servlet&gt;
    &lt;servlet-name&gt;Push Servlet&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.richfaces.webapp.PushServlet&lt;/servlet-class&gt;
    &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
&lt;/servlet&gt;
&lt;servlet-mapping&gt;
    &lt;servlet-name&gt;Push Servlet&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/__richfaces_push&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;

&lt;!-- setups servlet-mapping in RichFaces configuration --&gt;
&lt;context-param&gt;
    &lt;param-name&gt;org.richfaces.push.handlerMapping&lt;/param-name&gt;
    &lt;param-value&gt;/__richfaces_push&lt;/param-value&gt;
&lt;/context-param&gt;</programlisting>


<note>
  <title>Manual registration of servlet in Servlets 3.0</title>
  
<simpara>When you attempt to register the Push servlet manually in Servlet 3.0 environments, RichFaces will detect that the Push servlet is already registered and avoid initializing it again.</simpara>
<simpara>However, be sure to setup the Push servlet to support asynchronous requests - modify the servlet registration from the previous <literal>web.xml</literal> snippet as follows:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;servlet&gt;
    &lt;servlet-name&gt;Push Servlet&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.richfaces.webapp.PushServlet&lt;/servlet-class&gt;
    &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
    &lt;async-supported&gt;true&lt;/async-supported&gt;
&lt;/servlet&gt;</programlisting>



  
</note>
<note>
  <title>Switching to Blocking I/O instead of asynchronous servlets</title>
  
<simpara>Although a container you use supports Servlets 3.0, you may experience problems with using asynchronous servlets.</simpara>
<simpara>It is possible to force the Atmosphere to use a blocking I/O approach with the following <literal>web.xml</literal> configuration:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;context-param&gt;
    &lt;param-name&gt;org.atmosphere.useBlocking&lt;/param-name&gt;
    &lt;param-value&gt;true&lt;/param-value&gt;
&lt;/context-param&gt;</programlisting>



  
</note>

</section>

</section>
<section id="sect-Component_Reference-a4jpush-Server_side_Push_methods">
  <title>Server-side Push methods</title>
  <simpara>The Push events can be fired on the server-side in several ways:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><emphasis>TopicsContext</emphasis> - accesses a RichFaces message queue directly</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><emphasis>Push CDI</emphasis> - uses the CDI Event mechanism to fire messages</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><emphasis>Push JMS</emphasis> - the RichFaces Push consumes messages from an enterprise messaging system and exposes them to the client (tightly coupled with the JMS runtime)</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-a4jpush-Client_side_Push_methods">
  <title>Client-side Push methods</title>
  <simpara>On the client side, push notifications may be processed in the following ways:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>ondataavailable</literal> event handler (serialized message is available)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Client behaviors attached to <literal>dataavailable</literal> event</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-a4jpush-Push_Topics">
  <title>Push Topics</title>
  <simpara>The Push messages are delivered to the client based on a <literal>TopicKey</literal>'s name (e.g. <literal>someTopic</literal>).</simpara>
<simpara>The <literal>TopicKey</literal> can optionally include a subtopic name (e.g. <literal>subtopic@anotherTopic</literal>).</simpara>
<simpara>On the client side, the topic is represted by an <literal>&lt;a4j:push&gt;</literal>'s attribute <literal>address</literal>.</simpara>
<note>
  <title>Push Topic relates to JMS topic</title>
  
<simpara>The format for the name of the push topic is very close to the JMS topic name and thus enables a seamless transport of JMS messages to the RichFaces message queue.</simpara>

  
</note>
<note>
  <title>Topics with EL expressions</title>
  
<simpara>Since the topic key can contain EL expressions, it is possible to achieve dynamic end-points (e.g. addressing specific clients).</simpara>
<simpara>You need to push a message by using <literal>TopicContext.publish(TopicKey key, Object message)</literal> or using CDI events to publish message to dynamically evaluated topic key.</simpara>
<simpara>The <literal>&lt;a4j:push&gt;</literal>'s attribute <literal>address</literal> accepts EL expressions.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-a4jpush-Handling_a_push_message">
  <title>Handling a push message</title>
  <simpara>A push message sent from the server to the <literal>&lt;a4j:push&gt;</literal> component on the client will cause it to trigger any event handlers defined using the <literal>dataavailable</literal> event handler.</simpara>
<simpara>The <literal>&lt;a4j:push&gt;</literal> component should also include the <literal>onerror</literal> event handler to inform the user when an error has occurred with the push messages.</simpara>
<simpara><literal>&lt;a4j:push&gt;</literal> can be used for either immediate processing of messages (like in the previous example) or it can trigger a partial page update. Check out following samples:</simpara>
<example id="exam-Component_Reference-a4jpush-Handling_a_push_message">
  <title>Handling a push message</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:push address="chat"
          onerror="alert(event.rf.data)"
          ondataavailable="chat.addMessage(event.rf.data)" /&gt;
</programlisting>


<simpara>This example uses the <literal>dataavailable</literal> event attribute with some JavaScript to update messages in a chat room. The <literal>event.rf.data</literal> parameter contains Push message data serialized to JavaScript.</simpara>

</example>
<example id="exam-Component_Reference-a4jpush-Updating_DOM_for_each_push_notification">
  <title>Updating DOM for each push message</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:push address="chat"
          onerror="alert(event.rf.data)"&gt;
    &lt;a4j:ajax event="datavailable" render="chat" /&gt;
&lt;/a4j:push&gt;</programlisting>


<simpara>This example uses the <literal>dataavailable</literal> event handler to trigger an AJAX request and a partial page update.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jpush-Handling_a_push_subscription">
  <title>Handling a push subscription</title>
  <simpara>The <literal>&lt;a4j:push&gt;</literal> component establishes connection with server on complete page load (when document is ready).</simpara>
<simpara>It means that the application starts to handle push messages once the page is completely loaded.</simpara>
<simpara>However time-critical applications may require keeping client stricly synchronized with the server state.</simpara>
<simpara>For such applications you may use <literal>onsubscribed</literal> event handler, which is triggered every time the given component is successfully subscribed to the address/topic it listens to (on a page load and on each AJAX re-render).</simpara>
<example id="exam-Component_Reference-a4jpush-Handling_a_push_subscription">
  <title>The time-critical updates in stock application</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:push address="stockUpdates"
          onerror="alert(event.rf.data)"&gt;
    &lt;a4j:ajax event="dataavailable" render="stocksTable" /&gt;
	&lt;a4j:ajax event="subscribed" render="stocksTable" /&gt;
&lt;/a4j:push&gt;
</programlisting>


<simpara>This example uses the <literal>subscribed</literal> event to update the table content once the push component is subscribed to the topic, ensuring that the table content is not stale.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jpush-Using_TopicsContext_to_publish_message">
  <title>Using TopicsContext to publish message</title>
  <simpara>Messages could be produced using the <literal>TopicsContext</literal> interface directly as in the following sample:</simpara>


<programlisting language="Java" linenumbering="unnumbered">private TopicKey topicKey = new TopicKey("chat");

public void initializeTopic() {
	TopicsContext topicsContext = TopicsContext.lookup();
	topicsContext.getOrCreateTopic(topicKey);
}

public void sendMessage(String message) throws MessageException {
    TopicsContext topicsContext = TopicsContext.lookup();
    topicsContext.publish(topicKey, message);
}</programlisting>


<simpara>A topic needs to first be created using <literal>TopicsContext#getOrCreate(TopicKey)</literal> where <literal>TopicKey</literal> is the name of the topic. A message to the topic can be sent using the method: <literal>TopicsContext#publish(topicKey, message)</literal>.</simpara>

</section>
<section id="sect-Component_Reference-a4jpush-Push_CDI_Integration">
  <title>Integrating Push with CDI events</title>
  <simpara>An alternative way of producing messages is to use the CDI event mechanism.</simpara>
<simpara>Push notifications can be produced by annotating a CDI event injection point with the <literal>@Push</literal> annotation, which specifies an end-point (topic name).</simpara>
<simpara>The payload of the message is the serialized object sent using the CDI event interface ( <literal>Event.fire(T object)</literal>).</simpara>


<programlisting language="Java" linenumbering="unnumbered">@Inject
@Push(topic = "chat")
Event&lt;String&gt; pushEvent;

public void sendMessage(String message) {
    pushEvent.fire(message);
}</programlisting>



</section>
<section id="sect-Component_Reference-a4jpush-Push_and_JMS_integration">
  <title>Push and JMS integration</title>
  <simpara>An integration of the RichFaces Push and the Java Messaging Service ( JMS) allows to write robust interactive applications.</simpara>
<section id="_enabling_jms_integraction">
  <title>Enabling JMS integraction</title>
  <simpara>The JMS integration needs to be enabled in <literal>web.xml</literal> with a following configuration:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;context-param&gt;
    &lt;param-name&gt;org.richfaces.push.jms.enabled&lt;/param-name&gt;
    &lt;param-value&gt;true&lt;/param-value&gt;
&lt;/context-param&gt;</programlisting>



</section>
<section id="_configuring_jms_backend">
  <title>Configuring JMS backend</title>
  <simpara>The JMS instance on the back-end must be configured to work with your <literal>&lt;a4j:push&gt;</literal> components.</simpara>
<note>
  <title>Configuring JMS on JBoss Application Server</title>
  
<simpara>Refer to the JBoss Application Server Administration Console Guidefor details on managing JBoss Application Server through the Administration Console.</simpara>

  
</note>
<example id="exam-Component_Reference-a4jpush-JMS_server_configuration">
  <title>JMS server configuration</title>
<simpara>This simple example describes the JMS server configuration required for a pushing server date to the client.</simpara>
<simpara>The JMS server needs to be setup in order to propagate JMS messages to Push components. Create a new JMS topic using the following settings:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>Name:datePush</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>JNDI name:/topic/datePush</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Use the default settings for other options.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Add a single role for the topic in the same form using the following settings:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>Name:guest</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Send:true</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Consume:true</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Create subscriber:true</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Delete subscriber:true</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Create durable subscriber:true</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Delete durable subscriber:true</simpara>
      
    </listitem>
  
</itemizedlist>


</example>
<simpara>Ensure the Create durable subscriberand the Delete durable subscriberoptions are set to truefor proper push functionality.</simpara>
<note>
  <title>Durable subscriptions</title>
  
<simpara>Durable subscriptions receive all events, including those events which were sent while the push component was not connected.</simpara>
<simpara>Refer to JMS Documentationfor details on configuring the JMS Server.</simpara>

  
</note>
<note>
  <title>JMS integration with custom configuration</title>
  
<simpara>RichFaces looks for the JMS Connection Factory on the JNDI context <literal>/ConnectionFactory</literal> by default.</simpara>
<simpara>The prefix <literal>/topic</literal> is used for deriving JMS topic names from Push topic names.</simpara>
<simpara>When integrating component into an enterprise system, this defaults can be changed.</simpara>
<simpara>Use following <literal>web.xml</literal> parameters to change default values: <literal>org.richfaces.push.jms.connectionFactory</literal>, <literal>org.richfaces.push.jms.topicsNamespace</literal>.</simpara>
<simpara>When RichFaces obtains a connection, an empty user name is used with an empty password.</simpara>
<simpara>Use following <literal>web.xml</literal> parameters or equivalent JVM parameters to change default values: <literal>org.richfaces.push.jms.connectionUsername</literal>, <literal>org.richfaces.push.jms.connectionPassword</literal>.</simpara>

<literallayout class="monospaced">,</literallayout>


  
</note>

</section>
<section id="_sending_and_receiving_push_messages_using_jms">
  <title>Sending and receiving Push messages using JMS</title>
  <simpara>The JMS message which should be propagated to Push needs to be created with the method <literal>session.createObjectMessage(message);</literal>.</simpara>
<simpara>The message could be then published using <literal>publisher.publish(message);</literal> like in a following example:</simpara>
<example id="exam-Component_Reference-a4jpush-Sending_messages_using_JMS">
  <title>Sending messages using JMS</title>


<programlisting language="Java" linenumbering="unnumbered">TopicConnection connection;
TopicSession session;
TopicPublisher publisher;

public void sendCurrentDate() throws JMSException {
    String currentDate = new Date().toString();
    ObjectMessage message = session.createObjectMessage(message);
    publisher.publish(message);
}

// messaging needs to be initialized before using method #sendCurrentDate()
private void initializeMessaging() throws JMSException, NamingException {
    if (connection == null) {
        TopicConnectionFactory tcf = (TopicConnectionFactory) InitialContext.doLookup("java:/ConnectionFactory");
        connection = tcf.createTopicConnection();
    }
    if (session == null) {
        session = connection.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
    }
    if (topic == null) {
        topic = InitialContext.doLookup("topic/datePush");
    }
    if (publisher == null) {
        publisher = session.createPublisher(topic);
    }
}</programlisting>



</example>
<simpara>Receiving messages from a JMS queue doesn&#8217;t differ from receiving messages sent by the <literal>TopicsContext</literal> or using CDI events.</simpara>
<example id="exam-Component_Reference-a4jpush-Receiving_messages_using_JMS">
  <title>Receiving messages using JMS</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:push id="datePush" address="datePush"
            ondataavailable="jQuery(#{rich:element('serverDate')}).text(event.rf.data)" /&gt;

&lt;a4j:outputPanel id="serverDate" layout="block"&gt;
    &lt;i&gt;waiting for event...&lt;/i&gt;
&lt;/a4j:outputPanel&gt;</programlisting>



</example>
<simpara>The above example demonstrates a simple use of the <literal>&lt;a4j:push&gt;</literal> tag that causes an immediate update of the page content.</simpara>

</section>

</section>
<section id="sect-Component_Reference-a4jpush-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Push</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPush</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Push</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PushRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Resources">
  <title>Resources</title>
  <simpara>This chapter covers those components used to handle and manage resources and beans.</simpara>
<section id="sect-Component_Reference-Resources-a4jmediaOutput">
  <title><literal>&lt;a4j:mediaOutput&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:mediaOutput&gt;</literal> component is used for generating images, video, sounds, and other resources defined on the fly.</simpara>
<section id="sect-Component_Reference-a4jmediaOutput-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>createContent</literal> attribute points to the method used for generating the displayed content.</simpara>
<simpara>If necessary, the <literal>value</literal> attribute can be used to pass input data to the content generation method specified with <literal>createContent</literal>. The <literal>cacheable</literal> attribute specifies whether the resulting content will be cached or not.</simpara>

</section>
<section id="sect-Component_Reference-a4jmediaOutput-Handling_content">
  <title>Handling content</title>
  <simpara>The <literal>mimeType</literal> attribute describes the type of output content, and corresponds to the type in the header of the HTTPrequest. The <literal>element</literal> attribute defines XHTMLelement used to display the content:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>img</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>object</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>applet</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>script</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>link</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>a</literal></simpara>
      
    </listitem>
  
</itemizedlist>

<example id="exam-Component_Reference-a4jmediaOutput-a4jmediaOutput_example">
  <title><literal>&lt;a4j:mediaOutput&gt;</literal> example</title>
<simpara>This example uses the <literal>&lt;a4j:mediaOutput&gt;</literal> component to generate a JPEGimage of verification digits. The code on the application page is a single element:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:mediaOutput element="img" cacheable="false" session="false"
                 createContent="#{mediaBean.paint}" value="#{mediaData}"
                 mimeType="image/jpeg" /&gt;
</programlisting>


<simpara>The <literal>&lt;a4j:mediaOutput&gt;</literal> component uses the MediaBean.paintmethod to create the image. The method generates a random number, which is then converted into an output stream and rendered to a JPEGimage. The <literal>MediaBean</literal> class is as follows:</simpara>


<programlisting language="Java" linenumbering="unnumbered">package demo;

import java.awt.Graphics2D;
import java.awt.image.BufferedImage;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Random;
import javax.imageio.ImageIO;

public class MediaBean {

    public void paint(OutputStream out, Object data) throws IOException {

        Integer high = 9999;
        Integer low = 1000;
        Random generator = new Random();
        Integer digits = generator.nextInt(high - low + 1) + low;

        if (data instanceof MediaData) {
            MediaData paintData = (MediaData) data;
            BufferedImage img = new BufferedImage(paintData.getWidth(),paintData.getHeight(),BufferedImage.TYPE_INT_RGB);
            Graphics2D graphics2D = img.createGraphics();
            graphics2D.setBackground(paintData.getBackground());
            graphics2D.setColor(paintData.getDrawColor());
            graphics2D.clearRect(0,0,paintData.getWidth(),paintData.getHeight());
            graphics2D.setFont(paintData.getFont());
            graphics2D.drawString(digits.toString(), 20, 35);
            ImageIO.write(img,"png",out);
        }
    }
}
</programlisting>


<simpara>Another class, <literal>MediaData</literal> is required by the <literal>value</literal> attribute for keeping data to be used as input for the content creation method. The <literal>MediaData</literal> class is as follows:</simpara>


<programlisting language="Java" linenumbering="unnumbered">package demo;

import java.awt.Color;
import java.awt.Font;
import java.io.Serializable;

public class MediaData implements Serializable {

    private static final long serialVersionUID = 1L;

    Integer Width=110;
    Integer Height=50;

    Color Background=new Color(190, 214, 248);
    Color DrawColor=new Color(0,0,0);

    Font font = new Font("Serif", Font.TRUETYPE_FONT, 30);

    /* Corresponding getters and setters */
    ...

}
</programlisting>


<simpara>The <literal>&lt;a4j:mediaOutput&gt;</literal> component uses the <literal>MediaBean</literal> and <literal>MediaData</literal> classes to generate a new image on each page refresh.</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-a4jmediaOutput-a4jmediaOutput_example_result.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-a4jmediaOutput-a4jmediaOutput_example_result</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>The generated image containing a random verification number.</simpara>

</example>
<note>
  <title><literal>Serializable</literal> interface</title>
  
<simpara>A bean class passed using the <literal>value</literal> attribute of <literal>&lt;a4j:mediaOutput&gt;</literal> should implement the <literal>Serializable</literal> interface so that it will be encoded to the URLof the resource.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-a4jmediaOutput-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.MediaOutput</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIMediaOutput</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.MediaOutput</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.MediaOutputRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Containers">
  <title>Containers</title>
  <simpara>This chapter details those components in the <literal>a4j</literal> tag library which define an area used as a container or wrapper for other components.</simpara>
<section id="sect-Component_Reference-Containers-a4joutputPanel">
  <title><literal>&lt;a4j:outputPanel&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:outputPanel&gt;</literal> component is used to group together components in to update them as a whole, rather than having to specify the components individually.</simpara>
<section id="sect-Component_Reference-a4joutputPanel-Aiding_complex_Ajax_rendering">
  <title>Aiding complex Ajax rendering</title>
  <simpara>Use the <literal>&lt;a4j:outputPanel&gt;</literal> component to wrap behaviors when using complex Ajax rendering. Parent components may not render correctly when attached behaviors trigger updates. Point the behaviors to the wrapping <literal>&lt;a4j:outputPanel&gt;</literal> component instead of the parent components. The <literal>&lt;a4j:outputPanel&gt;</literal> component is properly encoded to ensure the wrapped components are correctly rendered.</simpara>

</section>
<section id="sect-Component_Reference-a4joutputPanel-Panel_appearance">
  <title>Panel appearance</title>
  <simpara>The <literal>layout</literal> attribute can be used to determine how the component is rendered in HTML:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>layout="inline"</literal> is the default behavior, which will render the component as a pair of <literal>&lt;span&gt;</literal> tags containing the child components.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>layout="block"</literal> will render the component as a pair of <literal>&lt;div&gt;</literal> tags containing the child components, which will use any defined <literal>&lt;div&gt;</literal> element styles.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Setting <literal>ajaxRendered="true"</literal> will cause the <literal>&lt;a4j:outputPanel&gt;</literal> to be updated with each Ajax response for the page, even when not listed explicitly by the requesting component. This can in turn be overridden by specific attributes on any requesting components.</simpara>

</section>
<section id="sect-Component_Reference-a4joutputPanel-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.OutputPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIOutputPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Panel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.OutputPanelRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Containers-a4jregion">
  <title><literal>&lt;a4j:region&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:region&gt;</literal> component specifies a part of the JSF component tree to be processed on the server. The region causes all the <literal>a4j</literal> and <literal>rich</literal> Ajax controls to execute: decoding, validating, and updating the model. The region causes these components to execute even if not explicitly declared. As such, processing areas can more easily be marked using a declarative approach.</simpara>
<simpara>Regions can be nested, in which case only the parent region of the component initiating the request will be processed.</simpara>
<section id="sect-Component_Reference-a4jregion-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Region</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIRegion</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.AjaxContainer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Validation">
  <title>Validation</title>
  <simpara>JavaServer Faces 2 provides built-in support for bean validation as per the Java Specification Request JSR-303 standard. As such, containers must validate model objects. Validation is performed at different application tiers according to annotation-based constraints. Refer to link:http://jcp.org/en/jsr/detail?id=303 for further details on the JSR-303 specification.</simpara>
<simpara><xref linkend="exam-Component_Reference-Validation-JSR-303_validation_annotations"/> shows an example JSF managed bean. The bean includes JSR-303 annotations for validation. Validation annotations defined in this way are registered on components bound to the bean properties, and validation is triggered in the <emphasis>Process Validation</emphasis> phase.</simpara>
<example id="exam-Component_Reference-Validation-JSR-303_validation_annotations">
  <title>JSR-303 validation annotations</title>


<programlisting language="Java" linenumbering="unnumbered">import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.Pattern;
import javax.validation.constraints.Size;

@ManagedBean
@RequestScoped
public class UserBean {

   @Size(min=3, max=12)
   private String name = null;

   @Pattern(regexp = "^[\\w\\-]([\\.\\w])+[\\w]+@([\\w\\-]+\\.)+[a-zA-Z]{2,4}$" , message="Bad email")
   private String email = null;

   @Min(value = 18)
   @Max(value = 99)
   private Integer age;

//...
//Getters and Setters
}
</programlisting>



</example>
<note>
  <title>Requirements</title>
  
<simpara>Bean validation in both JavaServer Faces and RichFaces requires the <emphasis>JSR-303</emphasis> implementation. The implementation is bundled with JEE 6 Application Server.</simpara>
<simpara>If using Tomcator another simple servlet container, add the _validation-api_Java Archive and a validation provider (such as Hibernate Validator) to your application libraries.</simpara>

  
</note>
<section id="sect-Component_Reference-Validation-richvalidator">
  <title><literal>&lt;rich:validator&gt;</literal> client-side validation</title>
  <simpara>The validation built in to JavaServer Faces 2 occurs on the server side. The <literal>&lt;rich:validator&gt;</literal> behavior adds client-side validation to a control based on registered server-side validators. It provides this validation without the need to reproduce the server-side annotations. The <literal>&lt;rich:validator&gt;</literal> behavior triggers all client validator annotations listed in the relevant managed bean.</simpara>
<section id="sect-Component_Reference-richvalidator-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:validator&gt;</literal> behavior is added as a child element to any input control. The value of the input control must reference a managed bean. The content of the input control validates on the client-side based on registered server-side validators included in the managed bean.</simpara>
<example id="exam-Component_Reference-richvalidator-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:inputText value="#{userBean.name}"&gt;
   &lt;rich:validator/&gt;
&lt;/h:inputText&gt;
</programlisting>



</example>
<note>
  <title>JSF validation tags</title>
  
<simpara>JSF validation tags, such as <literal>&lt;f:validateLength&gt;</literal> and <literal>&lt;f:validateDoubleRange&gt;</literal> tags, can be declared alongside <literal>&lt;rich:validator&gt;</literal> behaviors. However, because this duplicates the validation processes at both the view and model level, it is not recommended.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-richvalidator-Messages_from_client-side_validators">
  <title>Messages from client-side validators</title>
  <simpara>Use the <literal>&lt;rich:message&gt;</literal> and <literal>&lt;rich:messages&gt;</literal> components to display validation messages. The <literal>for</literal> attribute of the <literal>&lt;rich:message&gt;</literal> component references the <literal>id</literal> identifier of the input control being validated.</simpara>
<example id="exam-Component_Reference-richvalidator-Messages">
  <title>Messages</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel header="User information"&gt;
   &lt;h:panelGrid columns="3"&gt;

      &lt;h:outputText value="Name:" /&gt;
      &lt;h:inputText value="#{validationBean.name}" id="name"&gt;
         &lt;rich:validator /&gt;
      &lt;/h:inputText&gt;
      &lt;rich:message for="name" /&gt;

      &lt;h:outputText value="Email" /&gt;
      &lt;h:inputText value="#{validationBean.email}" id="email"&gt;
         &lt;rich:validator /&gt;
      &lt;/h:inputText&gt;
      &lt;rich:message for="email" /&gt;

      &lt;h:outputText value="Age" /&gt;
      &lt;h:inputText value="#{validationBean.age}" id="age"&gt;
         &lt;rich:validator /&gt;
      &lt;/h:inputText&gt;
      &lt;rich:message for="age" /&gt;

      &lt;h:outputText value="I agree the terms" /&gt;
      &lt;h:selectBooleanCheckbox value="#{validationBean.agree}" id="agree"&gt;
         &lt;rich:validator/&gt;
      &lt;/h:selectBooleanCheckbox&gt;
      &lt;rich:message for="agree" /&gt;

   &lt;/h:panelGrid&gt;
&lt;/rich:panel&gt;
</programlisting>


<simpara>Failed validation checks are reported using <literal>&lt;rich:message&gt;</literal> components. The validation annotations in the managed bean are outlined in <xref linkend="exam-Component_Reference-Validation-JSR-303_validation_annotations"/>.</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-richvalidator-Messages.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richvalidator-Messages</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>Failed validation checks are reported using <literal>&lt;rich:message&gt;</literal> components.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richvalidator-Validation_triggers">
  <title>Validation triggers</title>
  <simpara>Use the <literal>event</literal> attribute to specify which event on the input control triggers the validation process. By default, the <literal>&lt;rich:validator&gt;</literal> behavior triggers validation when the input control is changed ( <literal>event="change"</literal>).</simpara>
<example id="exam-Component_Reference-richvalidator-Validation_triggers">
  <title>Validation triggers</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:inputText value="#{userBean.name}"&gt;
   &lt;rich:validator event="keyup"/&gt;
&lt;/h:inputText&gt;
</programlisting>


<simpara>The <literal>event</literal> attribute is changed to the <literal>keyup</literal> event, such that validation takes place after each key press.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richvalidator-Ajax_fall-backs">
  <title>Ajax fall-backs</title>
  <simpara>If no client-side validation method exists for a registered server-side validator, Ajax fall-back is used. The <literal>&lt;rich:validator&gt;</literal> behavior invokes all available client-side validators. If all the client-side validators return valid, RichFaces performs an Ajax request to invoke the remaining validators on the server side.</simpara>

</section>
<section id="sect-Component_Reference-richvalidator-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>client-behavior-renderer-type</literal>: <literal>org.richfaces.ClientValidatorRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-id</literal>: <literal>org.richfaces.behavior.ClientValidator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.ClientValidatorHandler</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-class</literal>: <literal>org.ajax4jsf.component.behavior.ClientValidatorImpl</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client-behavior-renderer-class</literal>: <literal>org.richfaces.renderkit.html.ClientValidatorRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Validation-richgraphValidator">
  <title><literal>&lt;rich:graphValidator&gt;</literal> object validation</title>
  <simpara>The <literal>&lt;rich:graphValidator&gt;</literal> component is used to wrap a set of input components related to one object. The object defined by the <literal>&lt;rich:graphValidator&gt;</literal> component can then be completely validated. The validation includes all object properties, even those which are not bound to the individual form components. Validation performed in this way allows for cross-field validation in complex forms.</simpara>
<note>
  <title>Validation without model updates</title>
  
<simpara>The <literal>&lt;rich:graphValidator&gt;</literal> component performs a clone()method on the referenced bean instance during the validation phase. The cloned object is validated and triggers any required validation messages. As such, the model object remains clean, and the lifecycle is interrupted properly after the <emphasis>Process Validations</emphasis> phase.</simpara>
<simpara>Ensure the referenced object implements the Cloneableinterface, and allows a deep clone if required.</simpara>

  
</note>
<section id="sect-Component_Reference-richgraphValidator-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:graphValidator&gt;</literal> element must wrap all the input controls that are required to validate the object. The <literal>value</literal> attribute names the bean for the validating object.</simpara>
<example id="exam-Component_Reference-richgraphValidator-Basic_usage">
  <title>Basic usage</title>
<simpara>The example demonstrates a simple form for changing a password. The two entered passwords must match, so a <literal>&lt;rich:graphValidator&gt;</literal> component is used for cross-field validation.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form&gt;
   &lt;rich:graphValidator value="#{userBean}"&gt;
      &lt;rich:panel header="Change password"&gt;
         &lt;rich:messages/&gt;
         &lt;h:panelGrid columns="3"&gt;
            &lt;h:outputText value="Enter new password:" /&gt;
            &lt;h:inputSecret value="#{userBean.password}" id="pass"/&gt;
            &lt;rich:message for="pass"/&gt;
            &lt;h:outputText value="Confirm the new password:" /&gt;
            &lt;h:inputSecret value="#{userBean.confirm}" id="conf"/&gt;
            &lt;rich:message for="conf"/&gt;
         &lt;/h:panelGrid&gt;
         &lt;a4j:commandButton value="Store changes"
                            action="#{userBean.storeNewPassword}" /&gt;
      &lt;/rich:panel&gt;
   &lt;/rich:graphValidator&gt;
&lt;/h:form&gt;
</programlisting>


<simpara>The input controls validate against the following bean:</simpara>


<programlisting language="Java" linenumbering="unnumbered">@ManagedBean
@RequestScoped
public class UserBean implements Cloneable {

   @Size(min = 5, max = 15, message="Wrong size for password")
   private String password;
   @Size(min = 5, max = 15, message="Wrong size for confirmation")
   private String confirm;
   private String status = "";

   @AssertTrue(message = "Different passwords entered!")
   public boolean isPasswordsEquals() {
      return password.equals(confirm);
   }

   public void storeNewPassword() {
      FacesContext.getCurrentInstance().addMessage("", new FacesMessage(FacesMessage.SEVERITY_INFO, "Succesfully changed!", "Succesfully changed!"));
   }

   ...
}
</programlisting>


<simpara>When validation occurs, the whole object is validated against the annotation contstraints. The <literal>@AssertTrue</literal> annotation relies on the isPasswordsEqual()function to check whether the two entered passwords are equal.</simpara>
<simpara>If the entered passwords do not match, an error message is displayed:</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-richgraphValidator-Basic_usage.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richgraphValidator-Basic_usage</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>Failed validation checks are reported using <literal>&lt;rich:message&gt;</literal> components.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richgraphValidator-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.GraphValidator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIGraphValidator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.GraphValidator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.GraphValidatorHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Processing_management">
  <title>Processing management</title>
  <simpara>This chapter covers those components that manage the processing of information, requests, and updates.</simpara>
<section id="sect-Component_Reference-Processing_management-a4jqueue">
  <title><literal>&lt;a4j:queue&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:queue&gt;</literal> component manages the JSF queue of Ajax requests. It provides additional options for a finer control of request processing.</simpara>
<section id="sect-Component_Reference-a4jqueue-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;a4j:queue&gt;</literal> component works in the same basic way as the standard JSF queue. It can be enabled and disabled through the <literal>enabled</literal> attribute.</simpara>
<note>
  <title>Requests from other libraries</title>
  
<simpara>The <literal>&lt;a4j:queue&gt;</literal> component does not handle standard JSF requests or requests from component libraries other than RichFaces.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-a4jqueue-Delaying_requests">
  <title>Delaying requests</title>
  <simpara>Use the <literal>requestDelay</literal> attribute to add a delay between each request in the queue. Set the <literal>requestDelay</literal> attribute to the number of milliseconds to wait in between each request. Delaying requests avoids unnecessary processing for actions that would otherwise cause multiple requests, such as typing. Similar requests in the queue are combined while waiting for the request delay.</simpara>
<example id="exam-Component_Reference-a4jqueue-Delaying_requests">
  <title>Delaying requests</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:queue requestDelay="1500"/&gt;</programlisting>


<simpara>The queue delays each request by 1500 milliseconds.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jqueue-Duplicate_responses">
  <title>Duplicate responses</title>
  <simpara>The client side can update unnecessarily if duplicate responses require similar updates. Set <literal>ignoreDupResponses="true"</literal> to ignore duplicate responses. With this setting, the client will not update from a request if a similar request is in the queue.</simpara>

</section>
<section id="sect-Component_Reference-a4jqueue-Queue_scopes">
  <title>Queue scopes</title>
  <simpara>Define the queue scope to make it the default queue for all requests in that scope. The scope depends on the placement of the queue and any naming identifiers.</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>An unnamed <literal>&lt;a4j:queue&gt;</literal> component placed outside any forms becomes the default queue for all requests on the page.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>An unnamed <literal>&lt;a4j:queue&gt;</literal> component placed inside a form becomes the default queue for all requests within that form.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Use the <literal>name</literal> identifier attribute to name an <literal>&lt;a4j:queue&gt;</literal> component. Named queues can be accessed with the <literal>&lt;a4j:attachQueue&gt;</literal> behavior to act as a queue for specific components and behaviors. Refer to <xref linkend="sect-Component_Reference-Processing_management-a4jattachQueue"/> for details.</simpara>
      
    </listitem>
  
</itemizedlist>

<example id="exam-Component_Reference-a4jqueue-Queue_scopes">
  <title>Queue scopes</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:queue name="viewQueue" requestDelay="2000"/&gt;
&lt;h:form&gt;
	&lt;a4j:queue name="formQueue" requestDelay="1500"/&gt;
   ...
&lt;/h:form&gt;
</programlisting>


<simpara>The queue outside the form is scoped to the view. The queue inside the form is scoped only to that form.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jqueue-a4jqueue_client-side_events">
  <title><literal>&lt;a4j:queue&gt;</literal> client-side events</title>
  <simpara>The <literal>&lt;a4j:queue&gt;</literal> component features several events relating to queuing actions in addition to the common JSF events:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>complete</literal> event is fired after a request is completed. The request object is passed as a parameter to the event handler, so the queue is accessible using <literal>request.queue</literal> and the element which was the source of the request is accessible using <literal>this</literal>.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>requestqueue</literal> event is fired after a new request has been added to the queue.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>requestdequeue</literal> event is fired after a request has been removed from the queue.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-a4jqueue-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Queue</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIQueue</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Queue</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.QueueRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-Processing_management-a4jattachQueue">
  <title><literal>&lt;a4j:attachQueue&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:attachQueue&gt;</literal> behavior is used together with a <literal>&lt;a4j:queue&gt;</literal> component to further customize queuing for particular components and behaviors. The <literal>&lt;a4j:attachQueue&gt;</literal> behavior can override the scope-wide queue settings for an individual component, or attach specific requests to a queue.</simpara>
<section id="sect-Component_Reference-a4jattachQueue-Overriding_scope_settings">
  <title>Overriding scope settings</title>
  <simpara>Queues can be scoped to various levels as described in <xref linkend="sect-Component_Reference-a4jqueue-Queue_scopes"/>. Use an <literal>&lt;a4j:attachQueue&gt;</literal> behavior in the same scope as a queue to override the queue settings for a particular control.</simpara>
<example id="exam-Component_Reference-a4jattachQueue-Overriding_scope_settings">
  <title>Overriding scope settings</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:queue requestDelay="2000"/&gt;
&lt;h:form&gt;
   &lt;rich:panel&gt;
      &lt;h:inputText&gt;
         &lt;a4j:ajax event="keyup" /&gt;
      &lt;/h:inputText&gt;
      &lt;a4j:commandButton value="submit"&gt;
         &lt;a4j:attachQueue requestDelay="0" /&gt;
      &lt;/a4j:commandButton&gt;
   &lt;/rich:panel&gt;
&lt;/h:form&gt;
</programlisting>


<simpara>The request delay is overridden by the <literal>&lt;a4j:attachQueue&gt;</literal> behavior on the submit button.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jattachQueue-Using_a_named_queue">
  <title>Using a named queue</title>
  <simpara>Name an <literal>&lt;a4j:queue&gt;</literal> component using the <literal>name</literal> attribute. It can then be used by specific components through the <literal>&lt;a4j:attachQueue&gt;</literal> behavior. Use the <literal>name</literal> attribute of the <literal>&lt;a4j:attachQueue&gt;</literal> behavior to identify the name of the destination queue.</simpara>
<example id="exam-Component_Reference-a4jattachQueue-Using_a_named_queue">
  <title>Using a named queue</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:queue name="viewQueue"/&gt;
&lt;h:form&gt;
	&lt;a4j:queue name="formQueue"/&gt;
   &lt;rich:panel&gt;
      &lt;a4j:commandButton value="submit"&gt;
         &lt;a4j:attachQueue name="viewQueue" /&gt;
      &lt;/a4j:commandButton&gt;
   &lt;/rich:panel&gt;
&lt;/h:form&gt;
</programlisting>


<simpara>The requests from the button are attached to the <literal>viewQueue</literal> queue, rather than the <literal>formQueue</literal> queue.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jattachQueue-Grouping_requests">
  <title>Grouping requests</title>
  <simpara>Use grouping to process multiple requests together. Specify a grouping identifier with the <literal>requestGroupingId</literal> attribute. Requests from multiple <literal>&lt;a4j:attachQueue&gt;</literal> behaviors can use the same identifier to group requests together.</simpara>
<example id="exam-Component_Reference-a4jattachQueue-Grouping_requests">
  <title>Grouping requests</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form&gt;
   &lt;a4j:queue requestDelay="2000"/&gt;
   &lt;h:inputText id="input1" value="#{queueBean.text1}"&gt;
      &lt;a4j:attachQueue requestGroupingId="registrationForm"/&gt;
   &lt;/h:inputText&gt;
   &lt;h:inputText id="input2" value="#{queueBean.text2}"&gt;
      &lt;a4j:attachQueue requestGroupingId="registrationForm"/&gt;
   &lt;/h:inputText&gt;
&lt;/h:form&gt;
</programlisting>


<simpara>Requests from both the text input boxes are grouped together with the <literal>registrationForm</literal> identifier.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jattachQueue-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.AttachQueue</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIAttachQueue</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.AttachQueue</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.AttachQueueRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.AttachQueueHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</section>
<section id="sect-Component_Reference-Processing_management-a4jlog">
  <title><literal>&lt;a4j:log&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:log&gt;</literal> component generates JavaScript that opens a debug window, logging application information such as requests, responses, and DOMchanges.</simpara>
<section id="sect-Component_Reference-a4jlog-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;a4j:log&gt;</literal> component doesn&#8217;t require any additional attributes for basic functionality.</simpara>

</section>
<section id="sect-Component_Reference-a4jlog-Log_monitoring">
  <title>Log monitoring</title>
  <simpara>The <literal>mode</literal> attribute determines how the log appears on the page.</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>Set <literal>mode="inline"</literal> to place the logging data in-line on the current page. This is the default setting.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Set <literal>mode="popup"</literal> to present the logging data in a new pop-up window. The window is set to be opened by pressing the key combination CtrlShiftL; this can be partially reconfigured with the <literal>hotkey</literal> attribute, which specifies the letter key to use in combination with CtrlShiftinstead of L.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>The amount of data logged can be determined with the <literal>level</literal> attribute:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>Set <literal>level="ERROR"</literal> to log all errors.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Set <literal>level="FATAL"</literal> to log only fatal messages.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Set <literal>level="INFO"</literal> to log only informational messages.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Set <literal>level="WARN"</literal> to log only warning messages.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Set <literal>level="ALL"</literal> to log all data. This is the default setting.</simpara>
      
    </listitem>
  
</itemizedlist>

<example id="exam-Component_Reference-a4jlog-a4jlog_example">
  <title><literal>&lt;a4j:log&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:log level="ALL" mode="inline" /&gt;
</programlisting>


<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-a4jlog-a4jlog_example.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-a4jlog-a4jlog_example</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>The log readout displays all messages.</simpara>

</example>
<note>
  <title>Log renewal</title>
  
<simpara>The log is automatically renewed after each Ajax request. It does not need to be explicitly re-rendered. To clear previous requests, implement a Clearbutton or similar functionality.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-a4jlog-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.AjaxLog</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIAjaxLog</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.AjaxLog</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.AjaxLogRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-a4jlog-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <simpara>The <literal>&lt;a4j:log&gt;</literal> component is intended primarily for debugging during development. However it is still possible to style the component if desired.</simpara>
<table id="tabl-a4jlog-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log</literal>:: This class defines styles for the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-popup</literal>:: This class defines styles for the log when it appears as a pop-up.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-popup-cnt</literal>:: This class defines styles for the content of the log pop-up.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-inline</literal>:: This class defines styles for the log when it appears in-line.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-contents</literal>:: This class defines styles for the log contents.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-lbl</literal>:: This class defines styles for a label in the log.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-lbl-debug</literal>:: This class defines styles for the debuglabel in the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-lbl-info</literal>:: This class defines styles for the informationlabel in the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-lbl-warn</literal>:: This class defines styles for the warninglabel in the log.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-lbl-error</literal>:: This class defines styles for the errorlabel in the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-msg</literal>:: This class defines styles for a message in the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-msg-debug</literal>:: This class defines styles for the debugmessage in the log.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-msg-info</literal>:: This class defines styles for the informationmessage in the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-msg-warn</literal>:: This class defines styles for the warningmessage in the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-msg-error</literal>:: This class defines styles for the errormessage in the log.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-log-entry-msg-xml</literal>:: This class defines styles for an XML message in the log.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Processing_management-a4jstatus">
  <title><literal>&lt;a4j:status&gt;</literal></title>
  <simpara>The <literal>&lt;a4j:status&gt;</literal> component displays the status of current Ajax requests. The status can be either in progress, complete, or an error is shown after a failed request.</simpara>
<section id="sect-Component_Reference-a4jstatus-Customizing_the_text">
  <title>Customizing the text</title>
  <simpara>The text display can be customized depending on the current status.</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>startText</literal> attribute defines the text shown after the request has been started and is currently in progress. Set the styles for the text with the <literal>startStyle</literal> and <literal>startStyleClass</literal> attributes. Alternatively, use the <literal>start</literal> facet to customize the text appearance.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>stopText</literal> attribute defines the text shown once the request is complete. Set the styles for the text with the <literal>stopStyle</literal> and <literal>stopStyleClass</literal> attributes. Alternatively, use the <literal>stop</literal> facet to customize the text appearance.
If the <literal>stopText</literal> attribute is not defined, and no facet exists for the stopped state, the complete status is simply not shown. In this way, only the progress of the request is displayed to the user, along with any errors.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>errorText</literal> attribute defines the text shown when an error has occurred. Set the styles for the text with the <literal>errorStyle</literal> and <literal>errorStyleClass</literal> attributes. Alternatively, use the <literal>error</literal> facet to customize the text appearance.</simpara>
      
    </listitem>
  
</itemizedlist>

<example id="exam-Component_Reference-a4jstatus-Basic_a4jstatus_usage">
  <title>Basic <literal>&lt;a4j:status&gt;</literal> usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;a4j:status startText="In progress..." stopText="Complete" /&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-a4jstatus-Specifying_a_region">
  <title>Specifying a region</title>
  <simpara>The <literal>&lt;a4j:status&gt;</literal> component monitors the status of the region relevant to where it is placed.</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>If unnamed and placed outside any forms, it monitors the status at the view level.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>If unnamed and placed inside a form, it monitors the status at the form level.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>However, if identified with the <literal>name</literal> attribute, the <literal>&lt;a4j:status&gt;</literal> component can monitor any Ajax component or behavior. Use the <literal>status</literal> attribute on the Ajax component or behavior to reference the <literal>name</literal> identifier of the <literal>&lt;a4j:status&gt;</literal> component.</simpara>
<example id="exam-Component_Reference-a4jstatus-Updating_a_referenced_a4jstatus_component">
  <title>Updating a referenced <literal>&lt;a4j:status&gt;</literal> component</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel&gt;
   &lt;f:facet name="header"&gt;
      &lt;h:outputText value="User Details Panel" /&gt;
   &lt;/f:facet&gt;
   &lt;h:panelGrid columns="3"&gt;
      &lt;h:outputText value="User name:" /&gt;
      &lt;h:inputText value="#{userBean.name}"&gt;
         &lt;a4j:ajax status="nameStatus" event="keyup" /&gt;
      &lt;/h:inputText&gt;
      &lt;a4j:status name="nameStatus"&gt;
         &lt;f:facet name="start"&gt;
            &lt;h:graphicImage value="/images/ai.gif" /&gt;
         &lt;/f:facet&gt;
      &lt;/a4j:status&gt;
      &lt;h:outputText value="Address:" /&gt;
      &lt;h:inputText value="#{userBean.address}"&gt;
         &lt;a4j:ajax status="addressStatus" event="keyup" /&gt;
      &lt;/h:inputText&gt;
      &lt;a4j:status name="addressStatus"&gt;
         &lt;f:facet name="start"&gt;
            &lt;h:graphicImage value="/images/ai.gif" /&gt;
         &lt;/f:facet&gt;
      &lt;/a4j:status&gt;
   &lt;/h:panelGrid&gt;
&lt;/rich:panel&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-a4jstatus-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;a4j:status&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>start()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switches status to the <literal>start</literal> state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>stop()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switches status to the <literal>stop</literal> state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>error()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switches status to the <literal>error</literal> state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-a4jstatus-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Status</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIStatus</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Status</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.StatusRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</chapter>

</chapter>
<chapter id="part-Component_Reference-User_interface_components">
  <title>User interface components</title>
  <chapter id="chap-Component_Reference-Rich_inputs">
  <title>Rich inputs</title>
  <simpara>This chapter details rich components for user input and interaction.</simpara>
<section id="sect-Component_Reference-Rich_inputs-richautocomplete">
  <title><literal>&lt;rich:autocomplete&gt;</literal></title>
  <simpara>The <literal>&lt;rich:autocomplete&gt;</literal> component is an auto-completing input-box with built-in Ajax capabilities. It supports client-side suggestions, browser-like selection, and customization of the look and feel.</simpara>
<simpara>The auto-complete box is a standard JSF <literal>UIInput</literal> control with added validation.</simpara>
<figure id="figu-Component_Reference-richautocomplete-richautocomplete">
  <title><literal>&lt;rich:autocomplete&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richautocomplete-richautocomplete.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richautocomplete-richautocomplete</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richautocomplete-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>value</literal> attribute stores the text entered by the user for the auto-complete box. Suggestions shown in the auto-complete list can be specified using one of two different methods:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>autocompleteMethod</literal> attribute points to a method which returns a list of suggestions according to a supplied prefix.</simpara>
      
<note>
  
  
  <simpara>.<literal>client</literal> and <literal>lazyClient</literal> modes</simpara>
  
</note>

      
    </listitem>
  
</itemizedlist>

<example>
  
<simpara>The prefix is normally ignored in <literal>client</literal> and <literal>lazyClient</literal> modes. In these modes, the component requests the suggestion list once only, and performs filtering on the client.</simpara>

</example>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>autocompleteList</literal> attribute points to a collection of suggestions.</simpara>
      
    </listitem>
  
</itemizedlist>

<example id="exam-Component_Reference-richautocomplete-Defining_suggestion_values">
  <title>Defining suggestion values</title>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using the <literal>autocompleteMethod</literal>  attribute
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:autocomplete value="#{bean.state}" autocompleteMethod="#{bean.autocomplete}" /&gt;
</programlisting>


<simpara>The <literal>&lt;rich:autocomplete&gt;</literal> component uses the bean.autocompletemethod to provide suggestions, based on the entered prefix.
Using the <literal>autocompleteList</literal>  attribute::</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:autocomplete value="#{bean.state}" autocompleteList="#{bean.suggestions}" /&gt;
</programlisting>


<simpara>The <literal>&lt;rich:autocomplete&gt;</literal> component retrieve the suggestion list from bean.suggestions.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richautocomplete-Submission_modes">
  <title>Submission modes</title>
  <simpara>Use the <literal>mode</literal> attribute to determine how the suggestion list is requested:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>client</literal> setting pre-loads data to the client and uses the input to filter the possible suggestions.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>ajax</literal> setting fetches suggestions with every input change using Ajax requests.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>lazyClient</literal> setting pre-loads data to the client and uses the input to filter the possible suggestions. The filtering does not start until the input length matches a minimum value. Set the minimum value with the <literal>minChars</literal> attribute.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>cachedAjax</literal> setting pre-loads data via Ajax requests when the input length matches a minimum value. Set the minimum value with the <literal>minChars</literal> attribute. All suggestions are handled on the client until the input prefix is changed, at which point a new request is made based on the new input prefix.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richautocomplete-Interactivity_options">
  <title>Interactivity options</title>
  <simpara>Users can type into the text field to enter a value, which also searches through the suggestion items in the drop-down box. By default, the first suggestion item is selected as the user types. This behavior can be deactivated by setting <literal>selectFirst="false"</literal>.</simpara>
<simpara>Setting <literal>autoFill="true"</literal> causes the combo-box to fill the text field box with a matching suggestion as the user types.</simpara>
<simpara>To allow users to enter multiple values separated by specific characters, use the <literal>tokens</literal> attribute. As the user types, a suggestion will present as normal. When they enter a character specified as a token, this begins a new suggestion process, and the component only uses text entered after the token character for suggestions. For example, if <literal>tokens=", "</literal> is set, the <literal>&lt;rich:autocomplete&gt;</literal> component uses both the comma and space characters as tokens to separate entries. When the user enters a comma or a space, a new suggestion process begins.</simpara>
<note>
  <title>Using tokens</title>
  
<simpara>When declaring tokens, avoid using any characters that are present in the list of suggestions. This may cause unexpected behavior as the user expects the character to match suggestions instead of separating suggested entries.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-richautocomplete-Customizing_the_filter_in_client_and_lazyClient_modes">
  <title>Customizing the filter in <literal>client</literal> and <literal>lazyClient</literal> modes</title>
  <simpara>The <literal>&lt;rich:autocomplete&gt;</literal> component uses the JavaScript <literal>startsWith()</literal> method to create the list of suggestions. The filtering is performed on the client side. Alternatively, use the <literal>clientFilterFunction</literal> attribute to specify a custom filtering function. The custom function must accept two parameters: the <literal>subString</literal> parameter is the filtering value as typed into the text box by the user, and the <literal>value</literal> parameter is an item in the list of suggestions against which the <literal>subString</literal> must be checked. Each item is iterated through and passed to the function as the <literal>value</literal> parameter. The custom function must return a boolean value indicating whether the passed item meets the conditions of the filter, and the suggestion list is constructed from successful items.</simpara>
<example id="exam-Component_Reference-richautocomplete-Customizing_the_filter">
  <title>Customizing the filter</title>
<simpara>This example demonstrates how to use a custom filter with the <literal>clientFilterFunction</literal> attribute. The custom filter determines if the sub-string is contained anywhere in the suggestion item, instead of just at the start.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;script&gt;
   function customFilter(subString, value){
      if(subString.length&gt;=1) {
         if(value.indexOf(subString)!=-1)
            return true;
      }else return false;
   };
&lt;/script&gt;
&lt;h:form&gt;
   &lt;rich:autocomplete mode="client" minChars="0" autofill="false"
                      clientFilterFunction="customFilter"
                      autocompleteMethod="#{autocompleteBean.autocomplete}" /&gt;
&lt;/h:form&gt;</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richautocomplete-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:autocomplete&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the current value of the text field.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the value of the text field to the <literal>newValue</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>showPopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the pop-up list of completion values.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hidePopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the pop-up list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richautocomplete-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Autocomplete</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIAutocomplete</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Input</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.AutocompleteRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.AutocompleteHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richautocomplete-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richautocomplete-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-fnt</literal>:: This class defines styles for the auto-complete box font.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-inp</literal>:: This class defines styles for the auto-complete input box.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>controlBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-fld</literal>:: This class defines styles for the auto-complete field.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>controlBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-fld-btn</literal>:: This class defines styles for a button in the auto-complete field.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-btn</literal>:: This class defines styles for the auto-complete box button.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-left-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-btn-arrow</literal>:: This class defines styles for the button arrow.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-btn-arrow-dis</literal>:: This class defines styles for the button arrow when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-lst-scrl</literal>:: This class defines styles for the scrollbar in the auto-complete list.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-itm</literal>:: This class defines styles for an item in the auto-complete list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-itm-sel</literal>:: This class defines styles for a selected item in the auto-complete list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-shdw</literal>:: This class defines styles for the auto-complete box shadow.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-au-shdw-t</literal>:: <literal>.rf-au-shdw-l</literal>:: <literal>.rf-au-shdw-r</literal>:: <literal>.rf-au-shdw-b</literal>:: These classes define styles for the top, left, right, and bottom part of the auto-complete box shadow.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richcalendar">
  <title><literal>&lt;rich:calendar&gt;</literal></title>
  <simpara>The <literal>&lt;rich:calendar&gt;</literal> component allows the user to enter a date and time through an in-line or pop-up calendar. The pop-up calendar can navigate through months and years, and its look and feel can be highly customized.</simpara>
<figure id="figu-Component_Reference-richcalendar-richcalendar">
  <title><literal>&lt;rich:calendar&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richcalendar-richcalendar.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richcalendar-richcalendar</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richcalendar-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage of the <literal>&lt;rich:calendar&gt;</literal> component requires only the <literal>value</literal> attribute, which holds the currently selected date. <xref linkend="exam-Component_Reference-richcalendar-Basic_usage"/> shows a basic declaration, with the value pointing to a bean property. The bean property holds the selected date.</simpara>
<example id="exam-Component_Reference-richcalendar-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:calendar value="#{bean.dateTest}" /&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richcalendar-Behavior_and_appearance">
  <title>Behavior and appearance</title>
  <simpara>The <literal>&lt;rich:calendar&gt;</literal> component is presented as a pop-up by default, appearing as a text field with a button to expand the full pop-up calendar. To render the calendar in-line on the page instead, set <literal>popup="false</literal>. This displays the full calendar without the text field and display button.</simpara>
<simpara>To add keyboard support for manual input, set <literal>enableManualInput="true"</literal>. To disable the calendar from any user input, set <literal>disabled="true"</literal>.</simpara>
<simpara>To change the appearance of the display button from the standard calendar icon, use the <literal>buttonIcon</literal> and <literal>buttonDisabledIcon</literal> attributes to replace the icon with a specified file. Alternatively, use the <literal>buttonLabel</literal> attribute to display text on the button without an icon. If <literal>buttonLabel</literal> is specified then both the <literal>buttonIcon</literal> and <literal>buttonDisabledIcon</literal> attributes are ignored. To hide the text field box, set <literal>showInput="false"</literal>.</simpara>
<simpara>The calendar features a Todaybutton for locating today&#8217;s date on the calendar. This can be set to three different values using the <literal>todayControlMode</literal> attribute:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>hidden</literal>, which does not display the button;</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>select</literal>, the default setting, which scrolls the calendar to the current month and selects the date; and</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>scroll</literal>, which scrolls the calendar to the month but does not select the date.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>inactive</literal>, which displays the date but performs no action when clicked.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>To make the entire calendar read-only, set <literal>readonly="true"</literal>. This allows months and years to be browsed through with the arrow controls, but dates and times cannot be selected.</simpara>

</section>
<section id="sect-Component_Reference-richcalendar-Time_of_day">
  <title>Time of day</title>
  <simpara>The <literal>&lt;rich:calendar&gt;</literal> component can additionally allow a time of day to be specified with the date. After selecting a date the option to set a time becomes available. The default time can be set with the <literal>defaultTime</literal> attribute. If the time is altered and a new date is selected, it will not reset unless <literal>resetTimeOnDateSelect="true"</literal> is specified.</simpara>
<simpara>The date selection feature is activated if the time is present in the <literal>datePattern</literal> attribute for the calendar.</simpara>
<note>
  <title>Support for seconds</title>
  
<simpara>In RichFaces 4, the <literal>&lt;rich:calendar&gt;</literal> component supports times that include seconds. Previous versions of RichFaces only supported hours and minutes.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-richcalendar-Localization_and_formatting">
  <title>Localization and formatting</title>
  <simpara>Date and time strings can be formatted in a set pattern. Use standard locale formatting strings specified by ISO 8601(for example, <literal>d/M/yy HH:mm a</literal>) with the <literal>datePattern</literal> attribute to format date and time strings.</simpara>
<simpara>To set the locale of the calendar, use the <literal>locale</literal> attribute. The calendar will render month and day names in the relevant language. For example, to set the calendar to the US locale, specify <literal>locale="en/US"</literal>.</simpara>
<simpara>Use an application resource bundle to localize the calendar control labels. Define the following strings in the resource bundle:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The RICH_CALENDAR_APPLY_LABELstring is the label for the Applybutton.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The RICH_CALENDAR_TODAY_LABELstring is the label for the Todaybutton.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The RICH_CALENDAR_CLOSE_LABELstring is the label for the Closebutton.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The RICH_CALENDAR_OK_LABELstring is the label for the OKbutton.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The RICH_CALENDAR_CLEAN_LABELstring is the label for the Cleanbutton.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The RICH_CALENDAR_CANCEL_LABELstring is the label for the Cancelbutton.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Alternatively, use the <literal>org.richfaces.calendar</literal> resource bundle with Java Archive files ( JARs) defining the same properties.</simpara>

</section>
<section id="sect-Component_Reference-richcalendar-Using_a_data_model">
  <title>Using a data model</title>
  <simpara>The look and feel of the <literal>&lt;rich:calendar&gt;</literal> component can be customized through the use of a data model on the server side. The component supports two different ways of loading data from the server side through defining the <literal>mode</literal> attribute.</simpara>
<simpara>When the <literal>mode</literal> attribute is not specified, the component uses the <literal>client</literal> mode. The <literal>client</literal> mode loads an initial portion of data within a set date range. The range can be defined by using the <literal>preloadDateRangeBegin</literal> and <literal>preloadDateRangeEnd</literal> attributes. Additional data requests for months outside the range are not sent.</simpara>
<simpara>Alternatively, with <literal>mode="ajax"</literal> the <literal>&lt;rich:calendar&gt;</literal> requests portions of data from the data model every time the month is switched. The data model can be defined through the <literal>dataModel</literal> attribute, which points to an object that implements the <literal>CalendarDataModel</literal> interface. If the <literal>dataModel</literal> attribute is not defined or has a value of <literal>null</literal>, the <literal>ajax</literal> mode functions the same as the <literal>client</literal> mode.</simpara>

</section>
<section id="sect-Component_Reference-richcalendar-Client-side_customization">
  <title>Client-side customization</title>
  <simpara>Instead of using a data model, the <literal>&lt;rich:calendar&gt;</literal> component can be customized on the client-side using JavaScript. Use the <literal>dayClassFunction</literal> attribute to reference the function that determines the CSS style class for each day cell. Use the <literal>dayDisableFunction</literal> to reference the function that enables or disables a day cell. <xref linkend="exam-Component_Reference-richcalendar-Client-side_customization"/> demonstrates how client-side customization can be used to style different days in a calendar.</simpara>
<example id="exam-Component_Reference-richcalendar-Client-side_customization">
  <title>Client-side customization</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;style&gt;
   .everyThirdDay {
      background-color: gray;
   }
   .weekendBold {
      font-weight: bold;
      font-style: italic;
   }
&lt;/style&gt;
&lt;script type="text/javascript"&gt;
   var curDt = new Date();
   function disablementFunction(day){
      if (day.isWeekend) return false;
      if (curDt==undefined){
         curDt = day.date.getDate();
      }
      if (curDt.getTime() - day.date.getTime() &amp;lt; 0) return true;
      else return false;
   }
   function disabledClassesProv(day){
      if (curDt.getTime() - day.date.getTime() &amp;gt;= 0) return 'rf-ca-boundary-dates';
      var res = '';
      if (day.isWeekend) res+='weekendBold ';
      if (day.day%3==0) res+='everyThirdDay';
      return res;
   }
&lt;/script&gt;
&lt;rich:calendar dayDisableFunction="disablementFunction"
               dayClassFunction="disabledClassesProv"
               boundaryDatesMode="scroll" /&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richcalendar-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:calendar&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>showPopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Expand the pop-up calendar element.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hidePopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Collapse the pop-up calendar element.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>switchPopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Invert the state of the pop-up calendar element.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the selected date value of the calendar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getValueAsString()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the selected date value of the calendar as a formatted string.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the selected date value to the <literal>newValue</literal> date passed as a parameter. If the new date is not in the currently displayed month, a request is performed to display the correct month.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>resetValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Clear the selected date value.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>today()</literal>
    </term>
    
    <listitem>
      
      <simpara>Select today&#8217;s date.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getCurrentMonth()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the number of the month currently being displayed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getCurrentYear()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the number of the year currently being displayed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>showSelectedDate()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the calendar month that contains the currently selected date.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>showDateEditor()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the date editor pop-up.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hideDateEditor()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the date editor pop-up.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>showTimeEditor()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the time editor pop-up.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hideTimeEditor()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the time editor pop-up.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richcalendar-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Calendar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UICalendar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Calendar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.CalendarRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.CalendarHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richcalendar-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richcalendar-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-extr</literal>:: This class defines the styles for a pop-up calendar exterior.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-btn</literal>:: This class defines styles for a calendar button.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-hdr</literal>:: This class defines the styles for a calendar header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-hdr-optnl</literal>:: This class defines the styles for an optional header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-hdr-month</literal>:: This class defines the styles for the month header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-ftr</literal>:: This class defines the styles for a calendar footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-ftr-optnl</literal>:: This class defines the styles for an optional footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-tl</literal>:: This class defines the styles for calendar toolbars.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-tl-ftr</literal>:: This class defines the styles for a toolbar item in the calendar footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-tl-btn</literal>:: This class defines styles for a toolbar button.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-tl-btn-dis</literal>:: This class defines styles for a disabled toolbar button.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-tl-btn-hov</literal>:: This class defines the styles for toolbar items when it is hovered over with the mouse cursor.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>calendarWeekBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-tl-btn-press</literal>:: This class defines the styles for toolbar items when it is pressed.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-tl-close</literal>:: This class defines styles for a Closebutton in a toolbar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-c</literal>:: This class defines the styles for regular calendar cells.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-c-cnt</literal>:: This class defines styles for the content of a cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-today</literal>:: This class defines the styles for the cell representing today&#8217;s date.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>calendarCurrentBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarCurrentTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-sel</literal>:: This class defines the styles for the selected day.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-hov</literal>:: This class defines the styles for a cell when it is hovered over with the mouse cursor.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarSpecBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>calendarSpecTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-week</literal>:: This class defines the styles for week numbers.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarWeekBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-holiday</literal>:: This class defines the styles for weekends and holidays.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>calendarHolidaysBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarHolidaysTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-boundary-day</literal>:: This class defines styles for an active boundary button.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-sp-inp</literal>:: This class defines the styles for a spinner input field in the pop-up element for time selection.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>buttonSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>buttonFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-sp-inp-cntr</literal>:: This class defines the styles for a wrapper <literal>&lt;td&gt;</literal> element for a spinner input field in the pop-up element for time selection.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>controlBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>subBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-sp-btn</literal>:: This class defines the styles for a wrapper <literal>&lt;td&gt;</literal> element for spinner buttons in the pop-up element for time selection.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color, border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-sp-up</literal>:: This class defines styles for the Upspinner button.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-sp-down</literal>:: This class defines styles for the Downspinner button.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-sp-press</literal>:: This class defines styles for a spinner button when it is pressed.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-edtr-shdw</literal>:: This class defines the styles for the calendar editor shadow.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-edtr-layout-shdw</literal>:: This class defines the styles for the layout shadow of a calendar editor.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>shadowBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-edtr-btn</literal>:: This class defines styles for a button in the calendar editor.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-edtr-btn-over</literal>:: This class defines the styles for the calendar editor button when it is hovered over with the mouse cursor.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarSpecBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-edtr-btn-sel</literal>:: This class defines the styles for the calendar editor button when it is selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarCurrentBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarCurrentTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-edtr-tl-over</literal>:: This class defines the styles for a toolbar item in the calendar editor when it is hovered over with the mouse cursor.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-edtr-tl-press</literal>:: This class defines the styles for a toolbar item in the calendar editor when it is pressed.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-time-inp</literal>:: This class defines styles for the time input field.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-time-btn</literal>:: This class defines the styles for a button in the pop-up element for the calendar&#8217;s time section.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-time-btn-press</literal>:: This class defines the styles for a pressed button in the pop-up element for the calendar&#8217;s time section.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right-color, border-bottom-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>calendarWeekBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-timepicker-cnt</literal>:: This class defines the styles for the content of the pop-up element during time selection.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-timepicker-inp</literal>:: This class defines the styles for an input field in the time picker.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-timepicker-ok</literal>:: This class defines styles for the OKbutton in the time picker.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-timepicker-cancel</literal>:: This class defines styles for the Cancelbutton in the time picker.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-monthpicker-cnt</literal>:: This class defines the styles for the content of the pop-up element during month or year selection.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-monthpicker-ok</literal>:: This class defines the styles for the OKbutton for the month picker.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-top-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-monthpicker-cancel</literal>:: This class defines the styles for the Cancelbutton for the month picker.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-top-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cal-monthpicker-split</literal>:: This class defines the styles for the splitter in the month picker.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richeditor">
  <title><literal>&lt;rich:editor&gt;</literal></title>
  <simpara>The <literal>&lt;rich:editor&gt;</literal> component is used for creating a WYSIWYG editor on a page.</simpara>
<figure id="figu-Component_Reference-richeditor-richeditor">
  <title><literal>&lt;rich:editor&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richeditor-richeditor.png" contentwidth="400"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richeditor-richeditor</phrase></textobject>
  </mediaobject>
</figure>
<simpara><literal>&lt;rich:editor&gt;</literal> component is based on the CKEditor implementation.</simpara>
<simpara>When rendering a <literal>&lt;rich:editor&gt;</literal>, a textarea is rendered to the page and once the page is completely loaded (ready state), the textarea is enhanced using a CKEditor script and replaced with a full-featured WYSIWYG editor.</simpara>
<section id="sect-Component_Reference-richeditor-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage requires the <literal>value</literal> attribute to point to the expression for the current value of the component.</simpara>
<example>
  <title>Basic usage of <literal>&lt;rich:editor&gt;</literal></title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:editor value="#{backingBean.editedValue}" /&gt;

&lt;h:outputText escape="false" value="#{backingBean.editedValue}" /&gt;</programlisting>


<simpara>Note that the editor produces HTML markup and to be able to render it&#8217;s output, the markup needs to be unescaped (as with <literal>&lt;h:outputText&gt;</literal> component in example above).</simpara>

</example>
<simpara>The dimensions of the editor can be managed using <literal>width</literal> and <literal>height</literal> attributes.</simpara>
<simpara>The <literal>readonly</literal> attribute can be used to switch the editor into a read-only mode.</simpara>
<simpara>The <literal>tabindex</literal> attribute specifies the position of the current element in the tabbing order for the current document.</simpara>
<note>
  
  

<literallayout class="monospaced">The +ResourceServlet+  has to be registered for the +url-pattern++/org.richfaces.resources/\*+  in order to serve the editor resources (JavaScript, CSS, images) correctly. Check the _RichFaces Developer's Guide_  for further details.</literallayout>


  
</note>
<note>
  
  

<literallayout class="monospaced">The +&lt;rich:editor&gt;+  requires the +&lt;h:body&gt;+  component to be present in the view and must be an ancestor of the editor in order for the resource dependencies to render correctly.</literallayout>


  
</note>

</section>
<section id="sect-Component_Reference-richeditor-Styling">
  <title>Styling</title>
  <simpara>There are several options to customize the style of the editor:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>style, styleClass</literal>: customizes the style of the editor and underlying textarea</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>editorStyle, editorClass</literal>: customizes the style of the CKEditor instance</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>textareaStyle, textareaClass</literal>: customizes the style of the underlying textarea</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richeditor-Editor_skins">
  <title>Editor skins</title>
  <simpara>The <literal>&lt;rich:editor&gt;</literal> is skinnable using the <literal>skin</literal> attribute and either of the two approaches:</simpara>
<simpara>By default, <literal>&lt;rich:editor&gt;</literal> has a skin called <literal>richfaces</literal> that is optimized to match rest of the component suite look &amp; feel and changes to match the active RichFaces skin (refer to <emphasis>RichFaces Developer&#8217;s Guide</emphasis> for details about <emphasis>Skinning and theming</emphasis>).</simpara>
<example>
  <title>The skin <literal>richfaces</literal> of <literal>&lt;rich:editor&gt;</literal></title>
<simpara>.
<inlinemediaobject>
  <imageobject>
    <imagedata fileref=":images/figu-Component_Reference-richeditor-richfaces_skin.png" width="400"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richeditor-richfaces_skin</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A <literal>&lt;rich:editor&gt;</literal> with the default <literal>richfaces</literal> editor skin rendered against several RichFaces Skin options.</simpara>

</example>
<simpara>Alternatively, you can use any other CKeditor skin, either from the standard distribution, a downloaded skin, or a custom skin. In the distribution, there are three skins bundled: <literal>kama, v2, office2003</literal>.</simpara>
<example>
  <title>Examples of <literal>&lt;rich:editor&gt;</literal> skins in CKEditor distribution</title>
<simpara>.
<inlinemediaobject>
  <imageobject>
    <imagedata fileref=":images/figu-Component_Reference-richeditor-distribution_skins.png" width="400"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richeditor-distribution_skins</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A CKEditor distribution skins <literal>kama</literal>, <literal>v2</literal> and <literal>office2003</literal>.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richeditor-Advanced_configuration">
  <title>Advanced configuration</title>
  <simpara>The basic set of <literal>&lt;rich:editor&gt;</literal> attributes allows you to support common use-cases for a WYSIWYG editor. However the underlying CKEditor implementation supports many more configuration options.</simpara>
<simpara>Use the <literal>config</literal> attribute to define any of these advanced configuration options supported by the CKEditor. This configuration is written in JavaScript object format and its value is interpolated for EL expressions (making configuration dynamic).</simpara>
<simpara>There are two ways to define the configuration: the <literal>config</literal> attribute or a facet named <literal>config</literal>. The facet takes precedence over attribute when both are defined.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:editor config="startupFocus: #{userPreferences.startupFocus}" /&gt;

&lt;rich:editor&gt;
    &lt;f:facet name="config"&gt;
        startupFocus: #{userPreferences.startupFocus}
    &lt;/f:facet&gt;
&lt;/rich:editor&gt;</programlisting>


<simpara>In the above samples, the <literal>&lt;rich:editor&gt;</literal> is configured to take focus after loading the page as defined by the userPreference bean. Definitions using either attribute or facet are equivalent.</simpara>
<note>
  
  

<literallayout class="monospaced">For further configuration options, refer to link:$$http://docs.cksource.com/CKEditor_3.x/Developers_Guide/Setting_Configurations$$[CKEditor 3 Developer Guide]  and link:$$http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html$$[CKEditor 3 configuration reference].</literallayout>


  
</note>

</section>
<section id="sect-Component_Reference-richeditor-Toolbar_customization">
  <title>Toolbar customization</title>
  <simpara>The <literal>&lt;rich:editor&gt;</literal> supports a <literal>toolbar</literal> attribute, which is able to change the configuration of the toolbar&#8217;s button set. There are two configurations available: <literal>basic</literal> (default), <literal>full</literal> (enables all of the features).</simpara>
<simpara>It is also possible to define a custom toolbar using the CKEditor toolbar configuration in a <literal>config</literal> facet:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:editor toolbar="CustomToolbar"&gt;
    &lt;f:facet name="config"&gt;
        toolbar_CustomToolbar:
        [
        { name: 'document', items : [ 'NewPage','Preview' ] },
        { name: 'clipboard', items : [ 'Cut','Copy','Paste','-','Undo','Redo' ] },
        { name: 'editing', items : [ 'Find','Replace','-','SelectAll','-','Scayt' ] },
        { name: 'insert', items : [ 'Image', 'Flash', 'Table', 'HorizontalRule',
                 'Smiley', 'SpecialChar', 'PageBreak', 'Iframe' ] },
                '/',
        { name: 'styles', items : [ 'Styles','Format' ] },
        { name: 'basicstyles', items : [ 'Bold','Italic','Strike','-','RemoveFormat' ] },
        { name: 'paragraph', items : [ 'NumberedList','BulletedList','-','Outdent','Indent','-','Blockquote' ] },
        { name: 'links', items : [ 'Link','Unlink','Anchor' ] },
        { name: 'tools', items : [ 'Maximize' ] }
        ]
        &lt;/f:facet&gt;
&lt;/rich:editor&gt;</programlisting>


<simpara>Note that toolbar name ( <literal>CustomToolbar</literal>) needs to match the <literal>toolbar_&lt;name&gt;</literal> configuration option.</simpara>

</section>
<section id="sect-Component_Reference-richeditor-Internationalization_and_localization">
  <title>Internationalization and localization</title>
  <simpara>The <literal>&lt;rich:editor&gt;</literal> comes with a <literal>lang</literal> attribute which allows you to change the localization of the editor. For language configuration options, refer to link:http://www.w3.org/TR/html4/struct/dirlang.html.</simpara>
<simpara>The <literal>lang</literal> attribute influences following settings:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><emphasis>underlying textarea</emphasis> - specifies the i18n settings for received and submitted content</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><emphasis>editor value</emphasis> - specifies the i18n settings for value edited in WYSIWYG mode</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><emphasis>default settings of localization</emphasis> of editor controls and interface</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>However the interface first localized using the browser configuration (usually determined by client system settings). To force the editor to use a specific localization for the interface, you use the advanced CKEditor configuration option <literal>language</literal>, as in following sample:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:editor lang="fr" config="language: 'fr'" /&gt;</programlisting>


<simpara>The above sample forces the editor to use a french interface, suppressing the browser preferred settings.</simpara>

</section>
<section id="sect-Component_Reference-richeditor-Client_side_event_handlers">
  <title>Client-side event handlers</title>
  <simpara>The <literal>&lt;rich:editor&gt;</literal> component produces set of events for handling component specific interaction.</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>init</literal> - once the editor is initialized and ready to be handle user interaction</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>focus</literal> - once the editor is focused</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>blur</literal> - once the editor is blurred</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>change</literal> - fired on blur event when editor content has been changed after previous focus</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>dirty</literal> - fired immediately after editor content has been changed</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Events can be handled either by registering a JavaScript event handler or by attaching JSF behavior:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:editor value="#{backingBean.editorValue}"&gt;
    &lt;a4j:ajax event="change" render="editorOutput" /&gt;
    &lt;a4j:ajax event="dirty" render="editorOutput"&gt;
        &lt;a4j:attachQueue requestDelay="1000" /&gt;
    &lt;/a4j:ajax&gt;
&lt;/rich:editor&gt;

&lt;a4j:outputPanel id="editorOutput"&gt;
    &lt;h:outputText escape="false" value="#{backingBean.editorValue}" /&gt;
&lt;/a4j:outputPanel&gt;</programlisting>


<simpara>The example above shows the editor and its output, which is updated every second after each instant change or immediately after user focus leaves the editor area.</simpara>

</section>
<section id="sect-Component_Reference-richeditor-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:editor&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the current value of the input control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the value of the input control to the <literal>newValue</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getEditor()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns the CKEditor object instance associated to given <literal>&lt;rich:editor&gt;</literal> component.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getInput()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns the associated textarea.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>focus()</literal>
    </term>
    
    <listitem>
      
      <simpara>Gives focus to this component</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>blur()</literal>
    </term>
    
    <listitem>
      
      <simpara>Removes focus from this component</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isFocused()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if this component is focused</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isDirty()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if editor is focused and it was edited from last focus event (reset by blur event, by using <literal>setValue(newValue)</literal> call and when component is re-rendered)</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isValueChanged()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if the control&#8217;s value has been changed from the default (reset by <literal>setValue(newValue)</literal> call and when component is re-rendered)</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isReadonly()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if editor content is editable.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setReadonly(readonly)</literal>
    </term>
    
    <listitem>
      
      <simpara>When <literal>readonly</literal> is <literal>true</literal>, editor will be switched to editable state. Otherwise, it will be switched to readonly state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richeditor-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Editor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIEditor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Editor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.EditorRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richeditor-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richeditor-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces</literal>::</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_wrapper</literal>::</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>editorMainBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_dialog_body</literal>::</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_dialog_title</literal>::</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>repeat-x</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_path a</literal>, <literal>.cke_skin_richfaces .cke_path .cke_empty</literal>::</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>editorMainTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_button a.cke_on</literal>::</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_button a:hover</literal>, <literal>.cke_skin_richfaces .cke_button a:focus</literal>, <literal>.cke_skin_richfaces .cke_button a:active</literal>::</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_rcombo a</literal>:: <literal>.cke_skin_richfaces .cke_rcombo a:active</literal>:: <literal>.cke_skin_richfaces .cke_rcombo a:hover</literal>::</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>controlTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>controlBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.cke_skin_richfaces .cke_rcombo .cke_openbutton</literal>::</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-left-color</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richfileUpload">
  <title><literal>&lt;rich:fileUpload&gt;</literal></title>
  <simpara>The <literal>&lt;rich:fileUpload&gt;</literal> component allows the user to upload files to a server. It features multiple uploads, progress bars, restrictions on file types, and restrictions on sizes of the files to be uploaded.</simpara>
<section id="sect-Component_Reference-richfileUpload-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage requires the <literal>fileUploadListener</literal> attribute. Use the attribute to reference a listener function on the server side after each file is uploaded. The listener should process files as required, such as storing them in the _session/db/filesystem/_directory. The component itself does not store uploaded files, so if the listener is not implemented they are not stored anywhere.</simpara>
<example id="exam-Component_Reference-richfileUpload-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:fileUpload fileUploadListener="#{bean.listener}" /&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richfileUpload-Upload_settings">
  <title>Upload settings</title>
  <simpara>Files are uploaded to either the temporary folder (different for each operating system) or to RAM(random-access memory), depending on the value of the <literal>org.richfaces.fileUpload.createTempFiles</literal> context parameter of the _web.xml_settings file for the project. If the parameter is set to <literal>true</literal>, the files are uploaded to the temporary folder.</simpara>
<simpara>To limit the maximum size of the uploaded files, define the byte size with the <literal>org.richfaces.fileUpload.maxRequestSize</literal> context parameter of the _web.xml_settings file for the project.</simpara>

</section>
<section id="sect-Component_Reference-richfileUpload-Sanitizing_file_upload_input">
  <title>Sanitizing file upload input</title>
  <simpara>Any file is accepted by rich:fileUpload component by default. There are three parameters available for limiting what can user upload to the server:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>maxFilesQuantity</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>maxFilesQuantity</literal> parameter defines maximum number of files allowed to be uploaded. After a number of files in the list equals to the value of this attribute, "Add" button disappears and nothing could be uploaded even if you clear the whole list. In order to upload files again you should rerender the component.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>acceptedTypes</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>acceptedTypes</literal> parameter defines comma separated list of file extensions accepted by component. The component does not provide any feedback when rejecting file. For introducing feedback for rejection, use <literal>ontyperejected</literal> parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>ontyperejected</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>ontyperejected</literal> parameter defines event handler when file does not meet conditions stated by <literal>acceptedTypes</literal> parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richfileUpload-Interactivity_options">
  <title>Interactivity options</title>
  <simpara>Set the <literal>immediateUpload</literal> attribute to <literal>true</literal> to upload files as soon as they are added to the list, rather than waiting for the user to press the Uploadbutton.</simpara>
<simpara>The text labels used in the component can be completely customized. Labels for the various controls of the component can be set using the following parameters:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>addLabel</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>addLabel</literal> parameter sets the label for the Addbutton.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>clearAllLabel</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>clearAllLabel</literal> parameter sets the label for the Clear Allbutton.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>clearLabel</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>clearLabel</literal> parameter sets the label for the Clearbutton.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>uploadLabel</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>uploadLabel</literal> parameter sets the label for the Uploadbutton.
The <literal>&lt;rich:fileUpload&gt;</literal> component provides a built-in progress bar to indicate the progress of each file that is uploaded. This progress bar can be replaced with a <literal>&lt;rich:progressBar&gt;</literal> component added to the <literal>progress</literal> facet. Refer to <xref linkend="sect-Component_Reference-Output_and_messages-richprogressBar"/> for details on the <literal>&lt;rich:progressBar&gt;</literal> component.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<simpara>To disable the <literal>&lt;rich:fileUpload&gt;</literal> component, use the <literal>disabled</literal> attribute.</simpara>

</section>
<section id="sect-Component_Reference-richfileUpload-richfileUpload_client-side_events">
  <title><literal>&lt;rich:fileUpload&gt;</literal> client-side events</title>
  <simpara>There are a number of event handlers specific to the <literal>&lt;rich:fileUpload&gt;</literal> component:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>filesubmit</literal> is triggered before a file is uploaded.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>uploadcomplete</literal> is triggered after all files in the list have finished uploading.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richfileUpload-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.FileUpload</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIFileUpload</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.FileUpload</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.FileUploadRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.FileUploadHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richfileUpload-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richfileUpload-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu</literal>:: This class defines styles for the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-hdr</literal>:: This class defines styles for the header of the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color, border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-lst</literal>:: This class defines styles for lists in the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-cntr-hdn</literal>:: This class defines styles for the file upload container when it is hidden.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btns-lft</literal>:: <literal>.rf-fu-btns-rgh</literal>:: These classes define styles for buttons on the left and right of the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-add</literal>:: This class defines styles for the Addbutton in the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>trimColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-cnt-add</literal>:: This class defines styles for the content of the Addbutton in the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-add-dis</literal>:: This class defines styles for the Addbutton in the file upload control when it is disabled.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableFooterBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableFooterBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-cnt-add-dis</literal>:: This class defines styles for the content of the Addbutton in the file upload control when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-upl</literal>:: This class defines styles for the Uploadbutton in the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>trimColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-cnt-upl</literal>:: This class defines styles for the content of the Uploadbutton in the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-clr</literal>:: This class defines styles for the Clearbutton in the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>trimColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-btn-cnt-clr</literal>:: This class defines styles for the content of the Clearbutton in the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-itm</literal>:: This class defines styles for an item in the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-itm-lft</literal>:: <literal>.rf-fu-itm-rgh</literal>:: These classes define styles for items on the left and right of the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-itm-lbl</literal>:: This class defines styles for the label of an item in the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-itm-st</literal>:: This class defines styles for the status of an item in the file upload control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-itm-lnk</literal>:: This class defines styles for a link item in the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalLinkColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-fu-inp</literal>:: This class defines styles for the input field in the file upload control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richinplaceInput">
  <title><literal>&lt;rich:inplaceInput&gt;</literal></title>
  <simpara>The <literal>&lt;rich:inplaceInput&gt;</literal> component allows information to be entered in-line in blocks of text, improving readability of the text. Multiple input regions can be navigated with keyboard navigation. The component has three functional states: the <emphasis>view</emphasis> state, where the component displays its initial setting, such as "click to edit"; the <emphasis>edit</emphasis> state, where the user can input text; and the "changed" state, where the new value for the component has been confirmed but can be edited again if required.</simpara>
<section id="sect-Component_Reference-richinplaceInput-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage requires the <literal>value</literal> attribute to point to the expression for the current value of the component. Validation and conversion rules for the JSF <literal>UIInput</literal> control apply as usual.</simpara>

</section>
<section id="sect-Component_Reference-richinplaceInput-Interactivity_options">
  <title>Interactivity options</title>
  <simpara>When in the initial <emphasis>view</emphasis> state, the starting label can be set using the <literal>defaultLabel</literal> attribute. Alternatively, if the initial value is already set through the <literal>value</literal> attribute, this is displayed instead.</simpara>
<simpara>Once the user has entered text, the label is stored in the model specified by the <literal>value</literal> attribute. The use of the default label and value is shown in <xref linkend="exam-Component_Reference-richinplaceInput-Default_label_and_value"/>.</simpara>
<example id="exam-Component_Reference-richinplaceInput-Default_label_and_value">
  <title>Default label and value</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:inplaceInput value="#{bean.value}" defaultLabel="click to edit"/&gt;
</programlisting>



</example>
<simpara>By default, the event to switch the component to the <emphasis>edit</emphasis> state is a single mouse click. This can be changed using the <literal>editEvent</literal> attribute to specify a different event.</simpara>
<simpara>The user can confirm and save their input in multiple ways:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>By default, pressing the Enterkey will confirm and save the input.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>If <literal>showControls="true"</literal> is set, buttons for confirming or canceling are added to the component.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>If <literal>saveOnBlur="true"</literal> is set, the input is saved on the component&#8217;s blur event.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Pressing the Esckey cancels editing in all cases.</simpara>

</section>
<section id="sect-Component_Reference-richinplaceInput-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:inplaceInput&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the current value of the input control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the value of the input control to the <literal>newValue</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isEditState()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if the control is currently in the <emphasis>edit</emphasis> state, or <literal>false</literal> if the control is currently in the <emphasis>view</emphasis> state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isValueChanged()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if the control&#8217;s value has been changed from the default.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>save()</literal>
    </term>
    
    <listitem>
      
      <simpara>Saves the current item as the control&#8217;s value.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>cancel()</literal>
    </term>
    
    <listitem>
      
      <simpara>Cancel editing the value.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getInput()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the DOM element for the input.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richinplaceInput-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.InplaceInput</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIInplaceInput</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.InplaceInput</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.InplaceInputRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richinplaceInput-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richinplaceInput-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii</literal>:: This class defines styles for the in-place input when it is in the default state.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>editorBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-act</literal>:: This class defines styles for the in-place input when it is in the editing state.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-chng</literal>:: This class defines styles for the in-place input when it is in the changed state.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-dis</literal>:: This class defines styles for the in-place input when it is in the disabled state.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-fld</literal>:: This class defines styles for the in-place input field.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>editBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color, border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-lbl</literal>:: This class defines styles for the label of the in-place input.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-dflt-lbl</literal>:: This class defines styles for the default label of the in-place input.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-btn</literal>:: This class defines styles for the buttons for the in-place input.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-btn-p</literal>:: This class defines styles for the buttons for the in-place input when they are pressed.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-btn-set</literal>:: <literal>.rf-ii-btn-prepos</literal>:: <literal>.rf-ii-btn-pos</literal>:: These classes define the positioning of the buttons.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-btn-shdw</literal>:: This class defines styles for the button shadows for the in-place input.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-btn-shdw-t</literal>:: <literal>.rf-ii-btn-shdw-b</literal>:: <literal>.rf-ii-btn-shdw-l</literal>:: <literal>.rf-ii-btn-shdw-r</literal>:: These classes define the top, bottom, left, and right edge of the button shadows.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ii-none</literal>:: This class defines styles for the in-place input when it cannot be edited.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richinplaceSelect">
  <title><literal>&lt;rich:inplaceSelect&gt;</literal></title>
  <simpara>The <literal>&lt;rich:inplaceSelect&gt;</literal> component is similar to the <literal>&lt;rich:inplaceInput&gt;</literal> component, except that the <literal>&lt;rich:inplaceSelect&gt;</literal> component uses a drop-down selection box to enter text instead of a regular text field. Changes can be rendered either in-line or for the whole block, and inputs can be focused with keyboard navigation. The component is based on the JSF <literal>UISelectOne</literal> component, so all the standard rules for value definition, processing, conversion, and validation apply.</simpara>
<simpara>The component has three functional states:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>When in the <emphasis>view</emphasis> state, the component displays its initial setting, such as "click to edit".</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>When in the <emphasis>edit</emphasis> state, the user can select a value from a drop-down list.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>When in the <emphasis>changed</emphasis> state, the new value for the component has been confirmed, but it can be edited again if required.</simpara>
      
    </listitem>
  
</itemizedlist>

<figure id="figu-Component_Reference-richinplaceSelect-richinplaceSelect">
  <title><literal>&lt;rich:inplaceSelect&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richinplaceSelect-richinplaceSelect.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richinplaceSelect-richinplaceSelect</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richinplaceSelect-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage requires the <literal>value</literal> attribute to point to the expression for the current value of the component and a list of items. The list of items can be defined using the JSF components <literal>&lt;f:selectItem/&gt;</literal> and <literal>&lt;f:selectItems/&gt;</literal>.</simpara>
<example id="exam-Component_Reference-richinplaceSelect-Defining_list_items_for_richinplaceSelect">
  <title>Defining list items for <literal>&lt;rich:inplaceSelect&gt;</literal></title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:inplaceSelect value="#{bean.inputValue}" defaultLabel="click to edit" &gt;
    &lt;f:selectItems value="#{bean.selectItems}" /&gt;
    &lt;f.selectItem itemValue="1" itemLabel="Item 1" /&gt;
    &lt;f.selectItem itemValue="2" itemLabel="Item 2" /&gt;
    &lt;f.selectItem itemValue="3" itemLabel="Item 3" /&gt;
    &lt;f.selectItem itemValue="4" itemLabel="Item 4" /&gt;
&lt;/rich:comboBox&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richinplaceSelect-Interactivity_options">
  <title>Interactivity options</title>
  <simpara>When in the initial <emphasis>view</emphasis> state, the starting label can be set using the <literal>defaultLabel</literal> attribute, such as <literal>defaultLabel="click to edit"</literal>. Alternatively, if the initial value is already set through the <literal>value</literal> attribute, this is displayed instead.</simpara>
<simpara>By default, the event to switch the component to the <emphasis>edit</emphasis> state is a single mouse click. This can be changed using the <literal>editEvent</literal> attribute to specify a different event. When switching to <emphasis>edit</emphasis> mode, the drop-down list of possible values will automatically be displayed; this can be deactivated by setting <literal>openOnEdit="false"</literal>.</simpara>
<simpara>Once a new value for the control is saved, the state switches to the "changed" state. Saving a new value for the control can be performed in a number of ways:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>Once the user selects an item from the drop-down list, the item is saved as the new control value. This is the default setting. If <literal>saveOnSelect="false"</literal> is set, the component applies the selected item but remains in the <emphasis>edit</emphasis> state so a different selection could be chosen. The value is then applied when the Enterkey is pressed.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>If <literal>saveOnBlur="true"</literal> is set, the selected item is saved as the new control value when the control loses focus.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>If <literal>showControls="true"</literal> is set, buttons are added to the control to confirm or cancel the selection. The new control value is only saved once the user confirms the selection using the button.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Pressing the Esckey cancels editing in all cases.</simpara>

</section>
<section id="sect-Component_Reference-richinplaceSelect-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:inplaceSelect&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the current value of the select control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the value of the select control to the <literal>newValue</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isEditState()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if the control is currently in the <emphasis>edit</emphasis> state, or <literal>false</literal> if the control is currently in the <emphasis>view</emphasis> state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isValueChanged()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns <literal>true</literal> if the control&#8217;s value has been changed from the default.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>save()</literal>
    </term>
    
    <listitem>
      
      <simpara>Saves the current item as the control&#8217;s value.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>cancel()</literal>
    </term>
    
    <listitem>
      
      <simpara>Cancel editing the value.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getInput()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the input entered into the control by the user.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getLabel()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the default label of the control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setLabel(newLabel)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the default label of the control to the <literal>newLabel</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>showPopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the pop-up list of possible values.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hidePopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the pop-up list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richinplaceSelect-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.InplaceSelect</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIInplaceSelect</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Select</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.InplaceSelectRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richinplaceSelect-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richinplaceSelect-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-d-s</literal>:: This class defines styles for the in-place select when it is in the default state.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>editorBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-e-s</literal>:: This class defines styles for the in-place select when it is in the editing state.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-c-s</literal>:: This class defines styles for the in-place select when it is in the changed state.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-dis-s</literal>:: This class defines styles for the in-place select when it is in the disabled state.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-fld</literal>:: This class defines styles for the in-place select field.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>editBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-opt</literal>:: This class defines styles for an option for the in-place select.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-sel</literal>:: This class defines styles for the selected option of the in-place select.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-lbl</literal>:: This class defines styles for the label of the in-place select.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-dflt-lbl</literal>:: This class defines styles for the default label of the in-place select.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-edit</literal>:: This class defines styles for the in-place select when it is being edited.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-btn</literal>:: This class defines styles for the buttons for the in-place select.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-btn-p</literal>:: This class defines styles for the buttons for the in-place select when they are pressed.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-btn-set</literal>:: <literal>.rf-is-btn-prepos</literal>:: <literal>.rf-is-btn-pos</literal>:: These classes define the positioning of the buttons.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-lst-pos</literal>:: This class defines the positioning of the list.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-lst-dec</literal>:: This class defines styles for a decreasing list for the in-place select.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>editBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-lst-scrl</literal>:: This class defines styles for the list scrollbar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-shdw</literal>:: This class defines styles for the in-place select shadow.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-shdw-t</literal>:: <literal>.rf-is-shdw-b</literal>:: <literal>.rf-is-shdw-l</literal>:: <literal>.rf-is-shdw-r</literal>:: These classes define the top, bottom, left, and right edge of the in-place select shadows.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-btn-shdw</literal>:: This class defines styles for the button shadows for the in-place select.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-is-none</literal>:: This class defines styles for the in-place select when it cannot be edited.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richinputNumberSlider">
  <title><literal>&lt;rich:inputNumberSlider&gt;</literal></title>
  <simpara>The <literal>&lt;rich:inputNumberSlider&gt;</literal> component provides a slider for changing numerical values. Optional features include control arrows to step through the values, a tool-tip to display the value while sliding, and a text field for typing the numerical value which can then be validated against the slider&#8217;s range.</simpara>
<figure id="figu-Component_Reference-richinputNumberSlider-richinputNumberSlider">
  <title><literal>&lt;rich:inputNumberSlider&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richinputNumberSlider-richinputNumberSlider.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richinputNumberSlider-richinputNumberSlider</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richinputNumberSlider-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic use of the component with no attributes specified will render a slider with a minimum value of 0, a maximum of 100, and a gradient step of 1, together with a text field for typing the desired numerical value. The slider is labeled with the minimum and maximum boundary values, and a tool-tip showing the current value is shown while sliding the slider. The <literal>value</literal> attribute is used for storing the currently selected value of the slider. Standard conversion and validation for the JSF <literal>UIInput</literal> component is applied.</simpara>

</section>
<section id="sect-Component_Reference-richinputNumberSlider-Interactivity_options">
  <title>Interactivity options</title>
  <simpara>The text field can be removed by setting <literal>showInput="false"</literal>.</simpara>
<simpara>The properties of the slider can be set with the attributes <literal>minValue</literal>, <literal>maxValue</literal>, and <literal>step</literal>.</simpara>
<simpara>The minimum and maximum labels on the slider can be hidden by setting <literal>showBoundaryValues="false"</literal>. The tool-tip showing the current value can be hidden by setting <literal>showToolTip="false"</literal>.</simpara>
<simpara>Arrow controls can be added to either side of the slider to adjust the value incrementally by setting <literal>showArrows="true"</literal>. Clicking the arrows move the slider indicator in that direction by the gradient step, and clicking and holding the arrows moves the indicator continuously. The time delay for each step when updating continuously can be defined using the <literal>delay</literal> attribute.</simpara>

</section>
<section id="sect-Component_Reference-richinputNumberSlider-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:inputNumberSlider&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the current value of the slider control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the value of the slider control to the <literal>newValue</literal> integer passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>increase()</literal>
    </term>
    
    <listitem>
      
      <simpara>Increase the value of the slider control by the gradient step amount.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>decrease()</literal>
    </term>
    
    <listitem>
      
      <simpara>Decrease the value of the slider control by the gradient step amount.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richinputNumberSlider-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.InputNumberSlider</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIInputNumberSlider</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Input</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.inputNumberSliderRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richinputNumberSlider-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richinputNumberSlider-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl</literal>:: This class defines styles for the number slider itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-trc</literal>:: This class defines styles for the number slider track.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>controlBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-trc-cntr</literal>:: This class defines styles for the container of the number slider track.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-mn</literal>:: This class defines styles for the minimumlabel on the number slider.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-left-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-mx</literal>:: This class defines styles for the maximumlabel on the number slider.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-inp</literal>:: This class defines styles for the input field on the number slider.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-inp-cntr</literal>:: This class defines styles for the container of the input field.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-hnd</literal>:: This class defines styles for the handle on the number slider.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-hnd-cntr</literal>:: This class defines styles for the container of the handle.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-hnd-sel</literal>:: This class defines styles for the handle when it is selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-hnd-dis</literal>:: This class defines styles for the handle when it is selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-dec</literal>:: <literal>.rf-insl-inc</literal>:: These classes define styles for the step controls to decrease and increase the number.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-dec-sel</literal>:: <literal>.rf-insl-inc-sel</literal>:: These classes define styles for the step controls when they are selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-dec-dis</literal>:: <literal>.rf-insl-inc-dis</literal>:: These classes define styles for the step controls when they are disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insl-tt</literal>:: This class defines styles for the tool-tip on the number slider.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tipBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tipBackgroundColor</literal></simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richinputNumberSpinner">
  <title><literal>&lt;rich:inputNumberSpinner&gt;</literal></title>
  <simpara>The <literal>&lt;rich:inputNumberSpinner&gt;</literal> component is a single-line input field with buttons to increase and decrease a numerical value. The value can be changed using the corresponding directional keys on a keyboard, or by typing into the field.</simpara>
<figure id="figu-Component_Reference-richinputNumberSpinner-richinputNumberSpinner">
  <title><literal>&lt;rich:inputNumberSpinner&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richinputNumberSpinner-richinputNumberSpinner.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richinputNumberSpinner-richinputNumberSpinner</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richinputNumberSpinner-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic use of the component with no attributes specified will render a number spinner with a minimum value of 1, a maximum value of 100, and a gradient step of 1.</simpara>
<simpara>These default properties can be re-defined with the attributes <literal>minValue</literal>, <literal>maxValue</literal>, and <literal>step</literal> respectively. The starting value of the spinner is the minimum value unless otherwise specified with the <literal>value</literal> attribute.</simpara>

</section>
<section id="sect-Component_Reference-richinputNumberSpinner-Interactivity_options">
  <title>Interactivity options</title>
  <simpara>When changing the value using the buttons, raising the value above the maximum or cause the spinner to restart at the minimum value. Likewise, when lowering below the minimum value the spinner will reset to the maximum value. This behavior can be deactivated by setting <literal>cycled="false"</literal>, which will cause the buttons to stop responding when the reach the maximum or minimum value.</simpara>
<simpara>The ability to change the value by typing into the text field can be disabled by setting <literal>enableManualInput="false"</literal>.</simpara>

</section>
<section id="sect-Component_Reference-richinputNumberSpinner-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:inputNumberSpinner&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the current value of the spinner control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the value of the spinner control to the <literal>newValue</literal> integer passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>increase()</literal>
    </term>
    
    <listitem>
      
      <simpara>Increase the value of the spinner control by the gradient step amount.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>decrease()</literal>
    </term>
    
    <listitem>
      
      <simpara>Decrease the value of the spinner control by the gradient step amount.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richinputNumberSpinner-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.InputNumberSpinner</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIInputNumber</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Input</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.InputNumberSpinnerRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richinputNumberSpinner-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richinputNumberSpinner-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insp</literal>:: This class defines styles for the number spinner itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insp-inp</literal>:: This class defines styles for the input field on the number spinner.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>controlBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insp-btns</literal>:: This class defines styles for the buttons on the number spinner.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-left-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insp-dec</literal>:: <literal>.rf-insp-inc</literal>:: These classes define styles for the step controls to decrease and increase the number.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-insp-dec-dis</literal>:: <literal>.rf-insp-inc-dis</literal>:: These classes define styles for the step controls when they are disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richselect">
  <title><literal>&lt;rich:select&gt;</literal></title>
  <simpara>The <literal>&lt;rich:select&gt;</literal> component provides a drop-down list box for selecting a single value from multiple options. The <literal>&lt;rich:select&gt;</literal> component can be configured as a combo-box, where it will accept typed input. The component also supports keyboard navigation. The <literal>&lt;rich:select&gt;</literal> component functions similarly to the JSF <literal>UISelectOne</literal> component.</simpara>
<figure id="figu-Component_Reference-richselect-richselect">
  <title><literal>&lt;rich:select&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richselect-richselect.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richselect-richselect</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richselect-Basic_usage">
  <title>Basic usage</title>
  <simpara>Simple usage of the <literal>&lt;rich:select&gt;</literal> component requires the <literal>value</literal> attribute to store the selected value. Additionally, child tags to manage the list of selections are required. The child tags can either be a number of <literal>&lt;f:selectItem&gt;</literal> tags or a <literal>&lt;f:selectItems&gt;</literal> tag which points to a data model containing a list of selection items. The <literal>value</literal> attribute is used to store the current selection.</simpara>
<example id="exam-Component_Reference-richselect-Selection_items">
  <title>Selection items</title>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using multiple <literal>&lt;f:selectItem&gt;</literal>  tags
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:select&gt;
   &lt;f:selectItem itemValue="0" itemLabel="Option 1" /&gt;
   &lt;f:selectItem itemValue="1" itemLabel="Option 2" /&gt;
   &lt;f:selectItem itemValue="2" itemLabel="Option 3" /&gt;
   &lt;f:selectItem itemValue="3" itemLabel="Option 4" /&gt;
   &lt;f:selectItem itemValue="4" itemLabel="Option 5" /&gt;
&lt;/rich:select&gt;
</programlisting>



<variablelist>
  
  
  <varlistentry>
    <term>
      Using a single <literal>&lt;f:selectItems&gt;</literal>  tag
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:select&gt;
   &lt;f:selectItems value="#{bean.options}" /&gt;
&lt;/rich:select&gt;
</programlisting>



</example>
<simpara>The arrow keys on a keyboard can be used to highlight different items in the list. If the control loses focus or the Enterkey is pressed, the highlighted option is chosen as the value and the list is closed. Pressing the Esckey will close the list but not change the value.</simpara>

</section>
<section id="sect-Component_Reference-richselect-Using_manual_input">
  <title>Using manual input</title>
  <simpara>The <literal>&lt;rich:select&gt;</literal> component allows the user to type into a text field to scroll through or filter the list. By default, the <literal>&lt;rich:select&gt;</literal> component functions as a drop-down list with no manual input. To add keyboard support for manual input, set <literal>enableManualInput="true"</literal>.</simpara>
<simpara>Once the user begins typing, the first available matching option is highlighted. If the typed text does not match any values in the list, no value is chosen and the drop-down list displays as empty. Other keyboard interaction remains the same as the basic drop-down list.</simpara>
<simpara>The standard JSF <literal>&lt;h:selectOne&gt;</literal> component does not offer this extended keyboard support. However, since the <literal>&lt;rich:select&gt;</literal> component is still based on the JSF <literal>UISelectOne</literal> component, it will not accept a value that does not match any items in the drop-down list. If an invalid value is entered, it is highlighted as erroneous and validation messages appear with the submission.</simpara>

</section>
<section id="sect-Component_Reference-richselect-Advanced_options">
  <title>Advanced options</title>
  <simpara>Use the <literal>defaultLabel</literal> attribute to set a place-holder label, such as <literal>defaultLabel="select an option"</literal>.</simpara>
<simpara>Server-side processing occurs in the same manner as for an <literal>&lt;h:selectOneMenu&gt;</literal> component. As such, custom objects used for selection items should use the same converters as for an <literal>&lt;h:selectOneMenu&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richselect-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:select&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the current value of the text field.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue(newValue)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the value of the text field to the <literal>newValue</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getLabel()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the default label of the control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>showPopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the pop-up list of completion values.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hidePopup()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the pop-up list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richselect-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Select</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UISelect</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Select</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.SelectRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richselect-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richselect-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel</literal>:: This class defines styles for the select control itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-cntr</literal>:: This class defines styles for the container of the select control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-inp</literal>:: This class defines styles for the select control input field.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>controlBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-fld-err</literal>:: This class defines styles for the input field when an error occurs.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-opt</literal>:: This class defines styles for an option in the select control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-sel</literal>:: This class defines styles for the selected option of the select control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-dflt-lbl</literal>:: This class defines styles for the default label of the select control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-btn</literal>:: This class defines styles for the button of the select control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-left-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-btn-arrow</literal>:: This class defines styles for the arrow on the button.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-btn-dis</literal>:: This class defines styles for the button of the select control when it is disabled.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-lst-scrl</literal>:: This class defines styles for the list scrollbar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-shdw</literal>:: This class defines styles for the select control shadow.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-sel-shdw-t</literal>:: <literal>.rf-sel-shdw-b</literal>:: <literal>.rf-sel-shdw-l</literal>:: <literal>.rf-sel-shdw-r</literal>:: These classes define the top, bottom, left, and right edge of the select control shadows.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-richorderingList">
  <title><literal>&lt;rich:orderingList&gt;</literal></title>
  <simpara>The <literal>&lt;rich:orderingList&gt;</literal> is a component for ordering items in a list (client-side).</simpara>
<figure id="figu-Component_Reference-richorderingList-richorderingList">
  <title><literal>&lt;rich:select&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richorderingList-richorderingList.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richorderingList-richorderingList</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richorderingList-Basic_usage">
  <title>Basic usage</title>
  <simpara>To use the <literal>&lt;rich:orderingList&gt;</literal> bind the <literal>value</literal> attribute to the list to be ordered. The <literal>var</literal> attribute specifies a variable to use when iterating through the list values. The <literal>var</literal> attribute is used within the <literal>itemLabel</literal> to assign the object value to be displayed. Similarly, the <literal>var</literal> attribute is used within the <literal>itemValue</literal> attribute to specify the object value mapped by the display value. If the itemValue is not of type <literal>String</literal>, a converter must be specified for this itemValue using either the <literal>converter</literal> attribute, or a nested <literal>&lt;f:converter&gt;</literal> tag.</simpara>
<example id="exam-Component_Reference-richorderingList-ItemLabel_use">
  <title>ItemLabel/ItemValue use</title>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using the <literal>itemLabel</literal>  and <literal>itemValue</literal>  attributes
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:orderingList value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}"&gt;
    &lt;f:converter converterId="CapitalsConverter" /&gt;
&lt;/rich:orderingList&gt;</programlisting>



</example>
<simpara>The arrow keys on a keyboard can be used to highlight different items in the list. Pressing the ctrlmodifier with the arrow keys will move the selected item up or down within the list.</simpara>

</section>
<section id="sect-Component_Reference-richorderingList-Column_layout">
  <title>Column Layout</title>
  <simpara>In addition to the above simple itemLabel display, the <literal>&lt;rich:orderingList&gt;</literal> supports a columnar layout of the itemValues to be sorted. This is achieved by nesting <literal>&lt;rich:column&gt;</literal> tags within the orderingList, and referencing the <literal>var</literal> attribute from within the <literal>&lt;rich:column&gt;</literal> EL.</simpara>
<example id="exam-Component_Reference-richorderingList-richcolumn">
  <title>Nested <literal>&lt;rich:column&gt;</literal> tags</title>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using <literal>&lt;rich:column&gt;</literal>  tags nested within the <literal>&lt;rich:orderingList&gt;</literal>
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:orderingList value="#{listSelectBean.capitals}" var="capital"  listWidth="300px"&gt;
    &lt;f:converter converterId="CapitalsConverter" /&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;Flag&lt;/f:facet&gt;
        &lt;h:graphicImage value="#{capital.stateFlag}" alt="flag"  width="33"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;Name&lt;/f:facet&gt;
        #{capital.name}
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;State&lt;/f:facet&gt;
        #{capital.state}
    &lt;/rich:column&gt;
&lt;/rich:orderingList&gt;</programlisting>



</example>
<simpara>When using <literal>&lt;rich:column&gt;</literal> tags to layout the <literal>&lt;rich:orderingList&gt;</literal> items, the <literal>itemLabel</literal> attribute is irrelevant, and may be left out.</simpara>

</section>
<section id="sect-Component_Reference-richorderingList-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:orderingList&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getList()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns the javascript list object backing the <literal>&lt;rich:orderingList&gt;</literal>. This list can be used to select/unselect item(s).</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>up()</literal>
    </term>
    
    <listitem>
      
      <simpara>Move the currently selected item(s) up one step.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>down()</literal>
    </term>
    
    <listitem>
      
      <simpara>Move the currently selected item(s) down one step.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>upTop()</literal>
    </term>
    
    <listitem>
      
      <simpara>Move the currently selected item(s) to the top of the list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>downBottom()</literal>
    </term>
    
    <listitem>
      
      <simpara>Move the currently selected item(s) to the bottom of the list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>toggleButtons()</literal>
    </term>
    
    <listitem>
      
      <simpara>Activate/de-activate the orderingList buttons based on the current component item state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richorderingList-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.OrderingList</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIOrderingList</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.SelectMany</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.OrderingListRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richorderingList-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richorderingList-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord</literal>:: This class defines styles for the orderingList control itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-cntr</literal>:: This class defines styles for the container of the orderingList control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-cptn</literal>:: This class defines styles for the caption of the orderingList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-lst</literal>:: This class defines styles for the items list of the orderingList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-hdr</literal>:: This class defines styles for the header of the items list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-opt</literal>:: This class defines styles for an option in the orderingList control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-sel</literal>:: This class defines styles for the selected option of the orderingList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-dflt-lbl</literal>:: This class defines styles for the default label of the orderingList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-btn</literal>:: This class defines styles for the button of the orderingList control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-left-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ord-btn-dis</literal>:: This class defines styles for the button of the orderingList control when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Rich_inputs-pickList">
  <title><literal>&lt;rich:pickList&gt;</literal></title>
  <simpara>The <literal>&lt;rich:pickList&gt;</literal> is a component for selecting items from a list. Additionally, it allows for the selected items to be ordered (client-side). From the client side perspective, items are added/removed from the source list, and removed/added to the target list. However it is important to note that the server-side source of items is never modified, and always represents the list of all items available for selection. If the list of unselected items is required, it can be determined by subtracting the collection of all selected items from the collection of all available items.</simpara>
<figure id="figu-Component_Reference-richpickList-richpickList">
  <title><literal>&lt;rich:select&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richpickList-richpickList.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richpickList-richpickList</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richpickList-Basic_usage">
  <title>Basic usage</title>
  <simpara>To use the <literal>&lt;rich:pickList&gt;</literal> bind the <literal>value</literal> attribute to the target list, where the selected items will be stored. The list of source items is provided by nesting a <literal>SelectItem</literal> source, such as a <literal>&lt;f:selectItems&gt;</literal> tag, or a list of <literal>&lt;f:selectItem&gt;</literal> tags. If the itemValue of the <literal>SelectItem</literal> is not of type <literal>String</literal>, a converter must be specified for this itemValue using either the <literal>converter</literal> attribute, or a nested <literal>&lt;f:converter&gt;</literal> tag.</simpara>
<example id="exam-Component_Reference-richpickList-ItemLabel_use">
  <title>Simple pickList use</title>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using the default <literal>SelectItem</literal>  itemLabel to generate the pickList source and target items.
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:pickList value="#{listSelectBean.selectedCapitals}"
               sourceCaption="Available cities" targetCaption="Selected cities"
               listWidth="170px" listHeight="100px"
               orderable="true"&gt;
    &lt;f:selectItems value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}" /&gt;
    &lt;f:converter converterId="CapitalsConverter" /&gt;
&lt;/rich:pickList&gt;</programlisting>



</example>
<simpara>The items in the target list can be ordered client-side by setting the <literal>orderable</literal> attribute of the <literal>&lt;rich:pickList&gt;</literal> tag to <literal>true</literal>. The arrow keys on a keyboard can then be used to highlight different items in the target list, and pressing the ctrlmodifier with the arrow keys will move the selected item up or down within the target list.</simpara>

</section>
<section id="sect-Component_Reference-richpickList-Column_layout">
  <title>Column Layout</title>
  <simpara>In addition to the above simple <literal>SelectItem</literal> itemLabel display, the <literal>&lt;rich:pickList&gt;</literal> supports a columnar layout of the items to be selected. This is achieved by adding a <literal>var</literal> attribute used to represent the collection of nested <literal>SelectItems</literal>, and nesting <literal>&lt;rich:column&gt;</literal> tags within the pickList. The <literal>var</literal> attribute of the <literal>&lt;f:selectItem&gt;</literal> is then referenced from within the <literal>&lt;rich:column&gt;</literal> EL.</simpara>
<example id="exam-Component_Reference-richpickList-richcolumn">
  <title>Nested <literal>&lt;rich:column&gt;</literal> tags</title>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using <literal>&lt;rich:column&gt;</literal>  tags nested within the <literal>&lt;rich:pickList&gt;</literal>
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:pickList value="#{listSelectBean.selectedCapitals}" var="capital" listHeight="200px"&gt;
    &lt;f:selectItems value="#{listSelectBean.capitals}" /&gt;
    &lt;f:converter converterId="CapitalsConverter" /&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;Flag&lt;/f:facet&gt;
        &lt;h:graphicImage value="#{capital.stateFlag}" alt="flag" width="33"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;Name&lt;/f:facet&gt;
        #{capital.name}
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;State&lt;/f:facet&gt;
        #{capital.state}
    &lt;/rich:column&gt;
&lt;/rich:pickList&gt;</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richpickList-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:pickList&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getSourceList()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns the javascript list object backing the <literal>&lt;rich:pickList&gt;</literal> source list. This list can be used to select/unselect item(s).</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getTargetList()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns the javascript list object backing the <literal>&lt;rich:pickList&gt;</literal> target list. This list can be used to select/unselect item(s).</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>add()</literal>
    </term>
    
    <listitem>
      
      <simpara>Add the currently selected items to the target list, removing them from the source list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>addAll()</literal>
    </term>
    
    <listitem>
      
      <simpara>Add all the source items to the target list, removing them from the source list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>remove()</literal>
    </term>
    
    <listitem>
      
      <simpara>Remove the currently selected items from the target list, adding them to the source list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>removeAll()</literal>
    </term>
    
    <listitem>
      
      <simpara>Remove all the source items from the target list, adding them to the source list.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>toggleButtons()</literal>
    </term>
    
    <listitem>
      
      <simpara>Activate/de-activate the pickList buttons based on the current component item state.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richpickList-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.PickList</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPickList</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.SelectMany</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PickListRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richpickList-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richpickList-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick</literal>:: This class defines styles for the pickList control itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-src-cptn, .rf-pick-tgt-cptn</literal>:: These classes define styles for the source and target captions of the pickList control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-lst</literal>:: This class defines styles for the items list of the pickList control.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-hdr</literal>:: This class defines styles for the header of the items list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-opt</literal>:: This class defines styles for an option in the pickList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-sel</literal>:: This class defines styles for the selected option of the pickList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-dflt-lbl</literal>:: This class defines styles for the default label of the pickList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-btn</literal>:: This class defines styles for the button of the pickList control.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-left-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-btn-dis</literal>:: This class defines styles for the button of the pickList control when it is disabled.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pick-lst-scrl</literal>:: This class defines styles for the list scrollbar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Panels">
  <title>Panels</title>
  <simpara>This chapter details those components which act as panels and containers to hold groups of other components.</simpara>
<section id="sect-Component_Reference-Panels-richpanel">
  <title><literal>&lt;rich:panel&gt;</literal></title>
  <simpara>The <literal>&lt;rich:panel&gt;</literal> component is a bordered panel with an optional header.</simpara>
<figure id="figu-Component_Reference-richpanel-richpanel">
  <title><literal>&lt;rich:panel&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richpanel-richpanel.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richpanel-richpanel</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richpanel-Basic_usage">
  <title>Basic usage</title>
  <simpara>No attributes need to be listed for basic usage. a <literal>&lt;rich:panel&gt;</literal> without any attributes defined renders a bordered region with no header.</simpara>

</section>
<section id="sect-Component_Reference-richpanel-Adding_a_header">
  <title>Adding a header</title>
  <simpara>To add a header to the panel, use the <literal>header</literal> attribute to specify the text to appear in the header. Alternatively the header can be constructed using a header facet. <xref linkend="exam-Component_Reference-richpanel-Adding_a_header"/> demonstrates the two different approaches.</simpara>
<example id="exam-Component_Reference-richpanel-Adding_a_header">
  <title>Adding a header</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel header="This is the panel header"&gt;
    &lt;h:outputText value="This is the panel content" /&gt;
&lt;/rich:panel&gt;
</programlisting>




<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel&gt;
    &lt;f:facet name="header"&gt;
        &lt;h:outputText value="This is the panel header"&gt;
    &lt;/f:facet&gt;
    &lt;h:outputText value="This is the panel content" /&gt;
&lt;/rich:panel&gt;
</programlisting>


<simpara>Both the examples render an identical panel.</simpara>
<blockquote>
  
  

<figure>
  <title>Adding a header</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richpanel-Adding_a_header.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richpanel-Adding_a_header</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>

</section>
<section id="sect-Component_Reference-richpanel-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Panel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Panel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PanelRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richpanel-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richpanel-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-p</literal>:: This class defines styles for the panel itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-p-hdr</literal>:: This class defines styles for the header of a panel.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color, border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-p-b</literal>:: This class defines styles for the body of a panel.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Panels-richaccordion">
  <title><literal>&lt;rich:accordion&gt;</literal></title>
  <simpara>The <literal>&lt;rich:accordion&gt;</literal> is a series of panels stacked on top of each other, each collapsed such that only the header of the panel is showing. When the header of a panel is clicked, it is expanded to show the content of the panel. Clicking on a different header will collapse the previous panel and epand the selected one. Each panel contained in a <literal>&lt;rich:accordion&gt;</literal> component is a <literal>&lt;rich:accordionItem&gt;</literal> component.</simpara>
<figure id="figu-Component_Reference-richaccordion-richaccordion">
  <title>A <literal>&lt;rich:accordion&gt;</literal> component containing three <literal>&lt;rich:accordionItem&gt;</literal> components</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richaccordion-richaccordion.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richaccordion-richaccordion</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richaccordion-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:accordion&gt;</literal> component requires no attributes for basic usage. The component can contain any number of <literal>&lt;rich:accordionItem&gt;</literal> components as children. The headers of the <literal>&lt;rich:accordionItem&gt;</literal> components control the expanding and collapsing when clicked. Only a single <literal>&lt;rich:accordionItem&gt;</literal> can be displayed at a time. Refer to <xref linkend="sect-Component_Reference-Panels-richaccordionItem"/> for details on the <literal>&lt;rich:accordionItem&gt;</literal> component.</simpara>
<note>
  <title>Form elements required</title>
  
<simpara>All <literal>&lt;rich:tabPanel&gt;</literal> components should be wrapped in a form element when using either <literal>ajax</literal> or <literal>server</literal> mode, as usual for submitting components.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-richaccordion-Switching_panels">
  <title>Switching panels</title>
  <simpara>The <literal>activeItem</literal> attribute holds the active panel name. This name is a reference to the <literal>name</literal> identifier of the active child <literal>&lt;rich:accordionItem&gt;</literal> component.</simpara>
<simpara>The switching mode for performing submissions is determined by the <literal>switchType</literal> attribute, which can have one of the following three values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>server</literal>
    </term>
    
    <listitem>
      
      <simpara>The default setting. Activation of a <literal>&lt;rich:accordionItem&gt;</literal> component causes the parent <literal>&lt;rich:accordion&gt;</literal> component to perform a common submission, completely refreshing the page. Only one panel at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>Activation of a <literal>&lt;rich:accordionItem&gt;</literal> component causes the parent <literal>&lt;rich:accordion&gt;</literal> component to perform an Ajax form submission, and the content of the panel is rendered. Only one panel at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>Activation of a <literal>&lt;rich:accordionItem&gt;</literal> component causes the parent <literal>&lt;rich:accordion&gt;</literal> component to perform updates on the client side. All the panels are rendered on the client side during the initial page render. JavaScript changes the styles such that one panel component becomes hidden while the other is shown.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richaccordion-richaccordion_client-side_events">
  <title><literal>&lt;rich:accordion&gt;</literal> client-side events</title>
  <simpara>In addition to the standard Ajax events and HTML events, the <literal>&lt;rich:accordion&gt;</literal> component uses the client-side events common to all switchable panels:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>itemchange</literal> event points to the function to perform when the switchable item is changed.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>beforeitemchange</literal> event points to the function to perform when before the switchable item is changed.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richaccordion-richaccordion_server-side_events">
  <title><literal>&lt;rich:accordion&gt;</literal> server-side events</title>
  <simpara>The <literal>&lt;rich:accordion&gt;</literal> component uses the server-side events common to all switchable panels:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>ItemChangeEvent</literal> event occurs on the server side when an item is changed through Ajax using the <literal>server</literal> mode. It can be processed using the <literal>ItemChangeListener</literal> attribute. Refer to <xref linkend="sect-Component_Reference-Panels-richitemChangeListener"/> for details on the <literal>&lt;rich:itemChangeListener&gt;</literal> tag.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richaccordion-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:accordion&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions, which are common to all switchable panels:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getItems()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return an array of the items contained in the accordion control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getItemsNames()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return an array of the names of the items contained in the accordion control.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>switchToItem(itemName)</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to and display the item identified by the <literal>itemName</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>firstItem()</literal>:: <literal>prevItem()</literal>:: <literal>nextItem()</literal>:: <literal>lastItem()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the name of the first item, the previous item, the next item, or the last item.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richaccordion-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Accordion</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIAccordion</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Accordion</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.AccordionRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.TogglePanelTagHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richaccordion-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richaccordion-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac</literal>:: This class defines styles for the accordion control itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-hdr</literal>:: This class defines styles for the header of an accordion item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-hdr-act</literal>:: <literal>.rf-ac-itm-hdr-inact</literal>:: These classes define styles for the header when the item is either active (expanded) or inactive (collapsed).</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-hdr-dis</literal>:: This class defines styles for the header when it is disabled.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-gr</literal>:: This class defines styles for an item group.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-cnt</literal>:: This class defines styles for the content of an accordion item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-ico</literal>:: This class defines styles for the item icon.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-exp-ico</literal>:: This class defines styles for the expanded icon for an item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-ico-act</literal>:: <literal>.rf-ac-itm-ico-inact</literal>:: These classes define styles for the icon when the item is either active (expanded) or inactive (collapsed).</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ac-itm-lbl</literal>:: This class defines styles for the item label.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>
<section id="sect-Component_Reference-Panels-richaccordionItem">
  <title><literal>&lt;rich:accordionItem&gt;</literal></title>
  <simpara>The <literal>&lt;rich:accordionItem&gt;</literal> component is a panel for use with the <literal>&lt;rich:accordion&gt;</literal> component. <literal>&lt;rich:accordionItem&gt;</literal> components can be added dynamically using iteration models with the <literal>&lt;c:forEach&gt;</literal> tag.</simpara>
<section id="sect-Component_Reference-richaccordionItem-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage of the <literal>&lt;rich:accordionItem&gt;</literal> component requires the <literal>header</literal> attribute, which provides the text on the panel header. The panel header is all that is visible when the accordion item is collapsed.</simpara>
<simpara>Alternatively the <literal>header</literal> facet could be used in place of the <literal>header</literal> attribute. This would allow for additional styles and custom content to be applied to the tab.</simpara>

</section>
<section id="sect-Component_Reference-richaccordionItem-richaccordionItem_client-side_events">
  <title><literal>&lt;rich:accordionItem&gt;</literal> client-side events</title>
  <simpara>In addition to the standard HTML events, the <literal>&lt;rich:accordionItem&gt;</literal> component uses the client-side events common to all switchable panel items:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>enter</literal> event points to the function to perform when the mouse enters the panel.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>leave</literal> event points to the function to perform when the mouse leaves the panel.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richaccordionItem-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.AccordionItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIAccordionItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.AccordionItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.AccordionItemRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</section>
<section id="sect-Component_Reference-Panels-richcollapsiblePanel">
  <title><literal>&lt;rich:collapsiblePanel&gt;</literal></title>
  <simpara>The <literal>&lt;rich:collapsiblePanel&gt;</literal> component is a collapsible panel that shows or hides content when the header bar is activated. It is a simplified version of <literal>&lt;rich:togglePanel&gt;</literal> component.</simpara>
<figure id="figu-Component_Reference-richcollapsiblePanel-richcollapsiblePanel">
  <title><literal>&lt;rich:collapsiblePanel&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richcollapsiblePanel-richcollapsiblePanel.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richcollapsiblePanel-richcollapsiblePanel</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richcollapsiblePanel-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage requires the header content is specified either by the <literal>header</literal> attribute, or by the <literal>headerExpanded</literal> / <literal>headerCollapsed</literal> facets. Additionally the panel requires content to display when it is expanded. Content is added as child elements like a standard panel.</simpara>

</section>
<section id="sect-Component_Reference-richcollapsiblePanel-Expanding_and_collapsing_the_panel">
  <title>Expanding and collapsing the panel</title>
  <simpara>The switching mode for performing submissions is determined by the <literal>switchType</literal> attribute, which can have one of the following three values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>server</literal>
    </term>
    
    <listitem>
      
      <simpara>This is the default setting. The <literal>&lt;rich:collapsiblePanel&gt;</literal> component performs a common submission, completely refreshing the page. Only one panel at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>&lt;rich:collapsiblePanel&gt;</literal> component performs an Ajax form submission, and only the content of the panel is refreshed. Only one panel at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>&lt;rich:collapsiblePanel&gt;</literal> component changes the state on the client side without any additional requests being sent.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richcollapsiblePanel-Appearance">
  <title>Appearance</title>
  <simpara>The appearance of the <literal>&lt;rich:collapsiblePanel&gt;</literal> component can be customized using facets. The <literal>headerExpanded</literal> and <literal>headerCollapsed</literal> CSS fclasses are used to style the appearance of the panel when it is expanded and collapsed respectively.</simpara>

</section>
<section id="sect-Component_Reference-richcollapsiblePanel-richcollapsiblePanel_server-side_events">
  <title><literal>&lt;rich:collapsiblePanel&gt;</literal> server-side events</title>
  <simpara>The <literal>&lt;rich:collapsiblePanel&gt;</literal> component uses the following unique server-side events:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>PanelToggleEvent</literal> event occurs on the server side when the <literal>&lt;rich:collapsiblePanel&gt;</literal> component is expanded or collapsed in either the <literal>ajax</literal> or <literal>server</literal> modes. It can be processed using the <literal>panelTogglerListener</literal> attribute.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richcollapsiblePanel-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:collapsiblePanel&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>switchPanel()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch the state of the collapsible panel (expanded or collapsed).</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richcollapsiblePanel-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.CollapsiblePanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UICollapsiblePanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.CollapsiblePanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.CollapsiblePanelRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.CollapsiblePanelTagHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richcollapsiblePanel-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richcollapsiblePanel-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp</literal>:: This class defines styles for the collapsible panel itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-hdr</literal>:: This class defines styles for the header of a collapsible panel.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color, border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-hdr-exp</literal>:: <literal>.rf-cp-hdr-colps</literal>:: These classes define styles for the header when the item is either expanded or collapsed.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-gr</literal>:: This class defines styles for a collapsible panel group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-b</literal>:: This class defines styles for the body of a collapsible panel.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-ico</literal>:: This class defines styles for the panel icon.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-exp-ico</literal>:: This class defines styles for the expanded icon for a panel.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-ico-exp</literal>:: <literal>.rf-cp-ico-colps</literal>:: These classes define styles for the icon when the panel is either expanded or collapsed.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-lbl</literal>:: This class defines styles for the panel label.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cp-lbl-exp</literal>:: <literal>.rf-cp-lbl-colps</literal>:: These classes define styles for the label when the panel is either expanded or collapsed.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>
<section id="sect-Component_Reference-Panels-richpanelToggleListener">
  <title><literal>&lt;rich:panelToggleListener&gt;</literal></title>
  <simpara>Use the <literal>&lt;rich:panelToggleListener&gt;</literal> tag to register a <literal>PanelToggleListener</literal> class on a parent <literal>&lt;rich:collapsiblePanel&gt;</literal> component. The class provided as a listener must implement the org.richfaces.event.PanelToggleListenerinterface. The processPanelTogglemethod accepts an <literal>org.richface.event.PanelToggleEvent</literal> event as a parameter.</simpara>

</section>

</section>
<section id="sect-Component_Reference-Panels-richpopupPanel">
  <title><literal>&lt;rich:popupPanel&gt;</literal></title>
  <simpara>The <literal>&lt;rich:popupPanel&gt;</literal> component provides a pop-up panel or window that appears in front of the rest of the application. The <literal>&lt;rich:popupPanel&gt;</literal> component functions either as a modal window which blocks interaction with the rest of the application while active, or as a non-modal window. It can be positioned on the screen, dragged to a new position by the user, and re-sized.</simpara>
<section id="sect-Component_Reference-richpopupPanel-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:popupPanel&gt;</literal> does not require any compulsory attributes, though certain use cases require different attributes.</simpara>

</section>
<section id="sect-Component_Reference-richpopupPanel-Showing_and_hiding_the_pop-up">
  <title>Showing and hiding the pop-up</title>
  <simpara>If <literal>show="true"</literal> then the pop-up panel will display when the page is first loaded.</simpara>
<simpara>The <literal>&lt;rich:popupPanel&gt;</literal> component can be shown and hidden manually using the <literal>show()</literal> and <literal>hide()</literal> methods from the JavaScript API. These can be implemented using two different approaches:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>Using the <literal>&lt;rich:componentControl&gt;</literal> component. For details on the component, refer to <xref linkend="sect-Component_Reference-Functionality_extension-richcomponentControl"/>.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>Using the <literal>rich:component</literal> function. For details on the function, refer to <xref linkend="sect-Component_Reference-Functions-richcomponent"/>.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>For explicit referencing when using the functions, the component can be given an <literal>id</literal> identifier.</simpara>
<simpara><xref linkend="exam-Component_Reference-richpopupPanel-richpopupPanel_example"/> demonstrates basic use of both the <literal>&lt;rich:componentControl&gt;</literal> component and the <literal>rich:component</literal> function to show and hide the <literal>&lt;rich:popupPanel&gt;</literal> component.</simpara>
<example id="exam-Component_Reference-richpopupPanel-richpopupPanel_example">
  <title><literal>&lt;rich:popupPanel&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:commandButton value="Show the panel"&gt;
    &lt;rich:componentControl target="popup" operation="show" /&gt;
&lt;/h:commandButton&gt;
...
&lt;rich:popupPanel id="popup"&gt;
    &lt;p&gt;&lt;a href="#" onclick="#{rich:component('popup')}.hide()"&gt;Hide the panel&lt;/a&gt;&lt;/p&gt;
&lt;/rich:popupPanel&gt;</programlisting>



</example>
<important>
  <title>Placement</title>
  
<simpara>The <literal>&lt;rich:popupPanel&gt;</literal> component is usually rendered in front of any other objects on the page. This is achieved by attaching the component to the <literal>&lt;body&gt;</literal> element of the page, and setting a very high <emphasis>"z-index"</emphasis> (the stack order of the object). This approach is taken because relatively-positioned elements could still overlap the pop-up panel if they exist at higher levels of the DOMhierarchy, even if their z-index is less than the <literal>&lt;rich:popupPanel&gt;</literal> component.</simpara>
<simpara>If the <literal>&lt;rich:popupPanel&gt;</literal> is to participate in submitting child components/behaviors, then a form element must be nested within the <literal>&lt;rich:popupPanel&gt;</literal>. Alternatively, if no overlapping elements exist, the <literal>&lt;rich:popupPanel&gt;</literal> component can be reattached to its original DOMelement by setting <literal>domElementAttachment</literal> to either <literal>parent</literal> or <literal>form</literal>.</simpara>

  
</important>

</section>
<section id="sect-Component_Reference-richpopupPanel-Modal_and_non-modal_panels">
  <title>Modal and non-modal panels</title>
  <simpara>By default, the <literal>&lt;rich:popupPanel&gt;</literal> appears as a modal window that blocks interaction with the other objects on the page. To implement a non-modal window instead, set <literal>modal="false"</literal>. This will allow interaction with other objects outside the pop-up panel.</simpara>

</section>
<section id="sect-Component_Reference-richpopupPanel-Size_and_positioning">
  <title>Size and positioning</title>
  <simpara>The pop-up panel can be both re-sized and re-positioned by the user. The minimum possible size for the panel can be set with the <literal>minWith</literal> and <literal>minHeight</literal> attributes. These abilities can be deactivated by setting <literal>resizable</literal> or <literal>movable</literal> to <literal>false</literal> as necessary.</simpara>
<simpara>The pop-up panel can be automatically sized when it is shown if the <literal>autosized</literal> attribute is set to <literal>true</literal>.</simpara>
<note>
  <title>Embedded objects in the panel</title>
  
<simpara>Embedded objects inserted into the HTMLwith the <literal>&lt;embed&gt;</literal> tag could be rendered in front of a <literal>&lt;rich:popupPanel&gt;</literal> component in some browsers. The <literal>&lt;rich:popupPanel&gt;</literal> component can be forcibly rendered in front of these objects by setting <literal>overlapEmbedObjects="true"</literal>.</simpara>
<simpara>However, due to the additional script processing required when using the <literal>overlapEmbedObjects</literal> attribute, applications can suffer from decreased performance. As such, <literal>overlapEmbedObjects</literal> should only be set to <literal>true</literal> when <literal>&lt;embed&gt;</literal> or <literal>&lt;object&gt;</literal> tags are being used in the parent view. Do not set it to <literal>true</literal> for applications that do not require it.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-richpopupPanel-Header_and_controls">
  <title>Header and controls</title>
  <simpara>A panel header and associated controls can be added to the <literal>&lt;rich:popupPanel&gt;</literal> component through the use of facets. The <literal>header</literal> facet displays a title for the panel, and the <literal>controls</literal> facet can be customized to allow window controls such as a button for closing the pop-up. <xref linkend="exam-Component_Reference-richpopupPanel-Header_and_controls"/> demonstrates the use of the facets.</simpara>
<example id="exam-Component_Reference-richpopupPanel-Header_and_controls">
  <title>Header and controls</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:commandLink value="Show pop-up"&gt;
    &lt;rich:componentControl target="popup" operation="show" /&gt;
&lt;/h:commandLink&gt;
...
&lt;rich:popupPanel id="popup" modal="false" autosized="true" resizeable="false"&gt;
    &lt;f:facet name="header"&gt;
        &lt;h:outputText value="The title of the panel" /&gt;
    &lt;/f:facet&gt;
    &lt;f:facet name="controls"&gt;
        &lt;h:graphicImage value="/pages/close.png" style="cursor:pointer" onclick="#{rich:component('popup')}.hide()" /&gt;
    &lt;/f:facet&gt;
    &lt;p&gt;
        This is the content of the panel.
    &lt;/p&gt;
&lt;/rich:popupPanel&gt;
</programlisting>


<blockquote>
  
  

<figure>
  <title>Header and controls</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richpopupPanel-Header_and_controls.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richpopupPanel-Header_and_controls</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>

</section>
<section id="sect-Component_Reference-richpopupPanel-Contents_of_the_pop-up">
  <title>Contents of the pop-up</title>
  <simpara>The <literal>&lt;rich:popupPanel&gt;</literal> component can contain any other rich component just like a normal panel.</simpara>
<simpara>Contents of the <literal>&lt;rich:popupPanel&gt;</literal> component which are positioned relatively may be trimmed if they extend beyond the borders of the pop-up panel. For certain in-line controls this behavior may be preferable, but for other dynamic controls it could be undesirable. If the <literal>trimOverlayedElements</literal> attribute is set to <literal>false</literal> then child components will not be trimmed if they extend beyond the borders of the pop-up panel. For example, if using a calendar, select, or other pop-up component, set <literal>trimOverlayedElements="false"</literal>.</simpara>

</section>
<section id="sect-Component_Reference-richpopupPanel-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:popupPanel&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getTop()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the top co-ordinate for the position of the pop-up panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getLeft()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the left co-ordinate for the position of the pop-up panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>moveTo(top,left)</literal>
    </term>
    
    <listitem>
      
      <simpara>Move the pop-up panel to the co-ordinates specified with the <literal>top</literal> and <literal>left</literal> parameters.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>resize(width,height)</literal>
    </term>
    
    <listitem>
      
      <simpara>Resize the pop-up panel to the size specified with the <literal>width</literal> and <literal>height</literal> parameters.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>show()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the pop-up panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hide()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the pop-up panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richpopupPanel-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.PopupPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPopupPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.PopupPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PopupPanelRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richpopupPanel-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richpopupPanel-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-btn</literal>:: This class defines styles for the pop-up panel button.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-shade</literal>:: This class defines styles for the shading that covers the page when presenting a modal pop-up panel.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-cntr</literal>:: This class defines styles for the container for the pop-up panel.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-hdr</literal>:: This class defines styles for the header of the pop-up panel.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-hdr-cnt</literal>:: This class defines styles for the content of the header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-cnt</literal>:: This class defines styles for the content of the pop-up panel.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-cnt-scrlr</literal>:: This class defines styles for the scroll bars of the pop-up panel.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pp-hndlr</literal>:: This class defines styles for borders of the pop-up panel. The border handler is used to re-size the panel.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Panels-richtabPanel">
  <title><literal>&lt;rich:tabPanel&gt;</literal></title>
  <simpara>The <literal>&lt;rich:tabPanel&gt;</literal> component provides a set of tabbed panels for displaying one panel of content at a time. The tabs can be highly customized and themed. Each tab within a <literal>&lt;rich:tabPanel&gt;</literal> container is a <literal>&lt;rich:tab&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-Panels-richtab"/> for further details on the <literal>&lt;rich:tab&gt;</literal> component.</simpara>
<figure id="figu-Component_Reference-richtabPanel-richtabPanel_component">
  <title>A <literal>&lt;rich:tabPanel&gt;</literal> component containing three <literal>&lt;rich:tab&gt;</literal> components</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richtabPanel-richtabPanel_component.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richtabPanel-richtabPanel_component</phrase></textobject>
  </mediaobject>
</figure>
<note>
  <title>Form elements required</title>
  
<simpara>All <literal>&lt;rich:tabPanel&gt;</literal> components should be wrapped in a form element when using either <literal>ajax</literal> or <literal>server</literal> mode, as usual for submitting components.</simpara>

  
</note>
<section id="sect-Component_Reference-richtabPanel-Switching_tabs">
  <title>Switching panels</title>
  <simpara>The <literal>activeItem</literal> attribute holds the active tab name. This name is a reference to the <literal>name</literal> identifier of the active child <literal>&lt;rich:tab&gt;</literal> component.</simpara>
<simpara>The switching mode for performing submissions is determined by the <literal>switchType</literal> attribute, which can have one of the following three values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>server</literal>
    </term>
    
    <listitem>
      
      <simpara>The default setting. Activation of a <literal>&lt;rich:tab&gt;</literal> component causes the parent <literal>&lt;rich:tabPanel&gt;</literal> component to perform a common submission, completely refreshing the page. Only one tab at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>Activation of a <literal>&lt;rich:tab&gt;</literal> component causes the parent <literal>&lt;rich:tabPanel&gt;</literal> component to perform an Ajax form submission, and the content of the tab panel is refreshed. Only one tab at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>Activation of a <literal>&lt;rich:tab&gt;</literal> component causes the parent <literal>&lt;rich:tabPanel&gt;</literal> component to update on the client side. All the tabs are rendered to the client during the initial page render. JavaScript changes the styles such that one tab becomes hidden while the other is shown.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtabPanel-richtabPanel_client-side_events">
  <title><literal>&lt;rich:tabPanel&gt;</literal> client-side events</title>
  <simpara>In addition to the standard Ajax events and HTML events, the <literal>&lt;rich:tabPanel&gt;</literal> component uses the client-side events common to all switchable panels:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>itemchange</literal> event points to the function to perform when the switchable item is changed.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>beforeitemchange</literal> event points to the function to perform when before the switchable item is changed.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtabPanel-richtabPanel_server-side_events">
  <title><literal>&lt;rich:tabPanel&gt;</literal> server-side events</title>
  <simpara>The <literal>&lt;rich:tabPanel&gt;</literal> component uses the server-side events common to all switchable panels:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>ItemChangeEvent</literal> event occurs on the server side when an item is changed through Ajax using the <literal>server</literal> mode. It can be processed using the <literal>ItemChangeListener</literal> attribute. Refer to <xref linkend="sect-Component_Reference-Panels-richitemChangeListener"/> for details on the <literal>&lt;rich:itemChangeListener&gt;</literal> tag.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtabPanel-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:tabPanel&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions, which are common to all switchable panels:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getItems()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return an array of the tabs contained in the tab panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getItemsNames()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return an array of the names of the tabs contained in the tab panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>switchToItem(itemName)</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to and display the item identified by the <literal>itemName</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>firstItem()</literal>:: <literal>prevItem()</literal>:: <literal>nextItem()</literal>:: <literal>lastItem()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the name of the first item, the previous item, the next item, or the last item.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtabPanel-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.TabPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITabPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.TabPanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.TabPanelRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.TogglePanelTagHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtabPanel-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richtabPanel-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr</literal>:: This class defines styles for a tab header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-act</literal>:: This class defines styles for a tab header when it is active.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-inact</literal>:: This class defines styles for a tab header when it is inactive.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-dis</literal>:: This class defines styles for a tab header when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-tabline-vis</literal>:: This class defines styles for the header tab line when it is visible.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-tabs</literal>:: This class defines styles for the tabs in the header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-spcr</literal>:: This class defines styles for the tab header spacer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-lbl</literal>:: This class defines styles for the tab label.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdn</literal>:: This class defines styles for the tab when it is hidden.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-scrl-lft</literal>:: <literal>.rf-tab-hdr-scrl-rgh</literal>:: These classes define styles for the left and right controls for the tab header scroller.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-tablst</literal>:: This class define styles for the tab header list.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-hdr-brd</literal>:: This class define styles for the tab header border.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tab-cnt</literal>:: This class define styles for the content of the tab panel.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>
<section id="sect-Component_Reference-Panels-richtab">
  <title><literal>&lt;rich:tab&gt;</literal></title>
  <simpara>The <literal>&lt;rich:tab&gt;</literal> component represents an individual tab inside a <literal>&lt;rich:tabPanel&gt;</literal> component, including the tab&#8217;s content. Clicking on the tab header will bring its corresponding content to the front of other tabs.</simpara>
<section id="sect-Component_Reference-richtab-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage of the <literal>&lt;rich:tab&gt;</literal> component requires only the tab header and tab content. No additional attributes are required.</simpara>
<simpara>The <literal>header</literal> attribute provides the text on the tab header. The content of the tab is then detailed inside the <literal>&lt;rich:tab&gt;</literal> tags.</simpara>
<simpara>Alternatively, the <literal>header</literal> facet could be used in place of the <literal>header</literal> attribute. This would allow custom components to be applied to the tab header. The component also supports three facets to customize the appearance depending on the current state of the tab:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>headerActive</literal>  facet
    </term>
    
    <listitem>
      
      <simpara>This facet is used when the tab is the currently active tab.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>headerInactive</literal>  facet
    </term>
    
    <listitem>
      
      <simpara>This facet is used when the tab is not currently active.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>headerDisabled</literal>  facet
    </term>
    
    <listitem>
      
      <simpara>This facet is used when the tab is disabled.
The <literal>header</literal> facet is used in place of any state-based facet that has not been defined.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtab-Switching_tabs">
  <title>Switching tabs</title>
  <simpara>The switching mode for performing submissions can be inherited from the <literal>switchType</literal> attribute of the parent <literal>&lt;rich:tabPanel&gt;</literal> component, or set individually for each <literal>&lt;rich:tab&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-Panels-richtabPanel"/> for details on the <literal>switchType</literal> attribute.</simpara>
<simpara>An individual tab can be disabled by setting <literal>disabled="true"</literal>. Disabled tabs cannot be activated or switched to.</simpara>

</section>
<section id="sect-Component_Reference-richtab-richtab_client-side_events">
  <title><literal>&lt;rich:tab&gt;</literal> client-side events</title>
  <simpara>In addition to the standard HTML events, the <literal>&lt;rich:tab&gt;</literal> component uses the client-side events common to all switchable panel items:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>enter</literal> event points to the function to perform when the mouse enters the tab.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>leave</literal> attribute points to the function to perform when the mouse leaves the tab.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtab-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Tab</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITab</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Tab</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.TabRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtab-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <simpara>The <literal>&lt;rich:tab&gt;</literal> component uses the same styles as those applied to the parent <literal>&lt;rich:tabPanel&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-richtabPanel-Style_classes_and_skin_parameters"/> for details.</simpara>

</section>

</section>

</section>
<section id="sect-Component_Reference-Panels-richtogglePanel">
  <title><literal>&lt;rich:togglePanel&gt;</literal></title>
  <simpara>The <literal>&lt;rich:togglePanel&gt;</literal> component is used as a base for the other switchable components, the <literal>&lt;rich:accordion&gt;</literal> component and the <literal>&lt;rich:tabPanel&gt;</literal> component. It provides an abstract switchable component without any associated markup. As such, the <literal>&lt;rich:togglePanel&gt;</literal> component could be customized to provide a switchable component when neither an accordion component or a tab panel component is appropriate.</simpara>
<simpara>The <literal>&lt;rich:togglePanel&gt;</literal> component acts as a wrapper for multiple <literal>&lt;rich:togglePanelItem&gt;</literal> components. Each child component is displayed after being activated with the <literal>&lt;rich:toggleControl&gt;</literal> behavior.</simpara>
<simpara>Refer to <xref linkend="sect-Component_Reference-Panels-richtoggleControl"/> and <xref linkend="sect-Component_Reference-Panels-richtogglePanel"/> for details on how to use the components together.</simpara>
<section id="sect-Component_Reference-richtogglePanel-Basic_usage">
  <title>Basic usage</title>
  <simpara>The initial state of the component can be configured using the <literal>activeItem</literal> attribute, which points to a child component to display. Alternatively, if no <literal>activeItem</literal> attribute is defined, the initial state will be blank until the user activates a panel component with a connected <literal>&lt;rich:toggleControl&gt;</literal> behavior.</simpara>
<simpara>The child components are shown in the order in which they are defined in the view, as shown in <xref linkend="exam-Component_Reference-richtogglePanel-Basic_usage"/>.</simpara>
<note>
  <title>Form elements required</title>
  
<simpara>All <literal>&lt;rich:tabPanel&gt;</literal> components should be wrapped in a form element when using either <literal>ajax</literal> or <literal>server</literal> mode, as usual for submitting components.</simpara>

  
</note>
<example id="exam-Component_Reference-richtogglePanel-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:togglePanel id="layout" activeItem="item1"&gt;
   &lt;rich:togglePanelItem id="item1"&gt;
      &lt;!--content--&gt;
   &lt;/rich:togglePanelItem&gt;
   &lt;rich:togglePanelItem id="item2"&gt;
      &lt;!--content--&gt;
   &lt;rich:togglePanelItem&gt;
&lt;/rich:togglePanel&gt;
&lt;h:commandButton&gt;
   &lt;rich:toggleControl targetPanel="layout"/&gt; &lt;!--cycles through the states--&gt;
&lt;/h:commandButton&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richtab-Repeating_panels">
  <title>Dynamic panel item generation</title>
  <simpara>All the switchable components ( <literal>&lt;rich:togglePanel&gt;</literal>, <literal>&lt;rich:accordion&gt;</literal> component and the <literal>&lt;rich:tabPanel&gt;</literal>) can leverage the <literal>&lt;a4j:repeat&gt;</literal> tag to dynamically create child components. This can be useful when the definition of the panel items is determined at run-time from a backing bean list.</simpara>

</section>
<section id="sect-Component_Reference-richtogglePanel-Toggling_between_panels">
  <title>Toggling between components</title>
  <simpara>The switching mode for performing submissions is determined by the <literal>switchType</literal> attribute, which can have one of the following three values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>server</literal>
    </term>
    
    <listitem>
      
      <simpara>The default setting. Activation of a child component causes the parent <literal>&lt;rich:togglePanel&gt;</literal> component to perform a common submission, completely refreshing the page. Only one child at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>Activation of a child component causes the parent <literal>&lt;rich:togglePanel&gt;</literal> component to perform an Ajax form submission, and the content of the panel is refreshed. Only one child at a time is rendered to the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>Activation of a child component causes the parent <literal>&lt;rich:togglePanel&gt;</literal> component to update on the client side. All the items are rendered to the client side during the initial page render. JavaScript changes the styles such that one child component becomes hidden while the other is shown.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtogglePanel-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:togglePanel&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions, which are common to all switchable panels:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getItems()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return an array of the items contained in the toggle panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getItemsNames()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return an array of the names of the items contained in the toggle panel.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>switchToItem(itemName)</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to and display the item identified by the <literal>itemName</literal> string passed as a parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>firstItem()</literal>:: <literal>prevItem()</literal>:: <literal>nextItem()</literal>:: <literal>lastItem()</literal>
    </term>
    
    <listitem>
      
      <simpara>Get the name of the first item, the previous item, the next item, or the last item.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtogglePanel-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.TogglePanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITogglePanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.TogglePanel</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.TogglePanelRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.TogglePanelTagHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-Panels-richitemChangeListener">
  <title><literal>&lt;rich:itemChangeListener&gt;</literal></title>
  <simpara>Use the <literal>&lt;rich:itemChangeListener&gt;</literal> tag to register an <literal>ItemChangeListener</literal> class on a parent panel component. The class provided as a listener must implement the org.richfaces.event.ItemChangeListenerinterface. The processItemChangemethod accepts an <literal>org.richface.event.ItemChangeEvent</literal> event as a parameter.</simpara>
<simpara>The <literal>&lt;rich:itemChangeListener&gt;</literal> tag can be used with any of the switchable panel components:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>&lt;rich:togglePanel&gt;</literal> (refer to <xref linkend="sect-Component_Reference-Panels-richtogglePanel"/>)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>&lt;rich:accordion&gt;</literal> (refer to <xref linkend="sect-Component_Reference-Panels-richaccordion"/>)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>&lt;rich:tabPanel&gt;</literal> (refer to <xref linkend="sect-Component_Reference-Panels-richtabPanel"/>)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>&lt;rich:panelMenu&gt;</literal> (refer to <xref linkend="sect-Component_Reference-Menus_and_toolbars-richpanelMenu"/>)</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-Panels-richtoggleControl">
  <title><literal>&lt;rich:toggleControl&gt;</literal></title>
  <simpara>The <literal>&lt;rich:toggleControl&gt;</literal> behavior can be attached to any interface component, whether inside or outside the controlled panel itself. It works with a <literal>&lt;rich:togglePanel&gt;</literal> component to switch between different <literal>&lt;rich:togglePanelItem&gt;</literal> components. Refer to <xref linkend="sect-Component_Reference-Panels-richtogglePanel"/> and <xref linkend="sect-Component_Reference-Panels-richtogglePanelItem"/> for details on how to use the components together.</simpara>
<simpara>The <literal>&lt;rich:toggleControl&gt;</literal> implements the JSF <literal>BehaviorHolder</literal> component, which provides events to attached components and behaviors.</simpara>
<section id="sect-Component_Reference-richtoggleControl-Basic_usage">
  <title>Basic usage</title>
  <simpara>If the <literal>&lt;rich:toggleControl&gt;</literal> component is positioned inside a <literal>&lt;rich:togglePanel&gt;</literal> component, no panel attachment attributes need to be defined, as the control is assumed to switch through the <literal>&lt;rich:togglePanelItem&gt;</literal> components of its parent <literal>&lt;rich:togglePanel&gt;</literal> component.</simpara>
<simpara>A <literal>&lt;rich:toggleControl&gt;</literal> component can be located outside the <literal>&lt;rich:togglePanel&gt;</literal> component it needs to switch. Where this is the case, the <literal>&lt;rich:togglePanel&gt;</literal> is identified using the <literal>targetPanel</literal> attribute.</simpara>

</section>
<section id="sect-Component_Reference-richtoggleControl-Specifying_the_next_state">
  <title>Specifying the next state</title>
  <simpara>The <literal>&lt;rich:toggleControl&gt;</literal> component can switch the attached <literal>&lt;rich:togglePanel&gt;</literal> component in multiple ways:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>By default, the <literal>&lt;rich:toggleControl&gt;</literal> component will cycle through <literal>&lt;rich:togglePanelItem&gt;</literal> components in the order they are defined within the view.</simpara>
      
    </listitem>
  
</itemizedlist>

<example>
  <title>Default switching</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:togglePanel id="layout"&gt;
   &lt;rich:togglePanelItem&gt;
      &lt;!--content--&gt;
   &lt;/rich:togglePanelItem&gt;
   &lt;rich:togglePanelItem&gt;
      &lt;!--content--&gt;
   &lt;rich:togglePanelItem&gt;
&lt;/rich:togglePanel&gt;
&lt;h:commandButton&gt;
   &lt;rich:toggleControl targetPanel="layout"/&gt; &lt;!--cycles through the states--&gt;
&lt;/h:commandButton&gt;
</programlisting>



</example>

<itemizedlist>
  
  
    <listitem>
      <simpara>The next item to switch to can be explicitly defined by including a <literal>&lt;rich:toggleControl&gt;</literal> component within a <literal>&lt;rich:togglePanelItem&gt;</literal> component. Point the <literal>targetItem</literal> to the <literal>&lt;rich:togglePanelItem&gt;</literal> to switch to when the state is next changed.</simpara>
      
    </listitem>
  
</itemizedlist>

<example>
  <title>Explicit switching</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:togglePanel activeItem="item1"&gt;
   &lt;rich:togglePanelItem id="item1"&gt;
      &lt;!--content--&gt;
      &lt;h:commandButton&gt;
         &lt;rich:toggleControl targetItem="item2"&gt; &lt;!--switches to item2 --&gt;
      &lt;/h:commandButton&gt;
   &lt;/rich:togglePanelItem&gt;
   &lt;rich:togglePanelItem id="item2"&gt;
      &lt;!--content--&gt;
      &lt;h:commandButton&gt;
         &lt;rich:toggleControl targetItem="item1"&gt; &lt;!--switches to item1 --&gt;
      &lt;/h:commandButton&gt;
   &lt;rich:togglePanelItem&gt;
&lt;/rich:togglePanel&gt;
</programlisting>



</example>

<itemizedlist>
  
  
    <listitem>
      <simpara>Alternatively, use the <literal>targetItem</literal> attribute with keywords to switch items. The <literal>@first</literal>, <literal>@prev</literal>, <literal>@next</literal>, and <literal>@last</literal> keywords switch to the first item, the previous item, the next item, and the last item respectively.</simpara>
      
    </listitem>
  
</itemizedlist>

<example>
  <title>Keyword-based switching</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:togglePanel activeItem="item1"&gt;
   &lt;rich:togglePanelItem id="item1"&gt;
      &lt;!--content--&gt;
      &lt;h:commandButton&gt;
         &lt;rich:toggleControl targetItem="@next"&gt; &lt;!--switches to next item (item2)--&gt;
      &lt;/h:commandButton&gt;
   &lt;/rich:togglePanelItem&gt;
   &lt;rich:togglePanelItem id="item2"&gt;
      &lt;!--content--&gt;
      &lt;h:commandButton&gt;
         &lt;rich:toggleControl targetItem="@prev"&gt; &lt;!--switches to previous item (item1)--&gt;
      &lt;/h:commandButton&gt;
   &lt;rich:togglePanelItem&gt;
&lt;/rich:togglePanel&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richtoggleControl-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>client-behavior-renderer-type</literal>: <literal>org.richfaces.component.behavior.ToggleControl</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-id</literal>: <literal>org.richfaces.component.behavior.ToggleControl</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.CustomBehaviorHandler</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-class</literal>: <literal>org.richfaces.component.behavior.ToggleControl</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client-behavior-renderer-class</literal>: <literal>org.richfaces.renderkit.html.ToggleControlRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Panels-richtogglePanelItem">
  <title><literal>&lt;rich:togglePanelItem&gt;</literal></title>
  <simpara>The <literal>&lt;rich:togglePanelItem&gt;</literal> component is a switchable panel for use with the <literal>&lt;rich:togglePanel&gt;</literal> component. Use the <literal>&lt;rich:togglePanelItem&gt;</literal> component to define the content for a panel using nested components. Switching between <literal>&lt;rich:togglePanelItem&gt;</literal> components is handled by the <literal>&lt;rich:toggleControl&gt;</literal> behavior.</simpara>
<section id="sect-Component_Reference-richtogglePanelItem-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.TogglePanelItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITogglePanelItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.TogglePanelItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.TogglePanelItemRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Tables_and_grids">
  <title>Tables and grids</title>
  <simpara>This chapter covers all components related to the display of tables and grids.</simpara>
<section id="sect-Component_Reference-Actions-a4jrepeat">
  <title><literal>&lt;a4j:repeat&gt;</literal></title>
  <simpara>The non-visual <literal>&lt;a4j:repeat&gt;</literal> component is used to iterate through a data model. The component renders child content for every iteration according to the current object data.</simpara>
<simpara>The <literal>&lt;a4j:repeat&gt;</literal> component extends the standard <literal>UIRepeat</literal> component to allow partial updates within iterations while sending Ajax requests. The component acts as a base for all the data iteration components detailed in this chapter.</simpara>
<section id="sect-Component_Reference-a4jrepeat-Basic_usage">
  <title>Basic usage</title>
  <simpara>The contents of the collection are determined using Expression Language ( EL). The data model for the contents is specified with the <literal>value</literal> attribute. The <literal>var</literal> attribute names the object to use when iterating through the collection. This object is then referenced in the relevant child components. <xref linkend="exam-Component_Reference-a4jrepeat-a4jrepeat_example"/> shows how to use <literal>&lt;a4j:repeat&gt;</literal> to maintain a simple table.</simpara>
<example id="exam-Component_Reference-a4jrepeat-a4jrepeat_example">
  <title><literal>&lt;a4j:repeat&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;table&gt;
    &lt;tbody&gt;
        &lt;a4j:repeat value="#{repeatBean.items}" var="item"&gt;
            &lt;tr&gt;
                &lt;td&gt;&lt;h:outputText value="#{item.code}" id="item1" /&gt;&lt;/td&gt;
                &lt;td&gt;&lt;h:outputText value="#{item.price}" id="item2" /&gt;&lt;/td&gt;
            &lt;/tr&gt;
        &lt;/a4j:repeat&gt;
    &lt;/tbody&gt;
&lt;/table&gt;
</programlisting>


<simpara>Each row of a table contains two cells: one showing the item code, and the other showing the item price. The table is generated by iterating through items in the <literal>repeatBeans.items</literal> data model.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jrepeat-Limited_views_and_partial_updates">
  <title>Limited views and partial updates</title>
  <simpara>The <literal>&lt;a4j:repeat&gt;</literal> component uses other attributes common to iteration components, such as the <literal>first</literal> attribute for specifying the first item for iteration, and the <literal>rows</literal> attribute for specifying the number of rows of items to display.</simpara>
<simpara>Specific cells, rows, and columns can be updated without sending Ajax requests for the entire collection. Components that cause the change can specify which part of the table to update through the <literal>render</literal> attribute. The <literal>render</literal> attribute specifies which part of a table to update. The updated parts relate to where the action component is placed relative to the table:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      Action components inside the table
    </term>
    
    <listitem>
      
      <simpara>Use <literal>render=componentID</literal> where the component identified by <emphasis><literal>componentID</literal></emphasis> is in the same row as the action component. The action component updates the single specified component, as demonstrated in <xref linkend="exam-Component_Reference-a4jrepeat-Update_a_single_component"/>.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<example id="exam-Component_Reference-a4jrepeat-Update_a_single_component">
  <title>Update a single component</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:column&gt;
   &lt;a4j:commandButton render="col"&gt;&lt;/a4j:commandButton&gt;
&lt;/rich:column&gt;
&lt;rich:column&gt;
   &lt;h:outputText value="#{car.model}" id="col"/&gt;
&lt;/rich:column&gt;
</programlisting>



</example>

<variablelist>
  
  
  <varlistentry>
    <term>
      Action components outside the table
    </term>
    
    <listitem>
      
      <simpara>Use <literal>render=tableId:rowId:cellId</literal> to specify the cell to update. The action component updates the cell with an identifier of <emphasis><literal>cellId</literal></emphasis>, which is within the row with an identifier of <emphasis><literal>rowId</literal></emphasis>, which is within the table with an identifier of <emphasis><literal>tableId</literal></emphasis>.
Instead of a specific identifier, any of the references could be variables, as demonstrated in <xref linkend="exam-Component_Reference-a4jrepeat-Use_variables_to_specify_references"/>.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<example>
  <title>Use variables to specify references</title>


<programlisting language="XML" linenumbering="unnumbered">render=tableId:@rows(bean.rowToUpdate):cellId</programlisting>


<simpara>The @rows function accepts a collection of row keys to be updated.
Similarly the table@body shorthand can be used to specify that the entire table body should be updated.</simpara>

</example>

</section>
<section id="sect-Component_Reference-a4jrepeat-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Repeat</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIRepeat</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Data</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.RepeatRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.html.RepeatHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richdataTable">
  <title><literal>&lt;rich:dataTable&gt;</literal></title>
  <simpara>The <literal>&lt;rich:dataTable&gt;</literal> component is used to render a table, including the table&#8217;s caption. It works in conjunction with the <literal>&lt;rich:column&gt;</literal> and <literal>&lt;rich:columnGroup&gt;</literal> components to list the contents of a data model.</simpara>
<note>
  <title><literal>&lt;rich:extendedDataTable&gt;</literal></title>
  
<simpara>The <literal>&lt;rich:dataTable&gt;</literal> component does not include extended table features, such as data scrolling (including lazy Ajax loading), row selection, and column reordering. These features are available as part of the <literal>&lt;rich:extendedDataTable&gt;</literal> component; refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richextendedDataTable"/> for further details.</simpara>

  
</note>
<section id="sect-Component_Reference-richdataTable-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>value</literal> attribute points to the data model, and the <literal>var</literal> attribute specifies a variable to use when iterating through the data model.</simpara>
<simpara>In addition, the table requires a set of <literal>&lt;rich:column&gt;</literal> components to define the content of the table.</simpara>

</section>
<section id="sect-Component_Reference-richdataTable-Customizing_the_table">
  <title>Customizing the table</title>
  <simpara>The <literal>first</literal> attribute specifies which item in the data model to start from, and the <literal>rows</literal> attribute specifies the number of items to list. The <literal>header</literal>, <literal>footer</literal>, and <literal>caption</literal> facets can be used to display text, and to customize the appearance of the table through skinning. demonstrates a simple table implementation.</simpara>
<simpara>The <literal>keepSaved</literal> attribute defines whether this iteration component will reset saved children&#8217;s state before rendering. By default, the state is reset if there are no faces messages with severity error or higher.</simpara>
<example id="exam-Component_Reference-richdataTable-richdataTable_example">
  <title><literal>&lt;rich:dataTable&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"&gt;
    &lt;f:facet name="caption"&gt;
        &lt;h:outputText value="United States Capitals" /&gt;
    &lt;/f:facet&gt;
    &lt;f:facet name="header"&gt;
        &lt;h:outputText value="Capitals and States Table" /&gt;
    &lt;/f:facet&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;State Flag&lt;/f:facet&gt;
            &lt;h:graphicImage value="#{cap.stateFlag}"/&gt;
        &lt;f:facet name="footer"&gt;State Flag&lt;/f:facet&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;State Name&lt;/f:facet&gt;
            &lt;h:outputText value="#{cap.state}"/&gt;
        &lt;f:facet name="footer"&gt;State Name&lt;/f:facet&gt;
    &lt;/rich:column&gt;
    &lt;rich:column &gt;
        &lt;f:facet name="header"&gt;State Capital&lt;/f:facet&gt;
            &lt;h:outputText value="#{cap.name}"/&gt;
        &lt;f:facet name="footer"&gt;State Capital&lt;/f:facet&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;Time Zone&lt;/f:facet&gt;
            &lt;h:outputText value="#{cap.timeZone}"/&gt;
        &lt;f:facet name="footer"&gt;Time Zone&lt;/f:facet&gt;
    &lt;/rich:column&gt;
    &lt;f:facet name="footer"&gt;
        &lt;h:outputText value="Capitals and States Table" /&gt;
    &lt;/f:facet&gt;
&lt;/rich:dataTable&gt;

</programlisting>


<blockquote>
  
  

<figure>
  <title><literal>&lt;rich:dataTable&gt;</literal> example</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richdataTable_example.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richdataTable_example</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>
<simpara>For details on filtering and sorting data tables, refer to <xref linkend="sect-Component_Reference-Tables_and_grids-Table_filtering"/> and <xref linkend="sect-Component_Reference-Tables_and_grids-Table_sorting"/>.</simpara>

</section>
<section id="sect-Component_Reference-richdataTable-Partial_updates">
  <title>Partial updates</title>
  <simpara>As <literal>&lt;rich:dataTable&gt;</literal> the component is based on the <literal>&lt;a4j:repeat&gt;</literal> component, it can be partially updated with Ajax. Refer to <xref linkend="sect-Component_Reference-a4jrepeat-Limited_views_and_partial_updates"/> for details on partially updating the <literal>&lt;rich:dataTable&gt;</literal> component.</simpara>
<simpara>The <literal>&lt;rich:dataTable&gt;</literal> component supports master-detail markup with collapsible sub-table sections. Refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richcollapsibleSubTable"/> for full details on using the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component.</simpara>
<simpara>Use the <literal>rows</literal> attribute to specify the number of rows to show at a time. The table is then presented in pages of rows. Pages can be navigated by using a control such as the <literal>&lt;rich:dataScroller&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richdataScroller"/> for full details on using the <literal>&lt;rich:dataScroller&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richdataTable-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:dataTable&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>expandAllSubTables()</literal>
    </term>
    
    <listitem>
      
      <simpara>Expand any sub-tables contained in the data table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>collapseAllSubTables()</literal>
    </term>
    
    <listitem>
      
      <simpara>Collapse any sub-tables contained in the data table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>switchSubTable(subtableId)</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch the expanded or collapsed state of any sub-tables contained in the data table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>filter(columnId, newFilterValue, \[isClearPreviousFilters\])</literal>
    </term>
    
    <listitem>
      
      <simpara>Filter the table based on the column specified with the <literal>columnId</literal> parameter. Use the <literal>newFilterValue</literal> parameter as the filter value. The optional <literal>isClearPreviousFilters</literal> parameter is a boolean value which, if set to <literal>true</literal>, will clear any previous filters applied to the table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>sort(columnId, \[direction\], \[isClearPreviousSorting\])</literal>
    </term>
    
    <listitem>
      
      <simpara>Sort the table based on the column specified with the <literal>columnId</literal> parameter. The option <literal>direction</literal> parameter specifies whether to sort in ascending or descending order. The optional <literal>isClearPreviousSorting</literal> parameter is a boolean value which, if set to <literal>true</literal>, will clear any previous sorting applied to the table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richdataTable-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.DataTable</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIDataTable</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Data</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.DataTableRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.DataTableHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richdataTable-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richdataTable-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt</literal>:: This class defines styles for the table.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-left-width, border-top-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-left-color, border-top-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-cap</literal>:: This class defines styles for the table caption.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-r</literal>:: This class defines styles for a table row.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-fst-r</literal>:: This class defines styles for the first row in a table.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-c</literal>:: This class defines styles for a table cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-nd</literal>:: This class defines styles for a node.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-hdr</literal>:: This class defines styles for a table header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-hdr-fst</literal>:: This class defines styles for the first header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-hdr-c</literal>:: This class defines styles for a header cell.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-shdr</literal>:: This class defines styles for a table sub-header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-shdr-fst</literal>:: This class defines styles for the first sub-header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-shdr-c</literal>:: This class defines styles for a sub-header cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-ftr</literal>:: This class defines styles for a table footer.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-ftr-fst</literal>:: This class defines styles for the first footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-ftr-c</literal>:: This class defines styles for a footer cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableFooterBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-sftr</literal>:: This class defines styles for a table sub-footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-sftr-fst</literal>:: This class defines styles for the first sub-footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dt-sftr-c</literal>:: This class defines styles for a sub-footer cell.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableFooterBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richcolumn">
  <title><literal>&lt;rich:column&gt;</literal></title>
  <simpara>The <literal>&lt;rich:column&gt;</literal> component facilitates columns in a table. It supports merging columns and rows, sorting, filtering, and customized skinning.</simpara>
<section id="sect-Component_Reference-richcolumn-Basic_usage">
  <title>Basic usage</title>
  <simpara>In general usage, the <literal>&lt;rich:column&gt;</literal> component is used in the same was as the JavaServer Faces ( JSF) <literal>&lt;h:column&gt;</literal> component. It requires no extra attributes for basic usage, as shown in <xref linkend="exam-Component_Reference-richcolumn-Basic_column_example"/>.</simpara>
<example id="exam-Component_Reference-richcolumn-Basic_column_example">
  <title>Basic column example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;State Flag&lt;/f:facet&gt;
        &lt;h:graphicImage value="#{cap.stateFlag}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;State Name&lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.state}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column &gt;
        &lt;f:facet name="header"&gt;State Capital&lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.name}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;Time Zone&lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.timeZone}"/&gt;
    &lt;/rich:column&gt;
&lt;/rich:dataTable&gt;
</programlisting>


<blockquote>
  
  

<figure>
  <title>Basic column example</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richcolumn-Basic_column_example.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richcolumn-Basic_column_example</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>

</section>
<section id="sect-Component_Reference-richcolumn-Spanning_columns">
  <title>Spanning columns</title>
  <simpara>Columns can be merged by using the <literal>colspan</literal> attribute to specify how many normal columns to span. The <literal>colspan</literal> attribute is used in conjunction with the <literal>breakRowBefore</literal> attribute on the next column to determine how the merged columns are laid out. <xref linkend="exam-Component_Reference-richcolumn-Column_spanning_example"/>.</simpara>
<example id="exam-Component_Reference-richcolumn-Column_spanning_example">
  <title>Column spanning example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"&gt;
	&lt;rich:column colspan="3"&gt;
        &lt;h:graphicImage value="#{cap.stateFlag}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column breakBefore="true"&gt;
        &lt;h:outputText value="#{cap.state}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column &gt;
        &lt;h:outputText value="#{cap.name}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;h:outputText value="#{cap.timeZone}"/&gt;
    &lt;/rich:column&gt;
&lt;/rich:dataTable&gt;
</programlisting>


<blockquote>
  
  

<figure>
  <title>Column spanning example</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richcolumn-Column_spanning_example.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richcolumn-Column_spanning_example</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>

</section>
<section id="sect-Component_Reference-richcolumn-Spanning_rows">
  <title>Spanning rows</title>
  <simpara>Similarly, the <literal>rowspan</literal> attribute can be used to merge and span rows. Again the <literal>breakRowBefore</literal> attribute needs to be used on related <literal>&lt;rich:column&gt;</literal> components to define the layout. <xref linkend="exam-Component_Reference-richcolumn-Row_spanning_example"/> and the resulting <xref linkend="figu-Component_Reference-Complex_headers_using_column_groups-Complex_headers_using_column_groups"/> show the first column of the table spanning three rows.</simpara>
<example id="exam-Component_Reference-richcolumn-Row_spanning_example">
  <title>Row spanning example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5"&gt;
    &lt;rich:column rowspan="3"&gt;
        &lt;f:facet name="header"&gt;State Flag&lt;/f:facet&gt;
        &lt;h:graphicImage value="#{cap.stateFlag}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;State Info&lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.state}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column breakBefore="true"&gt;
        &lt;h:outputText value="#{cap.name}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column breakBefore="true"&gt;
        &lt;h:outputText value="#{cap.timeZone}"/&gt;
    &lt;/rich:column&gt;
&lt;/rich:dataTable&gt;
</programlisting>


<blockquote>
  
  

<figure>
  <title>Row spanning example</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richcolumn-Row_spanning_example.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richcolumn-Row_spanning_example</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>
<simpara>For details on filtering and sorting columns, refer to <xref linkend="sect-Component_Reference-Tables_and_grids-Table_filtering"/> and <xref linkend="sect-Component_Reference-Tables_and_grids-Table_sorting"/>.</simpara>

</section>
<section id="sect-Component_Reference-richcolumn-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Column</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIColumn</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Column</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richcolumnGroup">
  <title><literal>&lt;rich:columnGroup&gt;</literal></title>
  <simpara>The <literal>&lt;rich:columnGroup&gt;</literal> component combines multiple columns in a single row to organize complex parts of a table. The resulting effect is similar to using the <literal>breakRowBefore</literal> attribute of the <literal>&lt;rich:column&gt;</literal> component, but is clearer and easier to follow in the source code.</simpara>
<section id="sect-Component_Reference-richcolumnGroup-Complex_headers">
  <title>Complex headers</title>
  <simpara>The <literal>&lt;rich:columnGroup&gt;</literal> can also be used to create complex headers in a table. <xref linkend="exam-Component_Reference-richcolumnGroup-Complex_headers_using_column_groups"/> and the resulting <xref linkend="figu-Component_Reference-Complex_headers_using_column_groups-Complex_headers_using_column_groups"/> demonstrate how complex headers can be achieved.</simpara>
<example id="exam-Component_Reference-richcolumnGroup-Complex_headers_using_column_groups">
  <title>Complex headers using column groups</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" rows="5" id="sublist"&gt;
    &lt;f:facet name="header"&gt;
        &lt;rich:columnGroup&gt;
            &lt;rich:column rowspan="2"&gt;
                &lt;h:outputText value="State Flag"/&gt;
            &lt;/rich:column&gt;
            &lt;rich:column colspan="3"&gt;
                &lt;h:outputText value="State Info"/&gt;
            &lt;/rich:column&gt;
            &lt;rich:column breakBefore="true"&gt;
                &lt;h:outputText value="State Name"/&gt;
            &lt;/rich:column&gt;
            &lt;rich:column&gt;
                &lt;h:outputText value="State Capital"/&gt;
            &lt;/rich:column&gt;
            &lt;rich:column&gt;
                &lt;h:outputText value="Time Zone"/&gt;
            &lt;/rich:column&gt;
        &lt;/rich:columnGroup&gt;
    &lt;/f:facet&gt;
    &lt;rich:column&gt;
        &lt;h:graphicImage value="#{cap.stateFlag}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;h:outputText value="#{cap.state}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;h:outputText value="#{cap.name}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column&gt;
        &lt;h:outputText value="#{cap.timeZone}"/&gt;
    &lt;/rich:column&gt;
&lt;/rich:dataTable&gt;
</programlisting>


<blockquote>
  
  

<figure>
  <title>Complex headers using column groups</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richcolumnGroup-Complex_headers_using_column_groups.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richcolumnGroup-Complex_headers_using_column_groups</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>

</section>
<section id="sect-Component_Reference-richcolumnGroup-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.ColumnGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIColumnGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.ColumnGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.ColumnGroupRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richcollapsibleSubTable">
  <title><literal>&lt;rich:collapsibleSubTable&gt;</literal></title>
  <simpara>The <literal>&lt;rich:collapsibleSubTable&gt;</literal> component acts as a child element to a <literal>&lt;rich:dataTable&gt;</literal> component. The <literal>&lt;rich:collapsibleSubTable&gt;</literal> component iterates through the child collections in the currently iterated object to create master-detail tables.</simpara>
<simpara>Additionally, the detail part of the table can be collapsed or expanded through different modes. The <literal>&lt;rich:collapsibleSubTable&gt;</literal> component works with the <literal>&lt;rich:collapsibleSubTableToggler&gt;</literal> component, which expands and collapses the sub-tables.</simpara>
<section id="sect-Component_Reference-richcollapsibleSubTable-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:collapsibleSubTable&gt;</literal> component requires the same basic attributes as the <literal>&lt;rich:dataTable&gt;</literal> component. The <literal>value</literal> attribute points to the collection, and the <literal>var</literal> attribute specifies a variable to use when iterating through the collection.</simpara>
<simpara>In addition, the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component typically needs a corresponding <literal>&lt;rich:collapsibleSubTableToggler&gt;</literal> component to allow expanding and collapsing. Declare the <literal>id</literal> identifier on the <literal>&lt;rich:collapsibleSubTable&gt;</literal> element so that the <literal>&lt;rich:collapsibleSubTableToggler&gt;</literal> component can reference it. Refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richcollapsibleSubTableToggler"/> for details on the <literal>&lt;rich:collapsibleSubTableToggler&gt;</literal> component.</simpara>
<example id="exam-Component_Reference-richcollapsibleSubTable-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{carsBean.inventoryVendorLists}" var="list"&gt;
   &lt;f:facet name="header"&gt;
      &lt;rich:columnGroup&gt;
         &lt;rich:column colspan="6"&gt;
            &lt;h:outputText value="Cars marketplace" /&gt;
         &lt;/rich:column&gt;
         &lt;rich:column breakRowBefore="true"&gt;
            &lt;h:outputText value="Model" /&gt;
         &lt;/rich:column&gt;
         &lt;rich:column&gt;
            &lt;h:outputText value="Price" /&gt;
         &lt;/rich:column&gt;
         &lt;rich:column&gt;
            &lt;h:outputText value="Mileage" /&gt;
         &lt;/rich:column&gt;
         &lt;rich:column&gt;
            &lt;h:outputText value="VIN Code" /&gt;
         &lt;/rich:column&gt;
         &lt;rich:column&gt;
            &lt;h:outputText value="Items stock" /&gt;
         &lt;/rich:column&gt;
         &lt;rich:column&gt;
            &lt;h:outputText value="Days Live" /&gt;
         &lt;/rich:column&gt;
      &lt;/rich:columnGroup&gt;
   &lt;/f:facet&gt;
   &lt;rich:column colspan="6"&gt;
      &lt;rich:collapsibleSubTableToggler for="sbtbl" /&gt;
      &lt;h:outputText value="#{list.vendor}" /&gt;
   &lt;/rich:column&gt;
   &lt;rich:collapsibleSubTable value="#{list.vendorItems}" var="item" id="sbtbl"
      expandMode="client"&gt;
      &lt;rich:column&gt;
         &lt;h:outputText value="#{item.model}" /&gt;
      &lt;/rich:column&gt;
      &lt;rich:column&gt;
         &lt;h:outputText value="#{item.price}" /&gt;
      &lt;/rich:column&gt;
      &lt;rich:column&gt;
         &lt;h:outputText value="#{item.mileage}" /&gt;
      &lt;/rich:column&gt;
      &lt;rich:column&gt;
         &lt;h:outputText value="#{item.vin}" /&gt;
      &lt;/rich:column&gt;
      &lt;rich:column&gt;
         &lt;h:outputText value="#{item.stock}" /&gt;
      &lt;/rich:column&gt;
      &lt;rich:column&gt;
         &lt;h:outputText value="#{item.daysLive}" /&gt;
      &lt;/rich:column&gt;
      &lt;f:facet name="footer"&gt;
         &lt;h:outputText value="Total of #{list.vendor} Cars: #{list.count}" /&gt;
      &lt;/f:facet&gt;
   &lt;/rich:collapsibleSubTable&gt;
&lt;/rich:dataTable&gt;
</programlisting>


<simpara>The resulting tables contains multiple sub-tables, grouping the list of cars by vendor. Each sub-table can be expanded or collapsed using the toggle with the vendor&#8217;s name. The screenshot shows all sub-tables collapsed except for the sub-table for Ford cars.</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-richcollapsibleSubTable-Basic_usage.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richcollapsibleSubTable-Basic_usage</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A data table containing multiple collapsible sub-tables.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richcollapsibleSubTable-Expanding_and_collapsing_the_sub-table">
  <title>Expanding and collapsing the sub-table</title>
  <simpara>Use the boolean <literal>expanded</literal> attribute to control the current state of the sub-table.</simpara>
<simpara>The switching mode for performing submissions is determined by the <literal>expandMode</literal> attribute, which can have one of the following three values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>server</literal>
    </term>
    
    <listitem>
      
      <simpara>The default setting. Expansion of the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component performs a common submission, completely re-rendering the page.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>Expansion of the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component performs an Ajax form submission, and the content of the data table is rendered.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>Expansion of the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component updates the data table on the client side.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richcollapsibleSubTable-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.CollapsibleSubTable</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UICollapsibleSubTable</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Data</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.CollapsibleSubTableRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.CollapsibleSubTableHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richcollapsibleSubTable-Style_classes">
  <title>Style classes</title>
  <table id="tabl-richcollapsibleSubTable-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst</literal>:: This class defines styles for the table.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-r</literal>:: This class defines styles for a table row.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-fst-r</literal>:: This class defines styles for the first row in a table.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-c</literal>:: This class defines styles for a table cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-hdr</literal>:: This class defines styles for a table header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-hdr-fst</literal>:: This class defines styles for the first header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-hdr-fst-r</literal>:: This class defines styles for the first row in the header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-hdr-c</literal>:: This class defines styles for a header cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableSubHeaderBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-shdr</literal>:: This class defines styles for a table sub-header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-shdr-fst</literal>:: This class defines styles for the first sub-header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-shdr-c</literal>:: This class defines styles for a sub-header cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableSubHeaderBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-ftr</literal>:: This class defines styles for a table footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-ftr-fst</literal>:: This class defines styles for the first footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-ftr-c</literal>:: This class defines styles for a footer cell.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableSubFooterBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-sftr</literal>:: This class defines styles for a table sub-footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-sftr-fst</literal>:: This class defines styles for the first sub-footer.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-cst-sftr-c</literal>:: This class defines styles for a sub-footer cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableSubFooterBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richcollapsibleSubTableToggler">
  <title><literal>&lt;rich:collapsibleSubTableToggler&gt;</literal></title>
  <simpara>The <literal>&lt;rich:collapsibleSubTableToggler&gt;</literal> component provides a toggle control for the user to expand and collapse sub-tables.</simpara>
<section id="sect-Component_Reference-richcollapsibleSubTableToggler-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:collapsibleSubTableToggler&gt;</literal> component requires the <literal>for</literal> attribute. The <literal>for</literal> attribute references the <literal>id</literal> identifier of the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component to control.</simpara>
<simpara>Refer to <xref linkend="exam-Component_Reference-richcollapsibleSubTable-Basic_usage"/> for an example using the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component. In the example, the toggle control is placed in a column that spans the width of the table. Output text next to the toggle control displays the car vendor&#8217;s name for that sub-table.</simpara>

</section>
<section id="sect-Component_Reference-richcollapsibleSubTableToggler-Appearance">
  <title>Appearance</title>
  <simpara>The icons and labels of the <literal>&lt;rich:collapsibleSubTableToggler&gt;</literal> component can be customized. Use the <literal>collapsedIcon</literal> and <literal>expandedIcon</literal> attributes to specify icons for the toggler when it is collapsed and expanded respectively. Use the <literal>collapsedLabel</literal> and <literal>expandedLabel</literal> attributes to specify labels for the toggler when it is collapsed and expanded respectively.</simpara>

</section>
<section id="sect-Component_Reference-richcollapsibleSubTableToggler-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.CollapsibleSubTableToggler</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UICollapsibleSubTableToggler</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.CollapsibleSubTableToggler</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.CollapsibleSubTableTogglerRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richcollapsibleSubTableToggler-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  
</section>

</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richextendedDataTable">
  <title><literal>&lt;rich:extendedDataTable&gt;</literal></title>
  <formalpara>
  <title>rf-csttg-colps:: This class defines styles for a toggle control which collapses the sub-table.</title>
  <para>The <literal>&lt;rich:extendedDataTable&gt;</literal> component builds on the functionality of the <literal>&lt;rich:dataTable&gt;</literal> component, adding features such as scrolling for the table body (both horizontal and vertical), Ajax loading for vertical scrolling, frozen columns, row selection, and rearranging of columns. It also supports all the basic table features such as sorting, filtering, and paging using the <literal>&lt;rich:dataScroller&gt;</literal> component.</para>
</formalpara>
<simpara>The <literal>&lt;rich:extendedDataTable&gt;</literal> component includes the following main attributes not included in the <literal>&lt;rich:dataTable&gt;</literal> component:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>clientRows</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>frozenColumns</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>height</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>onselectionchange</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>selectedClass</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>selection</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>selectionMode</literal></simpara>
      
    </listitem>
  
</itemizedlist>

<note>
  <title>Complex sub-tables</title>
  
<simpara>Due to the complex mark-up involved in the <literal>&lt;rich:extendedDataTable&gt;</literal> component, it does not support the use of the <literal>&lt;rich:collapsibleSubTable&gt;</literal> component. The <literal>&lt;rich:collapsibleSubTable&gt;</literal> component is only available with the <literal>&lt;rich:dataTable&gt;</literal> component.</simpara>
<simpara>Similarly, complex row and column spanning using the <literal>breakRowBefore</literal>, <literal>colSpan</literal>, and <literal>rowSpan</literal> attributes is also not available with the <literal>&lt;rich:extendedDataTable&gt;</literal> component.</simpara>

  
</note>
<section id="sect-Component_Reference-richextendedDataTable-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic use of the <literal>&lt;rich:extendedDataTable&gt;</literal> component requires the <literal>value</literal> and <literal>var</literal> attributes, the same as with the <literal>&lt;rich:dataTable&gt;</literal> component. In addition, a set of columns must be included to define the table content. Refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richdataTable"/> for details.</simpara>

</section>
<section id="sect-Component_Reference-richextendedDataTable-Table_appearance">
  <title>Table appearance</title>
  <simpara>As with the <literal>&lt;rich:dataTable&gt;</literal> component, the look of the <literal>&lt;rich:extendedDataTable&gt;</literal> component can be customized using the <literal>header</literal> and <literal>footer</literal> facets.</simpara>

</section>
<section id="sect-Component_Reference-richextendedDataTable-Extended_features">
  <title>Extended features</title>
  <example id="exam-Component_Reference-richextendedDataTable-richextendedDataTable_example">
  <title><literal>&lt;rich:extendedDataTable&gt;</literal> example</title>
<simpara>This example <literal>&lt;rich:extendedDataTable&gt;</literal> component demonstrates horizontal and vertical scrolling and frozen columns. Each feature is detailed in this section.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:extendedDataTable value="#{carsBean.allInventoryItems}"
                        var="car" id="table" frozenColumns="2"
                        style="height:300px; width:500px;" selectionMode="none"&gt;
   &lt;f:facet name="header"&gt;
      &lt;h:outputText value="Cars marketplace" /&gt;
   &lt;/f:facet&gt;
   &lt;rich:column&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="vendor" /&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{car.vendor}" /&gt;
   &lt;/rich:column&gt;
   &lt;rich:column&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="Model" /&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{car.model}" /&gt;
   &lt;/rich:column&gt;
   &lt;rich:column&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="Price" /&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{car.price}" /&gt;
   &lt;/rich:column&gt;
   &lt;rich:column&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="Mileage" /&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{car.mileage}" /&gt;
   &lt;/rich:column&gt;
   &lt;rich:column&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="VIN Code" /&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{car.vin}" /&gt;
   &lt;/rich:column&gt;
   &lt;rich:column&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="Items stock" /&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{car.stock}" /&gt;
   &lt;/rich:column&gt;
   &lt;rich:column&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="Days Live" /&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{car.daysLive}" /&gt;
   &lt;/rich:column&gt;
&lt;/rich:extendedDataTable&gt;
</programlisting>


<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-Tables_and_grids-richextendedDataTable_example.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-Tables_and_grids-richextendedDataTable_example</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A data table made using the <literal>&lt;rich:extendedDataTable&gt;</literal> component. It features horizontal and vertical scrolling and frozen columns.</simpara>

</example>
<section id="sect-Component_Reference-richextendedDataTable-Scrolling">
  <title>Scrolling</title>
  <simpara>The example table shown in <xref linkend="exam-Component_Reference-richextendedDataTable-richextendedDataTable_example"/> features both horizontal and vertical scrolling. Scrolling occurs automatically when the contents of the table exceed the dimensions specified with the <literal>height</literal> and <literal>width</literal> attributes. Headers and footers remain in place and visible when the table is scrolled.</simpara>
<simpara>Large tables can use Ajax "lazy" loading to cache data on the client during scrolling. Use the <literal>clientRows</literal> attribute to specify the number of rows to load. The specified number of rows are loaded on the initial rendering and with every vertical scroll. If the <literal>clientRows</literal> attribute is not specified, all the rows are loaded on the client without the use of Ajax.</simpara>
<simpara>In addition to Ajax scrolling, the <literal>&lt;rich:extendedDataTable&gt;</literal> component can also be used with the <literal>&lt;rich:dataScroller&gt;</literal> component in the same way as a regular <literal>&lt;rich:dataTable&gt;</literal> component. If both the <literal>clientRows</literal> and <literal>rows</literal> attributes are included, Ajax loading occurs as defined by the <literal>clientRows</literal> attribute, but the loading is limited to the current table page as determined by the <literal>rows</literal> attribute. Refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richdataScroller"/> for full details on using the <literal>&lt;rich:dataScroller&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richextendedDataTable-Frozen_columns">
  <title>Frozen columns</title>
  <simpara>The example table shown in <xref linkend="exam-Component_Reference-richextendedDataTable-richextendedDataTable_example"/> has the first two columns frozen so that they remain visible if the user scrolls horizontally through the table. Note that the horizontal scrollbar does not encompass these frozen columns. To freeze columns, use the <literal>frozenColumns</literal> attribute to specify the number of columns on the left-hand side of the table to freeze.</simpara>

</section>
<section id="sect-Component_Reference-richextendedDataTable-Row_selection">
  <title>Row selection</title>
  <simpara>Row selection is determined by the <literal>selectionMode</literal> attribute. Setting the attribute to <literal>none</literal> allows for no row selection capability. The example table shown in <xref linkend="exam-Component_Reference-richextendedDataTable-richextendedDataTable_example"/> does not allow row selection.</simpara>
<simpara>Setting the <literal>selectionMode</literal> attribute to <literal>single</literal> allows the user to select a single row at a time using the mouse. With the <literal>selectionMode</literal> attribute set to <literal>multiple</literal>, the user can select multiple rows. Holding down the Ctrlkey while clicking selects additional rows with each click. Holding down the Shiftkey while clicking selects all the rows in a range.</simpara>
<simpara>The <literal>selection</literal> attribute points to a collection of objects. It holds the <literal>rowKey</literal> identifiers to track which rows are selected. <xref linkend="exam-Component_Reference-richextendedDataTable-Selecting_multiple_rows"/> shows how to implement multiple row selection in the same table from <xref linkend="exam-Component_Reference-richextendedDataTable-richextendedDataTable_example"/>.</simpara>
<example id="exam-Component_Reference-richextendedDataTable-Selecting_multiple_rows">
  <title>Selecting multiple rows</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:extendedDataTable value="#{extTableSelectionBean.inventoryItems}"
                        var="car" selection="#{extTableSelectionBean.selection}"
                        id="table" frozenColumns="2"
                        style="height:300px; width:500px;" selectionMode="multiple"&gt;
   ...
</programlisting>


<simpara>The accompanying <literal>ExtSelectionBean</literal> bean handles which rows are selected. The rows are identified by their <literal>rowKey</literal> identifiers.</simpara>


<programlisting language="Java" linenumbering="unnumbered">package org.richfaces.demo.tables;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

import javax.faces.bean.ManagedBean;
import javax.faces.bean.ManagedProperty;
import javax.faces.bean.SessionScoped;
import javax.faces.event.AjaxBehaviorEvent;

import org.richfaces.component.UIExtendedDataTable;
import org.richfaces.demo.tables.model.cars.InventoryItem;

@ManagedBean
@SessionScoped

public class ExtTableSelectionBean implements Serializable{

   private Collection&lt;Object&gt; selection;
   @ManagedProperty(value = "#{carsBean.allInventoryItems}")
   private List&lt;InventoryItem&gt; inventoryItems;
   private List&lt;InventoryItem&gt; selectionItems = new ArrayList&lt;InventoryItem&gt;();

   public void selectionListener(AjaxBehaviorEvent event){
      UIExtendedDataTable dataTable = (UIExtendedDataTable)event.getComponent();
      Object originalKey = dataTable.getRowKey();
      selectionItems.clear();
      for (Object selectionKey: selection) {
         dataTable.setRowKey(selectionKey);
         if (dataTable.isRowAvailable()){
            selectionItems.add((InventoryItem)dataTable.getRowData());
         }
      }
      dataTable.setRowKey(originalKey);
   }

   public Collection&lt;Object&gt; getSelection() {
      return selection;
   }

   public void setSelection(Collection&lt;Object&gt; selection) {
      this.selection = selection;
   }

   public List&lt;InventoryItem&gt; getInventoryItems() {
      return inventoryItems;
   }

   public void setInventoryItems(List&lt;InventoryItem&gt; inventoryItems) {
      this.inventoryItems = inventoryItems;
   }

   public List&lt;InventoryItem&gt; getSelectionItems() {
      return selectionItems;
   }

   public void setSelectionItems(List&lt;InventoryItem&gt; selectionItems) {
      this.selectionItems = selectionItems;
   }
}
</programlisting>


<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-Tables_and_grids-Selecting_multiple_rows.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-Tables_and_grids-Selecting_multiple_rows</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>The example table with the first, second, third, and fifth rows selected.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richextendedDataTable-Rearranging_columns">
  <title>Rearranging columns</title>
  <simpara>Columns in a <literal>&lt;rich:extendedDataTable&gt;</literal> component can be rearranged by the user by dragging each column to a different position. A graphical representation of the column is displayed during dragging. <xref linkend="figu-Component_Reference-richextendedDataTable-Dragging_columns"/> illustrates the Pricecolumn being dragged to a new location. The small blue arrow indicates where the column will be moved to if it is dropped in the current position. <xref linkend="figu-Component_Reference-richextendedDataTable-Rearranged_columns"/> shows the result of dragging the Pricecolumn.</simpara>
<figure id="figu-Component_Reference-richextendedDataTable-Dragging_columns">
  <title>Dragging columns</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-Tables_and_grids-Dragging_columns.png" contentwidth="444"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-Tables_and_grids-Dragging_columns</phrase></textobject>
  </mediaobject>
</figure>
<figure id="figu-Component_Reference-richextendedDataTable-Rearranged_columns">
  <title>Rearranged columns</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-Tables_and_grids-Rearranged_columns.png" contentwidth="444"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-Tables_and_grids-Rearranged_columns</phrase></textobject>
  </mediaobject>
</figure>

</section>
<section id="sect-Component_Reference-richextendedDataTable-State_saving">
  <title>State saving</title>
  <simpara>The <literal>tableState</literal> attribute of the <literal>&lt;rich:extendedDataTable&gt;</literal> component can be used to bind state of the table (column width, sequence, sorting, filtering) to a backing-bean string property, for a later use. This state can be for example saved to a database, and it is different from standard JSF state saving mechanism.</simpara>

</section>
<section id="sect-Component_Reference-richextendedDataTable-Filtering_and_sorting">
  <title>Filtering and sorting</title>
  <simpara>The <literal>&lt;rich:extendedDataTable&gt;</literal> component can include filtering and sorting in the same way as a regular <literal>&lt;rich:dataTable&gt;</literal> component. For full details on filtering tables, refer to <xref linkend="sect-Component_Reference-Tables_and_grids-Table_filtering"/>. For full details on sorting tables, refer to <xref linkend="sect-Component_Reference-Tables_and_grids-Table_sorting"/>.</simpara>

</section>

</section>
<section id="sect-Component_Reference-richextendedDataTable-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:extendedDataTable&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>sort()</literal>
    </term>
    
    <listitem>
      
      <simpara>Sort the data table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>filter()</literal>
    </term>
    
    <listitem>
      
      <simpara>Filter the data table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>clearSorting()</literal>
    </term>
    
    <listitem>
      
      <simpara>Clear any sorting that is currently applied to the table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>clearFiltering()</literal>
    </term>
    
    <listitem>
      
      <simpara>Clear any filtering that is currently applied to the table.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>selectRow(index)</literal>
    </term>
    
    <listitem>
      
      <simpara>Select the row specified by the <literal>index</literal> parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>selectRows(\[startIndex, stopIndex\])</literal>
    </term>
    
    <listitem>
      
      <simpara>Select all the rows in the table. Optionally, select only those rows between the indexes specified with the <literal>startIndex</literal> and <literal>stopIndex</literal> parameters.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>deselectRow</literal>
    </term>
    
    <listitem>
      
      <simpara>Deselect the row that is currently selected.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setActiveRow(index)</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the active row to that specified by the <literal>index</literal> parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richextendedDataTable-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.ExtendedDataTable</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIExtendedDataTable</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Data</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.ExtendedDataTableRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.ExtendedDataTableHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richextendedDataTable-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richextendedDataTable-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt</literal>:: This class defines styles for the table.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-cnt</literal>:: This class defines styles for the table content.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-c</literal>:: This class defines styles for a table cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-c-cnt</literal>:: This class defines styles for the contents of a cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-tbl-hdr</literal>:: This class defines styles for the table header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-hdr</literal>:: This class defines styles for a header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-hdr-c</literal>:: This class defines styles for a table header cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-hdr-c-cnt</literal>:: This class defines styles for the contents of a header cell.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-tbl-ftr</literal>:: This class defines styles for the table footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-top</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableFooterBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-ftr</literal>:: This class defines styles for a footer.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-top</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableFooterBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-ftr-cnt</literal>:: This class defines styles for the content of a footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-ftr-c</literal>:: This class defines styles for a table footer cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-ftr-c-cnt</literal>:: This class defines styles for the contents of a footer cell.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-ftr-emp</literal>:: This class defines styles for an empty footer cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-right</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-ftr-fzn</literal>:: This class defines styles for a frozen footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-b</literal>:: This class defines styles for the body of the table.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-r-sel</literal>:: This class defines styles for the selected row.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-right</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-r-act</literal>:: This class defines styles for the active row.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-rsz</literal>:: This class defines styles for the table resizer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-rsz-cntr</literal>:: This class defines styles for the resize container.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-rsz-mkr</literal>:: This class defines styles for the resize marker.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-left</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-edt-rord</literal>:: This class defines styles for the re-order functionality.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal>, <literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderBackgroundColor</literal> / <literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-rord-mkr</literal>:: This class defines styles for the re-order marker.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rich-edt-spcr</literal>:: This class defines a spacer for Internet Explorer 7compatibility.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richdataGrid">
  <title><literal>&lt;rich:dataGrid&gt;</literal></title>
  <simpara>The <literal>&lt;rich:dataGrid&gt;</literal> component is used to arrange data objects in a grid. Values in the grid can be updated dynamically from the data model, and Ajax updates can be limited to specific rows. The component supports <literal>header</literal>, <literal>footer</literal>, and <literal>caption</literal> facets.</simpara>
<simpara>The <literal>&lt;rich:dataGrid&gt;</literal> component is similar in function to the JavaServer Faces <literal>&lt;h:panelGrid&gt;</literal> component. However, the <literal>&lt;rich:dataGrid&gt;</literal> component additionally allows iteration through the data model rather than just aligning child components in a grid layout.</simpara>
<figure id="figu-Component_Reference-richdataGrid-The_richdataGrid_component">
  <title>The <literal>&lt;rich:dataGrid&gt;</literal> component</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richdataGrid-The_richdataGrid_component.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richdataGrid-The_richdataGrid_component</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richdataGrid-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:dataGrid&gt;</literal> component requires the <literal>value</literal> attribute, which points to the data model, and the <literal>var</literal> attribute, which holds the current variable for the collection of data.</simpara>

</section>
<section id="sect-Component_Reference-richdataGrid-Customizing_the_grid">
  <title>Customizing the grid</title>
  <simpara>The number of columns for the grid is specifed with the <literal>columns</literal> attribute, and the number of elements to layout among the columns is determined with the <literal>elements</literal> attribute. The <literal>first</literal> attribute references the zero-based element in the data model from which the grid starts.</simpara>
<example id="exam-Component_Reference-richdataGrid-richdataGrid_example">
  <title><literal>&lt;rich:dataGrid&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel style="width:150px;height:200px;"&gt;
  &lt;h:form&gt;
    &lt;rich:dataGrid value="#{dataTableScrollerBean.allCars}" var="car" columns="2" elements="4" first="1"&gt;
        &lt;f:facet name="header"&gt;
          &lt;h:outputText value="Car Store"&gt;&lt;/h:outputText&gt;
      &lt;/f:facet&gt;
      &lt;rich:panel&gt;
          &lt;f:facet name="header"&gt;
            &lt;h:outputText value="#{car.make} #{car.model}"&gt;&lt;/h:outputText&gt;
          &lt;/f:facet&gt;
          &lt;h:panelGrid columns="2"&gt;
            &lt;h:outputText value="Price:" styleClass="label"&gt;&lt;/h:outputText&gt;
            &lt;h:outputText value="#{car.price}"/&gt;
            &lt;h:outputText value="Mileage:" styleClass="label"&gt;&lt;/h:outputText&gt;
            &lt;h:outputText value="#{car.mileage}"/&gt;
          &lt;/h:panelGrid&gt;
      &lt;/rich:panel&gt;
      &lt;f:facet name="footer"&gt;
          &lt;rich:dataScroller&gt;&lt;/rich:dataScroller&gt;
      &lt;/f:facet&gt;
    &lt;/rich:dataGrid&gt;
  &lt;/h:form&gt;
&lt;/rich:panel&gt;
</programlisting>


<blockquote>
  
  

<figure>
  <title><literal>&lt;rich:dataGrid&gt;</literal> example</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richdataGrid-richdataGrid_example.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richdataGrid-richdataGrid_example</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>

</section>
<section id="sect-Component_Reference-richdataGrid-Patial_updates">
  <title>Partial updates</title>
  <simpara>As <literal>&lt;rich:dataGrid&gt;</literal> the component is based on the <literal>&lt;a4j:repeat&gt;</literal> component, it can be partially updated with Ajax. Refer to <xref linkend="sect-Component_Reference-a4jrepeat-Limited_views_and_partial_updates"/> for details on partially updating the <literal>&lt;rich:dataGrid&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richdataGrid-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.DataGrid</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIDataGrid</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Data</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.DataGridRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.DataGridHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richdataGrid-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richdataGrid-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg</literal>:: This class defines styles for the grid.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-left-width, border-top-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-left-color, border-top-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-cap</literal>:: This class defines styles for the grid caption.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-r</literal>:: This class defines styles for a grid row.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-c</literal>:: This class defines styles for a grid cell.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-nd-c</literal>:: This class defines styles for a node cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-th</literal>:: This class defines styles for the grid header section.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-h</literal>:: This class defines styles for a grid header.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-h-f</literal>:: This class defines styles for the first header.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-h-r</literal>:: This class defines styles for a header row.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-h-c</literal>:: This class defines styles for a header cell.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableHeaderTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-f</literal>:: This class defines styles for a grid footer.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-f-f</literal>:: This class defines styles for the first footer.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dg-f-c</literal>:: This class defines styles for a footer cell.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableFooterBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderWidth</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-width, border-right-width</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-bottom-color, border-right-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richlist">
  <title><literal>&lt;rich:list&gt;</literal></title>
  <simpara>The <literal>&lt;rich:list&gt;</literal> component renders a list of items. The list can be an numerically ordered list, an un-ordered bullet-point list, or a data definition list. The component uses a data model for managing the list items, which can be updated dynamically.</simpara>
<section id="sect-Component_Reference-richlist-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>var</literal> attribute names a variable for iterating through the items in the data model. The items to iterate through are determined with the <literal>value</literal> attribute by using EL (Expression Language).</simpara>

</section>
<section id="sect-Component_Reference-richlist-Type_of_list">
  <title>Type of list</title>
  <simpara>By default, the list is displayed as an un-ordered bullet-point list. The <literal>type</literal> attribute is used to specify different list types:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>unordered</literal>
    </term>
    
    <listitem>
      
      <simpara>The default presentation. The list is presented as a series of bullet-points, similar to the <literal>&lt;ul&gt;</literal> HTML element.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<figure id="figu-Component_Reference-richlist-Unordered_list">
  <title>Unordered list</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richlist-Unordered_list.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richlist-Unordered_list</phrase></textobject>
  </mediaobject>
</figure>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>ordered</literal>
    </term>
    
    <listitem>
      
      <simpara>The list is presented as a numbered series of items, similar to the <literal>&lt;ol&gt;</literal> HTML element.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<figure id="figu-Component_Reference-richlist-Ordered_list">
  <title>Ordered list</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richlist-Ordered_list.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richlist-Ordered_list</phrase></textobject>
  </mediaobject>
</figure>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>definitions</literal>
    </term>
    
    <listitem>
      
      <simpara>The list is presented as a series of data definitions. Part of the data model, specified as the term, is listed prominently. The other associated data is listed after each term.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<figure id="figu-Component_Reference-richlist-Data_definition_list">
  <title>Data definition list</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richlist-Data_definition_list.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richlist-Data_definition_list</phrase></textobject>
  </mediaobject>
</figure>
<simpara>The term is marked using the <literal>term</literal> facet. The facet is required for all definition lists. Use of the facet is shown in <xref linkend="exam-Component_Reference-richlist-Data_definition_list"/>.</simpara>
<example id="exam-Component_Reference-richlist-Data_definition_list">
  <title>Data definition list</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form&gt;
    &lt;rich:list var="car" value="#{dataTableScrollerBean.allCars}" type="definitions" rows="5" title="Cars"&gt;
        &lt;f:facet name="term"&gt;
            &lt;h:outputText value="#{car.make} #{car.model}"&gt;&lt;/h:outputText&gt;
        &lt;/f:facet&gt;
        &lt;h:outputText value="Price:" styleClass="label"&gt;&lt;/h:outputText&gt;
        &lt;h:outputText value="#{car.price}" /&gt;&lt;br/&gt;
        &lt;h:outputText value="Mileage:" styleClass="label"&gt;&lt;/h:outputText&gt;
        &lt;h:outputText value="#{car.mileage}" /&gt;&lt;br/&gt;
    &lt;/rich:list&gt;
&lt;/h:form&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richlist-Bullet_and_numeration_appearance">
  <title>Bullet and numeration appearance</title>
  <simpara>The appearance of bullet points for unordered lists or numeration for ordered lists can be customized through CSS, using the list-style-typeproperty.</simpara>

</section>
<section id="sect-Component_Reference-richlist-Customizing_the_list">
  <title>Customizing the list</title>
  <simpara>The <literal>first</literal> attribute specifies which item in the data model to start from, and the <literal>rows</literal> attribute specifies the number of items to list. The <literal>title</literal> attribute is used for a floating tool-tip. <xref linkend="exam-Component_Reference-richlist-richlist_example"/> shows a simple example using the <literal>&lt;rich:list&gt;</literal> component.</simpara>
<example id="exam-Component_Reference-richlist-richlist_example">
  <title><literal>&lt;rich:list&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form&gt;
    &lt;rich:list var="car" value="#{dataTableScrollerBean.allCars}" rows="5" type="unordered" title="Car Store"&gt;
        &lt;h:outputText value="#{car.make} #{car.model}"/&gt;&lt;br/&gt;
        &lt;h:outputText value="Price:" styleClass="label"&gt;&lt;/h:outputText&gt;
        &lt;h:outputText value="#{car.price} "/&gt;&lt;br/&gt;
        &lt;h:outputText value="Mileage:" styleClass="label"&gt;&lt;/h:outputText&gt;
        &lt;h:outputText value="#{car.mileage} "/&gt;&lt;br/&gt;
    &lt;/rich:list&gt;
&lt;/h:form&gt;
</programlisting>


<blockquote>
  
  

<figure>
  <title><literal>&lt;rich:list&gt;</literal> example</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richlist-Unordered_list.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richlist-Unordered_list</phrase></textobject>
  </mediaobject>
</figure>


</blockquote>

</example>

</section>
<section id="sect-Component_Reference-richlist-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.List</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIList</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.List</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.ListRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.ListHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richlist-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richlist-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ulst-itm</literal>:: This class defines styles for an item in an unordered list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-olst-itm</literal>:: This class defines styles for an item in an unordered list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dlst-trm</literal>:: This class defines styles for the term of an item in a definition list.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-dlst-dfn</literal>:: This class defines styles for the definition of an item in a definition list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-richdataScroller">
  <title><literal>&lt;rich:dataScroller&gt;</literal></title>
  <simpara>The <literal>&lt;rich:dataScroller&gt;</literal> component is used for navigating through multiple pages of tables or grids.</simpara>
<figure id="figu-Component_Reference-richdataScroller-The_richdataScroller_component">
  <title>The <literal>&lt;rich:dataScroller&gt;</literal> component</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richdataScroller-The_richdataScroller_component.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richdataScroller-The_richdataScroller_component</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richdataScroller-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:dataScroller&gt;</literal> must be placed in a facet of the table or grid it needs to control. Alternatively, use the <literal>for</literal> attribute to bind the parent table or grid to the scroller.</simpara>
<simpara>The bound table or grid should also have the <literal>rows</literal> attribute defined to limit the number of rows per page.</simpara>
<simpara>The <literal>&lt;rich:dataScroller&gt;</literal> component must be re-rendered whenever a filter changes on the bound table, so that the scroller matches the current model for the table.</simpara>
<example id="exam-Component_Reference-richdataScroller-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable id="table" value="#{capitalsBean.capitals}" var="cap" rows="5"&gt;
   &lt;!-- table content --&gt;
   ...
&lt;/rich:dataTable&gt;
&lt;rich:dataScroller for="table" maxPages="5"&gt;
   &lt;f:facet name="first"&gt;
      &lt;h:outputText value="First" /&gt;
   &lt;/f:facet&gt;
   &lt;f:facet name="last"&gt;
      &lt;h:outputText value="Last" /&gt;
   &lt;/f:facet&gt;
&lt;/rich:dataScroller&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richdataScroller-Appearance_and_interactivity">
  <title>Appearance and interactivity</title>
  <simpara>The <literal>page</literal> attribute is a value-binding attribute used to define and save the current page number.</simpara>
<simpara>The <literal>&lt;rich:dataScroller&gt;</literal> component provides a range of controllers for scrolling through tables and grids:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      Controls for scrolling by a specific amount
    </term>
    
    <listitem>
      
      <simpara>The component includes controls for switching to the first page, the last page, the next page, and the previous page, as well as controls for fast-forwarding or rewinding by a set amount. Use the <literal>fastStep</literal> attribute to set the number of pages to skip when fast-forwarding or rewinding.
The appearance of these controls can be customized using the following facets: <literal>first</literal>, <literal>last</literal>, <literal>next</literal>, <literal>previous</literal>, <literal>fastForward</literal>, and <literal>fastRewind</literal>. Additionally, there are facets for the controls' disabled states: <literal>first_disabled</literal>, <literal>last_disabled</literal>, <literal>next_disabled</literal>, <literal>previous_disabled</literal>, <literal>fastforward_disabled</literal>, and <literal>rewind_disabled</literal>.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      Page controls
    </term>
    
    <listitem>
      
      <simpara>The component also features a series of numbered controls to jump to a specific page. Use the <literal>maxPages</literal> attribute to limit the number of page controls that appear. The current page control is highlighted.
To add optional separators between controls, define the separators with the <literal>controlsSeparator</literal> facet.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richdataScroller-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:dataScroller&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>switchToPage(pageIndex)</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to the page specified with the <literal>pageIndex</literal> parameter.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>next()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to the next page.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>previous()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to the previous page.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>first()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to the first page.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>last()</literal>
    </term>
    
    <listitem>
      
      <simpara>Switch to the last page.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>fastForward()</literal>
    </term>
    
    <listitem>
      
      <simpara>Step forward through the pages by the <literal>fastStep</literal> amount.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>fastRewind()</literal>
    </term>
    
    <listitem>
      
      <simpara>Step backward through the pages by the <literal>fastStep</literal> amount.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richdataScroller-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.DataScroller</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIDataScroller</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DataScroller</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.DataScrollerRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.DataScrollerHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richdataScroller-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richdataScroller-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds</literal>:: This class defines styles for the data scroller.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-btn</literal>:: This class defines styles for buttons in the data scroller.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-btn-first</literal>:: This class defines styles for the firstbutton.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-btn-fastrwd</literal>:: This class defines styles for the fast rewindbutton.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-btn-prev</literal>:: This class defines styles for the previousbutton.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-btn-next</literal>:: This class defines styles for the nextbutton.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-btn-fastfwd</literal>:: This class defines styles for the fast forwardbutton.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-btn-last</literal>:: This class defines styles for the lastbutton.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-nmb-btn</literal>:: This class defines styles for page number buttons in the data scroller.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-press</literal>:: This class defines styles for a data scroller when a control is pressed.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-act</literal>:: This class defines styles for an active data scroller.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ds-dis</literal>:: This class defines styles for a disabled data scroller.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tableBorderColor</literal></simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-Table_filtering">
  <title>Table filtering</title>
  <simpara>Tables entries can be filtered by the user through either the basic built-in filter inputs, or by defining external filter controls. Refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richcolumn"/> for details on using the <literal>&lt;rich:column&gt;</literal> component in tables.</simpara>
<section id="sect-Component_Reference-Table_filtering-filtering">
  <title>Filter Definition</title>
  <simpara>To define a filter for a column use either the <literal>filter</literal> or <literal>filterExpression</literal> attributes, then use the <literal>filterValue</literal> attribute to point to an object which holds the current filtering value for the column. The attribute can be used to store filtering conditions in a session.</simpara>
<simpara>Use the <literal>filterExpression</literal> attribute to define an expression that can be evaluated as a boolean value. The expression checks if each table entry satisfies the filtering condition when the table is rendered. For example, the expression might be a JSTL (JavaServer Pages Standard Tag Library) function such as <literal>contains</literal> or <literal>equals</literal>.</simpara>
<simpara>Use the <literal>filter</literal> attribute to define a filter interface. The attribute must use EL (Expression Language) to point to an object which implements the org.richfaces.model.Filter&lt;T&gt;interface. The object must provide a single accept(T t)method. The method takes each iteration object as a parameter and returns a boolean value, which determines whether the object satisfies the filter. By defining a custom filter, you can implement complex business logic to filter a table.</simpara>

</section>
<section id="sect-Component_Reference-Table_filtering-builtin_filtering">
  <title>Built-in filter controls</title>
  <note>
  <title>Availability of built-in filter controls</title>
  
<simpara>The built-in filter controls are only available with the <literal>extendedDataTable</literal> component. Support for built-in filter controls in the <literal>dataTable</literal> component will be added in a subsequent release.</simpara>

  
</note>
<simpara>The built-in filter controls of the <literal>&lt;rich:column&gt;</literal> component allow the user to enter text to use as the filtering value. The value of the built-in filter control is bound to the <literal>filterValue</literal> attribute, which can either be an initial filtering value on the page, or a value binding on the server. The filterValue is then applied to the filter defined either by the <literal>filterExpression</literal> or <literal>filter</literal> column attributes.</simpara>
<simpara>The filterValue is of type <literal>String</literal>. Conversion is either done implicitly via EL in the <literal>filterExpression</literal>, or explicitly within the <literal>filter</literal> function. The filter is processed and the table is rendered when the <literal>onblur</literal> event occurs for the column.</simpara>
<example id="exam-Component_Reference-Table_filtering-Basic_filtering">
  <title>Basic filtering</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:extendedDataTable value="#{carsBean.allInventoryItems}" var="car" filterVar="filterValue"&gt;
    &lt;f:facet name="header"&gt;
        &lt;h:outputText value="Cars marketplace"/&gt;
    &lt;/f:facet&gt;
    &lt;rich:column filterExpression="#{empty filterValue or fn:startsWith(car.model, filterValue)}"
                 filterValue="#{carsFilteringBean.modelFilter}"&gt;
        &lt;f:facet name="header"&gt;Model&lt;/f:facet&gt;
        &lt;h:outputText value="#{car.model}"/&gt;
    &lt;/rich:column&gt;
    &lt;rich:column filterExpression="#{empty filterValue or car.price ge filterValue}"
                 filterValue="#{carsFilteringBean.priceFilter}"
                 filterConverterMessage="Error converting the 'Price' filter value"&gt;
        &lt;f:facet name="header"&gt;Price&lt;/f:facet&gt;
        &lt;h:outputText value="#{car.price}"/&gt;
    &lt;/rich:column&gt;
&lt;/rich:extendedDataTable&gt;</programlisting>


<simpara>The example uses the basic filtering method on both columns in the table.</simpara>

</example>

</section>
<section id="sect-Component_Reference-Table_filtering-External_filtering">
  <title>External filter controls</title>
  <simpara>If you require more advanced filter controls use the external filtering properties of the <literal>&lt;rich:column&gt;</literal> component. With custom filter controls you can tailor the filter control, allowing for advanced use cases like select menus, checkboxes, etc. To use a custom filter control with the <literal>extendedDataTable</literal> component, one must first disable the built-in filter control.</simpara>
<note>
  <title>Disabling built-in filter controls</title>
  
<simpara>The built-in filter controls can be disabled on a column-by-column basis by setting the column attribute <literal>filterType="custom"</literal>. Alternatively one can disable filter controls for the whole application via the following context-param in the web.xml:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;context-param&gt;
    &lt;param-name&gt;org.richfaces.builtin.filter.enabled&lt;/param-name&gt;
    &lt;param-value&gt;false&lt;/param-value&gt;
&lt;/context-param&gt;</programlisting>



  
</note>
<example id="exam-Component_Reference-Table_filtering-External_filtering">
  <title>Filtering example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table"&gt;

    &lt;f:facet name="header"&gt;
        &lt;rich:columnGroup&gt;
            &lt;rich:column&gt;
                &lt;h:outputText value="State Name" /&gt;
            &lt;/rich:column&gt;
            &lt;rich:column&gt;
                &lt;h:outputText value="State Time Zone" /&gt;
            &lt;/rich:column&gt;
        &lt;/rich:columnGroup&gt;
    &lt;/f:facet&gt;
    &lt;rich:column filter="#{filteringBean.stateFilter}"&gt;
        &lt;f:facet name="header"&gt;
            &lt;h:inputText value="#{filteringBean.stateFilterValue}" id="input"&gt;
                &lt;a4j:ajax event="keyup" render="table@body"&gt;
                    &lt;a4j:attachQueue  requestDelay="700"
                        ignoreDupResponses="true" /&gt;
                &lt;/a4j:ajax&gt;
            &lt;/h:inputText&gt;
        &lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.state}" /&gt;
    &lt;/rich:column&gt;
    &lt;rich:column filterExpression="#{fn:containsIgnoreCase(cap.timeZone, filteringBean.zoneFilterValue)}"&gt;
        &lt;f:facet name="header"&gt;
            &lt;h:selectOneMenu value="#{filteringBean.zoneFilterValue}"&gt;
                &lt;f:selectItems value="#{filteringBean.zoneList}" /&gt;
                &lt;a4j:ajax event="change" render="table@body" /&gt;
            &lt;/h:selectOneMenu&gt;
        &lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.timeZone}" /&gt;
    &lt;/rich:column&gt;
&lt;/rich:dataTable&gt;</programlisting>


<simpara>The example uses a filter expression on the first column and a filter method on the second column.</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-Table_filtering-External_filtering.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-Table_filtering-External_filtering</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A table of state capitals filtered by states beginning with the letter " a", further filtered to those states in the GMT-5 time zone.</simpara>

</example>

</section>

</section>
<section id="sect-Component_Reference-Tables_and_grids-Table_sorting">
  <title>Table sorting</title>
  <simpara>Tables entries can be sorted</simpara>
<simpara>by defining external sorting algorithms. Refer to <xref linkend="sect-Component_Reference-Tables_and_grids-richcolumn"/> for details on using the <literal>&lt;rich:column&gt;</literal> component in tables.</simpara>
<note>
  <title>Sorting non-English tables</title>
  
<simpara>To sort a table whose contents are not in English, add the <literal>org.richfaces.datatableUsesViewLocale</literal> context parameter to the project&#8217;s _web.xml_settings file. Set the value of the context parameter to <literal>true</literal>.</simpara>

  
</note>
<section id="sect-Component_Reference-Tables_and_grids-Comparator">
  <title>Comparator Definition</title>
  <simpara>Use the <literal>comparator</literal> attribute of the <literal>&lt;rich:column&gt;</literal> to specify the comparator to use when sorting. If no <literal>comparator</literal> is specified, the sorting algorithm will invoke the entries <literal>compareTo</literal> method of the <literal>sortBy</literal> values if they implement the <literal>java.lang.Comparable</literal> interface. As a final fall back, the algorithm implements a null sort, sorting elements based on whether or not they are null.</simpara>

</section>
<section id="sect-Component_Reference-Tables_and_grids-Basic_sorting">
  <title>Built-in sort controls</title>
  <note>
  <title>Availability of built-in sort controls</title>
  
<simpara>The built-in sort controls are only available with the <literal>extendedDataTable</literal> component. Support for built-in sort controls in the <literal>dataTable</literal> component will be added in a subsequent release.</simpara>

  
</note>
<simpara>The built-in sorting controls of the <literal>&lt;rich:column&gt;</literal> component allow a user to click the sort icons of a column to sort it in ascending or descending order.</simpara>
<simpara>Set the <literal>sortBy</literal> attribute to indicate which value to use when sorting the column. Expressions in the <literal>sortBy</literal> attribute must refer to the variable declared in the table&#8217;s <literal>var</literal> attribute, which is used to fill the contents of the table.</simpara>
<example id="exam-Component_Reference-Table_sorting-Built_in_sorting">
  <title>Basic sorting</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px"&gt;
   &lt;rich:column sortBy="#{cap.state}"&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="State Name"/&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{cap.state}"/&gt;
   &lt;/rich:column&gt;
   &lt;rich:column sortBy="#{cap.name}"&gt;
      &lt;f:facet name="header"&gt;
         &lt;h:outputText value="State Capital"/&gt;
      &lt;/f:facet&gt;
      &lt;h:outputText value="#{cap.name}"/&gt;
   &lt;/rich:column&gt;
&lt;/rich:dataTable&gt;
</programlisting>


<simpara>The example uses the basic sorting method on both columns in the table.</simpara>

</example>
<simpara>Use the <literal>sortOrder</literal> attribute to set how the table&#8217;s contents are sorted when it is first loaded. By default, the value of the <literal>sortOrder</literal> attribute is <literal>unsorted</literal>, so that table entries appear in the order the are contained in the data model. Use <literal>sortOrder="ascending"</literal> to sort the entries in ascending alphabetical or numerical order. Use <literal>sortOrder="descending"</literal> to sort the entries in descending alphabetical or numerical order. The <literal>sortOrder</literal> attribute can also be used to externally set the sort order of a table when using the external sorting method; refer to <xref linkend="sect-Component_Reference-Table_sorting-External_sorting"/> for details.</simpara>

</section>
<section id="sect-Component_Reference-Table_sorting-External_sorting">
  <title>External sort controls</title>
  <simpara>Set the <literal>sortBy</literal> attribute to indicate which iteration object property to use when sorting the column. If using custom-defined rules for sorting, use the <literal>comparator</literal> attribute instead. Set the <literal>comparator</literal> attribute to point to your comparator method, which will be used when sorting the data model.</simpara>
<note>
  <title>Disabling built-in sort controls</title>
  
<simpara>The built-in sort controls can be disabled on a column-by-column basis by setting the column attribute <literal>sortType="custom"</literal>. Alternatively one can disable sort controls for the whole application via the following context-param in the web.xml:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;context-param&gt;
    &lt;param-name&gt;org.richfaces.builtin.sort.enabled&lt;/param-name&gt;
    &lt;param-value&gt;false&lt;/param-value&gt;
&lt;/context-param&gt;</programlisting>



  
</note>
<simpara>Bind the <literal>sortOrder</literal> attribute to bean properties to manage the sorting order. The bean must handle all the sorting algorithms. <xref linkend="exam-Component_Reference-Table_sorting-Sorting"/> demonstrates table sorting using an external control.</simpara>
<example id="exam-Component_Reference-Table_sorting-Sorting">
  <title>Sorting</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table"&gt;
    &lt;rich:column&gt;
        &lt;f:facet name="header"&gt;
            State Flag
        &lt;/f:facet&gt;
        &lt;h:graphicImage value="#{cap.stateFlag}" alt="flag" /&gt;
    &lt;/rich:column&gt;
    &lt;rich:column sortBy="#{cap.name}" id="name" sortOrder="#{capitalsSortingBean.capitalsOrder}"&gt;
        &lt;f:facet name="header"&gt;
            &lt;a4j:commandLink value="Sort by Capital Name" render="table" action="#{capitalsSortingBean.sortByCapitals}" /&gt;
        &lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.name}" /&gt;
    &lt;/rich:column&gt;
    &lt;rich:column sortBy="#{cap.state}" id="state" sortOrder="#{capitalsSortingBean.statesOrder}"&gt;
        &lt;f:facet name="header"&gt;
            &lt;a4j:commandLink value="Sort by State Name" render="table" action="#{capitalsSortingBean.sortByStates}" /&gt;
        &lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.state}" /&gt;
    &lt;/rich:column&gt;
    &lt;rich:column sortBy="#{cap.timeZone}" id="timeZone" comparator="#{capitalsSortingBean.timeZoneComparator}"
        sortOrder="#{capitalsSortingBean.timeZonesOrder}"&gt;
        &lt;f:facet name="header"&gt;
            &lt;a4j:commandLink value="Sort by Time Zone" render="table" action="#{capitalsSortingBean.sortByTimeZones}" /&gt;
        &lt;/f:facet&gt;
        &lt;h:outputText value="#{cap.timeZone}" /&gt;
    &lt;/rich:column&gt;
&lt;/rich:dataTable&gt;</programlisting>


<simpara>The example uses an external control to manage the table&#8217;s sorting.</simpara>

</example>
<simpara>When multiple columns are capable of being sorted at the same time, set the priority by which the columns are sorted with the <literal>sortPriorities</literal> attribute. The attribute must contain a list of column identifiers in the order of the sorting sequence.</simpara>

</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Trees">
  <title>Trees</title>
  <simpara>Read this chapter for details on components that use tree structures.</simpara>
<section id="sect-Component_Reference-Trees-richtree">
  <title><literal>&lt;rich:tree&gt;</literal></title>
  <simpara>The <literal>&lt;rich:tree&gt;</literal> component provides a hierarchical tree control. Each <literal>&lt;rich:tree&gt;</literal> component typically consists of <literal>&lt;rich:treeNode&gt;</literal> child components. The appearance and behavior of the tree and its nodes can be fully customized.</simpara>
<section id="sect-Component_Reference-richtree-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:tree&gt;</literal> component requires the <literal>value</literal> attribute to point to the data model for populating the tree. The data model must be either an org.richfaces.model.TreeNodeinterface, an <literal>org.richfaces.model.TreeDataModel</literal> interface, or a javax.swing.tree.TreeNodeinterface. The <literal>var</literal> attribute declares the variable used for iterating through the data model, so that child <literal>&lt;rich:treeNode&gt;</literal> components can reference each iteration.</simpara>
<simpara>Ideally, the <literal>&lt;rich:tree&gt;</literal> component needs one or more <literal>&lt;rich:treeNode&gt;</literal> components to work with the data model. However if no <literal>&lt;rich:treeNode&gt;</literal> components are provided the tree creates default nodes instead.</simpara>
<example id="exam-Component_Reference-richtree-Basic_usage">
  <title>Basic usage</title>
<simpara>This example demonstrates basic usage of the <literal>&lt;rich:tree&gt;</literal> component using an org.richfaces.model.TreeNodedata model.</simpara>
<simpara>First extend the <literal>org.richfaces.model.TreeNodeImpl</literal> and add the data fields you require, with appropriate accessor methods, as in:</simpara>


<programlisting language="Java" linenumbering="unnumbered">import org.richfaces.model.TreeNodeImpl;

public class DataHolderTreeNodeImpl extends TreeNodeImpl {
    private Object data;

    public DataHolderTreeNodeImpl() {
        super();
    }

    public DataHolderTreeNodeImpl(boolean leaf, Object data) {
        super(leaf);
        this.data = data;
    }

    public Object getData() {
        return data;
    }

    @Override
    public String toString() {
        return super.toString() + " &gt;&gt; " + data;
    }
}</programlisting>


<simpara>Then, the data model is constructed as follows:</simpara>


<programlisting language="Java" linenumbering="unnumbered">private DataHolderTreeNodeImpl stationRoot;
private DataHolderTreeNodeImpl rootNodes;

public DataHolderTreeNodeImpl getRootNodes() {
    if (rootNodes == null) {
        String[] kickRadioFeed = {"Hall &amp; Oates - Kiss On My List",
                "David Bowie - Let's Dance",
                "Lyn Collins - Think (About It)",
                "Kim Carnes - Bette Davis Eyes",
                "KC &amp; the Sunshine Band - Give It Up"};
        stationRoot = new DataHolderTreeNodeImpl(false, "KickRadio");
        for (int i = 0; i&lt;kickRadioFeed.length; i++) {
            DataHolderTreeNodeImpl child = new DataHolderTreeNodeImpl(true, kickRadioFeed[i]);
            stationRoot.addChild(i, child);
        }
        rootNodes = new DataHolderTreeNodeImpl();
        rootNodes.addChild(0, stationRoot);
    }
    return rootNodes;
}
</programlisting>


<simpara>The tree then accesses the nodes of the model using the <literal>station</literal> variable:</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:tree value="#{stations.stationNodes}" var="station"&gt;
   &lt;rich:treeNode&gt;
      &lt;h:outputText value="#{station}" /&gt;
   &lt;/rich:treeNode&gt;
&lt;/rich:tree&gt;
</programlisting>


<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/exam-Component_Reference-richtree-Basic_usage.png"/>
  </imageobject>
  <textobject><phrase>exam-Component_Reference-richtree-Basic_usage</phrase></textobject>
</inlinemediaobject></simpara>

</example>

</section>
<section id="sect-Component_Reference-richtree-Appearance">
  <title>Appearance</title>
  <simpara>Different nodes in the tree can have different appearances, such as node icons, depending on the type of data the node contains. Use the <literal>nodeType</literal> attribute to differentiate the types of nodes; the node is then rendered according to the <literal>&lt;rich:treeNode&gt;</literal> component with the corresponding <literal>type</literal> attribute. <xref linkend="exam-Component_Reference-richtree-nodeType_attribute"/> shows a <literal>&lt;rich:tree&gt;</literal> component with three different child <literal>&lt;rich:treeNode&gt;</literal> components defined to represent three different node appearances. Refer to <xref linkend="sect-Component_Reference-richtreeNode-Appearance"/> for details on customizing the appearance of <literal>&lt;rich:treeNode&gt;</literal> components.</simpara>
<example id="exam-Component_Reference-richtree-nodeType_attribute">
  <title><literal>nodeType</literal> attribute</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:tree style="width:300px" value="#{library.data}" var="item" nodeType="#{item.type}"&gt;
   &lt;rich:treeNode type="artist" iconExpanded="/images/tree/singer.png" iconCollapsed="/images/tree/singer.png"&gt;
      &lt;h:outputText value="#{item.name}" /&gt;
   &lt;/rich:treeNode&gt;
   &lt;rich:treeNode type="album" iconExpanded="/images/tree/disc.png" iconCollapsed="/images/tree/disc.png"&gt;
      &lt;h:outputText value="#{item.album}" /&gt;
   &lt;/rich:treeNode&gt;
   &lt;rich:treeNode type="song" iconLeaf="/images/tree/song.png"&gt;
      &lt;h:outputText value="#{item.title}" /&gt;
   &lt;/rich:treeNode&gt;
&lt;/rich:tree&gt;
</programlisting>


<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/exam-Component_Reference-richtree-nodeType_attribute.png"/>
  </imageobject>
  <textobject><phrase>exam-Component_Reference-richtree-nodeType_attribute</phrase></textobject>
</inlinemediaobject></simpara>

</example>
<simpara>If the <literal>nodeType</literal> attribute returns null, the node is rendered as a " <emphasis>typeless</emphasis>" (or default) node. The <emphasis>typeless</emphasis> node is the first child <literal>&lt;rich:treeNode&gt;</literal> component with a valid <literal>rendered</literal> attribute, but without a defined <literal>type</literal> attribute.</simpara>
<simpara>If the <literal>nodeType</literal> attribute is not included and there are no child <literal>&lt;rich:treeNode&gt;</literal> components, the tree constructs a default node itself.</simpara>
<simpara>Icons for different nodes and node states can be defined for the whole tree using the following attributes:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>iconLeaf</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>iconLeaf</literal> attribute points to the icon to use for any node that does not contain any child nodes.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>iconExpanded</literal>  and <literal>iconCollapsed</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>iconExpanded</literal> and <literal>iconCollapsed</literal> attributes point to the icons to use for expanded and collapsed nodes respectively. If these attributes are defined, the <literal>icon</literal> attribute is not used.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtree-Expanding_and_collapsing_tree_nodes">
  <title>Expanding and collapsing tree nodes</title>
  <simpara>The mode for performing submissions when nodes are expanded or collapsed is determined by the <literal>toggleType</literal> attribute, which can have one of the following three values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>This is the default setting. The <literal>&lt;rich:tree&gt;</literal> component performs an Ajax form submission, and only the content of the tree is rendered.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>server</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>&lt;rich:tree&gt;</literal> component performs a common submission, completely refreshing the page.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>&lt;rich:tree&gt;</literal> component updates on the client side through JavaScript, without any additional requests or updates. All nodes are rendered to the client during the initial page rendering.
By default, tree nodes are expanded and collapsed through the <literal>and -controls. To expand or collapse a tree node using an action event such as a mouse click, specify the event with the +toggleNodeEvent</literal> attribute.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtree-Selecting_tree_nodes">
  <title>Selecting tree nodes</title>
  <simpara>The mode for performing submissions when nodes are selected is determined by the <literal>selectionType</literal> attribute, which can have one of the following three values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>This is the default setting. The <literal>&lt;rich:tree&gt;</literal> component performs an Ajax form submission, and only the content of the tree is rendered.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>&lt;rich:tree&gt;</literal> component updates on the client side using JavaScript, without any additional requests or updates.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtree-Identifying_nodes_with_the_rowKeyConverter_attribute">
  <title>Identifying nodes with the <literal>rowKeyConverter</literal> attribute</title>
  <simpara>If the <literal>&lt;rich:tree&gt;</literal> component uses a custom data model, the data model provides unique keys for tree nodes so they can be identified during a client request. The <literal>&lt;rich:tree&gt;</literal> component can use strings as key values. These strings may contain special characters that are not allowed by browsers, such as the left angle bracket (&lt;) and ampersand (&amp;). To allow these characters in the keys, a row key converter must be provided.</simpara>
<simpara>To apply a converter to the <literal>&lt;rich:tree&gt;</literal> component, define it with the <literal>rowKeyConverter</literal> attribute.</simpara>

</section>
<section id="sect-Component_Reference-richtree-Event_handling">
  <title>Event handling</title>
  <simpara>In addition to the standard Ajax events and HMTL events, the <literal>&lt;rich:tree&gt;</literal> component uses the following client-side events:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>nodetoggle</literal> event is triggered when a node is expanded or collapsed.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>beforenodetoggle</literal> event is triggered before a node is expanded or collapsed.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>selectionchange</literal> event is triggered when a node is selected.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>beforeselectionchange</literal> event is triggered before a node is selected.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>The <literal>&lt;rich:tree&gt;</literal> component uses the following server-side listeners:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>toggleListener</literal> listener processes expand and collapse events.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>selectionChangeListener</literal> listener processes the request when a node is selected.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtree-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Tree</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UItree</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Tree</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.TreeRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.TreeHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtree-Style_classes">
  <title>Style classes</title>
  <simpara>Styling for the <literal>&lt;rich:tree&gt;</literal> component is mostly applied to the tree nodes. Refer to <xref linkend="sect-Component_Reference-richtreeNode-Style_classes_and_skin_parameters"/> for details on styling tree nodes. In addition, the <literal>&lt;rich:tree&gt;</literal> component can make use of the style classes outlined in <xref linkend="vlst-richtree-Style_classes"/>.</simpara>

</section>
<section id="sect-Component_Reference-Actions-richtreeSelectionChangeListener">
  <title><literal>&lt;rich:treeSelectionChangeListener&gt;</literal></title>
  <formalpara>
  <title>rf-tr-nd-exp:: This class defines styles for an expanded tree node.</title>
  <para>Use the <literal>&lt;rich:treeSelectionChangeListener&gt;</literal> tag to register a <literal>TreeSelectionChangeListener</literal> class on a parent <literal>&lt;rich:tree&gt;</literal> component. The class provided as a listener must implement the org.richfaces.event.TreeSelectionChangeListenerinterface. The processTreeSelectionChangemethod accepts an <literal>org.richface.event.TreeSelectionChangeEvent</literal> event as a parameter.</para>
</formalpara>

</section>
<section id="sect-Component_Reference-Trees-richtreeNode">
  <title><literal>&lt;rich:treeNode&gt;</literal></title>
  <simpara>The <literal>&lt;rich:treeNode&gt;</literal> component is a child component of the <literal>&lt;rich:tree&gt;</literal> component. It represents nodes in the parent tree. The appearance and functionality of each tree node can be customized.</simpara>
<section id="sect-Component_Reference-richtreeNode-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:treeNode&gt;</literal> component must be a child of a <literal>&lt;rich:tree&gt;</literal> component or a tree adaptor component. It does not need any attributes declared for basic usage, but can provide markup templates for tree nodes of particular types. Default markup is used if the tree node type is not specified. Refer to <xref linkend="exam-Component_Reference-richtree-Basic_usage"/> for an example of basic <literal>&lt;rich:treeNode&gt;</literal> component usage.</simpara>
<example id="exam-Component_Reference-richtreeNode-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:tree nodeType="#{node.type}" var="node"
           value="#{treeBean.rootNodes}"&gt;
   &lt;rich:treeNode type="country"&gt;
      #{node.name}
   &lt;/rich:treeNode&gt;
   &lt;rich:treeNode type="state"&gt;
      #{node.name}
   &lt;/rich:treeNode&gt;
   &lt;rich:treeNode type="city"&gt;
      #{node.name}
   &lt;/rich:treeNode&gt;
&lt;/rich:tree&gt;
</programlisting>


<simpara>The example renders a simple tree of countries. Each country node expands to show state nodes for that country, and each state node expands to show city nodes for that state.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richtreeNode-Appearance">
  <title>Appearance</title>
  <simpara>Refer to <xref linkend="sect-Component_Reference-richtree-Appearance"/> for the <literal>&lt;rich:tree&gt;</literal> component for details and examples on styling nodes and icons. Icon styling for individual <literal>&lt;rich:treeNode&gt;</literal> components uses the same attributes as the parent <literal>&lt;rich:tree&gt;</literal> component: <literal>iconLeaf</literal>, <literal>iconExpanded</literal>, and <literal>iconCollapsed</literal>. Icon-related attributes specified for child <literal>&lt;rich:treeNode&gt;</literal> components overwrite any global icon attributes of the parent <literal>&lt;rich:tree&gt;</literal> component.</simpara>
<simpara>Use the <literal>rendered</literal> attribute to determine whether the node should actually be rendered in the tree or not. Using the <literal>rendered</literal> attribute in combination with the <literal>&lt;rich:treeNode&gt;</literal>+type+ attribute can allow further style differentiation between node content.</simpara>

</section>
<section id="sect-Component_Reference-richtreeNode-Interactivity">
  <title>Interactivity</title>
  <simpara>Interactivity with individual nodes, such as expanding, collapsing, and other event handling, can be managed by the parent <literal>&lt;rich:tree&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-richtree-Expanding_and_collapsing_tree_nodes"/></simpara>
<simpara>and <xref linkend="sect-Component_Reference-richtree-Event_handling"/> for further details.</simpara>
<simpara>Use the <literal>expanded</literal> attribute to determine whether the node is expanded or collapsed.</simpara>

</section>
<section id="sect-Component_Reference-richtreeNode-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.TreeNode</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITreeNode</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.TreeNode</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.TreeNodeRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.TreeNodeHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtreeNode-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richtreeNode-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn</literal>:: This class defines styles for a tree node.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-lbl</literal>:: This class defines styles for a tree node label.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-cnt</literal>:: This class defines styles for tree node content.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-sel</literal>:: This class defines styles for a selected tree node.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-ldn</literal>:: This class defines styles for a tree node when it is loading.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-hnd</literal>:: This class defines styles for a tree node handle.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-hnd-lf</literal>:: This class defines styles for the handle of a leaf node.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-hnd-colps</literal>:: This class defines styles for the handle of a collapsed node.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-hnd-exp</literal>:: This class defines styles for the handle of an expanded node.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-hnd-ldn-fct</literal>:: This class defines styles for the loading facet of a tree node handle.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-ico</literal>:: This class defines styles for tree node icon.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-ico-lf</literal>:: This class defines styles for the icon of a leaf node.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-ico-colps</literal>:: This class defines styles for the icon of a collapsed node.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-trn-ico-exp</literal>:: This class defines styles for the icon of an expanded node.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>
<section id="sect-Component_Reference-Actions-richtreeToggleListener">
  <title><literal>&lt;rich:treeToggleListener&gt;</literal></title>
  <simpara>Use the <literal>&lt;rich:treeToggleListener&gt;</literal> tag to register a <literal>TreeToggleListener</literal> class on a parent <literal>&lt;rich:treeNode&gt;</literal> component. The class provided as a listener must implement the org.richfaces.event.TreeToggleListenerinterface. The processTreeTogglemethod accepts an <literal>org.richface.event.TreeToggleEvent</literal> event as a parameter.</simpara>

</section>

</section>

</section>
<section id="sect-Component_Reference-Trees-Tree_adaptors">
  <title>Tree adaptors</title>
  <simpara>Use a tree adaptor to populate a tree model declaratively from a non-hierarchical model, such as a list or a map.</simpara>
<section id="sect-Component_Reference-Tree_adaptors-richtreeModelAdaptor">
  <title><literal>&lt;rich:treeModelAdaptor&gt;</literal></title>
  <simpara>The <literal>&lt;rich:treeModelAdaptor&gt;</literal> component takes an object which implements the Mapor Iterableinterfaces. It adds all the object entries to the parent node as child nodes.</simpara>
<section id="sect-Component_Reference-richtreeModelAdaptor-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:treeModelAdaptor&gt;</literal> component is added as a nested child component to a <literal>&lt;rich:tree&gt;</literal> component, or to another tree adaptor component.</simpara>
<simpara>The <literal>&lt;rich:treeModelAdaptor&gt;</literal> component requires the <literal>nodes</literal> attribute for basic usage. The <literal>nodes</literal> attribute defines a collection of elements to iterate through for populating the nodes.</simpara>
<simpara>Define the appearance of each node added by the adaptor with a child <literal>&lt;rich:treeNode&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-Trees-richtreeNode"/> for details on the <literal>&lt;rich:treeNode&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richtreeModelAdaptor-Identifying_nodes">
  <title>Identifying nodes</title>
  <simpara>Adaptors that use Mapinterfaces or models with non-string keys require a row key converter in order to correctly identify nodes. Refer to <xref linkend="sect-Component_Reference-richtree-Identifying_nodes_with_the_rowKeyConverter_attribute"/> for details on the use of the <literal>rowKeyConverter</literal> attribute.</simpara>
<simpara>Adaptors that use Iterableinterfaces have simple integer row keys. A default converter is provided and does not need to be referenced explicitly.</simpara>

</section>
<section id="sect-Component_Reference-richtreeModelAdaptor-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.treeModelAdaptor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITreeModelAdaptor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.TreeModelAdaptor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.TreeModelAdaptorHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Tree_adaptors-richtreeModelRecursiveAdaptor">
  <title><literal>&lt;rich:treeModelRecursiveAdaptor&gt;</literal></title>
  <simpara>The <literal>&lt;rich:treeModelRecursiveAdaptor&gt;</literal> component iterates through recursive collections in order to populate a tree with hierarchical nodes, such as for a file system with multiple levels of directories and files.</simpara>
<section id="sect-Component_Reference-richtreeModelRecursiveAdaptor-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:treeModelRecursiveAdaptor&gt;</literal> component is an extension of the <literal>&lt;rich:treeModelAdaptor&gt;</literal> component. As such, the <literal>&lt;rich:treeModelRecursiveAdaptor&gt;</literal> component uses all of the same attributes. Refer to <xref linkend="sect-Component_Reference-Tree_adaptors-richtreeModelAdaptor"/> for details on the <literal>&lt;rich:treeModelAdaptor&gt;</literal> component.</simpara>
<simpara>In addition, the <literal>&lt;rich:treeModelRecursiveAdaptor&gt;</literal> component requires the <literal>roots</literal> attribute. The <literal>roots</literal> attribute defines the collection to use at the top of the recursion. For subsequent levels, the <literal>nodes</literal> attribute is used for the collection.</simpara>
<simpara><xref linkend="exam-Component_Reference-richtreeModelRecursiveAdaptor-Basic_usage"/> demonstrates how the <literal>&lt;rich:treeModelRecursiveAdaptor&gt;</literal> component can be used in conjunction with the <literal>&lt;rich:treeModelAdaptor&gt;</literal> component to recursively iterate through a file system and create a tree of directories and files.</simpara>
<example id="exam-Component_Reference-richtreeModelRecursiveAdaptor-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:tree var="item"&gt;
   &lt;rich:treeModelRecursiveAdaptor roots="#{fileSystemBean.sourceRoots}" nodes="#{item.directories}" &gt;
      &lt;rich:treeNode&gt;
         #{item.shortPath}
      &lt;/rich:treeNode&gt;
      &lt;rich:treeModelAdaptor nodes="#{item.files}"&gt;
         &lt;rich:treeNode&gt;#{item}&lt;/rich:treeNode&gt;
      &lt;/rich:treeModelAdaptor&gt;
   &lt;/rich:treeModelRecursiveAdaptor&gt;
&lt;/rich:tree&gt;
</programlisting>


<simpara>The <literal>&lt;rich:treeModelRecursiveAdaptor&gt;</literal> component references the <literal>FileSystemBean</literal> class as the source for the data.</simpara>


<programlisting language="Java" linenumbering="unnumbered">@ManagedBean
@RequestScoped
public class FileSystemBean {
   private static final String SRC_PATH = "/WEB-INF";

   private List&lt;FileSystemNode&gt; srcRoots;

   public synchronized List&lt;FileSystemNode&gt; getSourceRoots() {
      if (srcRoots == null) {
         srcRoots = new FileSystemNode(SRC_PATH).getDirectories();
      }
      return srcRoots;
   }
}
</programlisting>


<simpara>The <literal>FileSystemBean</literal> class in turn uses the <literal>FileSystemNode</literal> class to recursively iterate through the collection.</simpara>


<programlisting language="Java" linenumbering="unnumbered">public class FileSystemNode {
   ...
   public synchronized List&lt;FileSystemNode&gt; getDirectories() {
      if (directories == null) {
         directories = Lists.newArrayList();
         Iterables.addAll(directories, transform(filter(getResourcePaths(), containsPattern("/$")), FACTORY));
      }
      return directories;
   }

   public synchronized List&lt;String&gt; getFiles() {
      if (files == null) {
         files = new ArrayList&lt;String&gt;();
         Iterables.addAll(files, transform(filter(getResourcePaths(), not(containsPattern("/$"))), TO_SHORT_PATH));
      }
      return files;
   }

   private Iterable&lt;String&gt; getResourcePaths() {
        FacesContext facesContext = FacesContext.getCurrentInstance();
        ExternalContext externalContext = facesContext.getExternalContext();
        Set&lt;String&gt; resourcePaths = externalContext.getResourcePaths(this.path);

      if (resourcePaths == null) {
         resourcePaths = Collections.emptySet();
      }
      return resourcePaths;
   }
   ...
}
</programlisting>


<simpara>The <literal>getDirectories()</literal> function is used recursively until the object has the collection of children. The model adaptor calls the <literal>getFiles()</literal> function at each level in order to add the file nodes.</simpara>
<simpara>The resulting tree hierarchically lists the directories and files in the collection.</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/exam-Component_Reference-richtreeModelRecursiveAdaptor-Basic_usage.png"/>
  </imageobject>
  <textobject><phrase>exam-Component_Reference-richtreeModelRecursiveAdaptor-Basic_usage</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A hierarchical tree detailing a file system.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richtreeModelRecursiveAdaptor-Identifying_nodes">
  <title>Identifying nodes</title>
  <simpara>Adaptors that use Mapinterfaces or models with non-string keys require a row key converter in order to correctly identify nodes. Refer to <xref linkend="sect-Component_Reference-richtree-Identifying_nodes_with_the_rowKeyConverter_attribute"/> for details on the use of the <literal>rowKeyConverter</literal> attribute.</simpara>
<simpara>Adaptors that use Iterableinterfaces have simple integer row keys. A default converter is provided and does not need to be referenced explicitly.</simpara>

</section>
<section id="sect-Component_Reference-richtreeModelRecursiveAdaptor-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.TreeModelRecursiveAdaptor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITreeModelRecursiveAdaptor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.TreeModelRecursiveAdaptor</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.TreeModelRecursiveAdaptorHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Menus_and_toolbars">
  <title>Menus and toolbars</title>
  <simpara>Read this chapter for details on menu and toolbar components.</simpara>
<section id="sect-Component_Reference-Menus_and_toolbars-richdropDownMenu">
  <title><literal>&lt;rich:dropDownMenu&gt;</literal></title>
  <simpara>The <literal>&lt;rich:dropDownMenu&gt;</literal> component is used for creating a drop-down, hierarchical menu. It can be used with the <literal>&lt;rich:toolbar&gt;</literal> component to create menus in an application&#8217;s toolbar.</simpara>
<figure id="figu-Component_Reference-richdropDownMenu-richdropDownMenu">
  <title><literal>&lt;rich:dropDownMenu&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richdropDownMenu-richdropDownMenu.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richdropDownMenu-richdropDownMenu</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richdropDownMenu-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:dropDownMenu&gt;</literal> component only requires the <literal>label</literal> attribute for basic usage. Use the <literal>label</literal> attribute to define the text label that appears as the title of the menu. Clicking on the title drops the menu down.</simpara>
<simpara>Alternatively, use the <literal>label</literal> facet to define the menu title. If the <literal>label</literal> facet is used, the <literal>label</literal> attribute is not necessary.</simpara>

</section>
<section id="sect-Component_Reference-richdropDownMenu-Menu_content">
  <title>Menu content</title>
  <simpara>To set the content of the drop-down menu and any sub-menus, use the <literal>&lt;rich:menuItem&gt;</literal>, <literal>&lt;rich:menuGroup&gt;</literal>, and <literal>&lt;rich:menuSeparator&gt;</literal> components. These components are detailed in <xref linkend="sect-Component_Reference-Menus_and_toolbars-Menu_sub-components"/>.</simpara>

</section>
<section id="sect-Component_Reference-richdropDownMenu-Appearance">
  <title>Appearance</title>
  <simpara>Use the <literal>jointPoint</literal> and <literal>direction</literal> attributes to determine the direction and location of the menu when it appears. The <literal>jointPoint</literal> and <literal>direction</literal> attributes both use the following settings:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>topLeft</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>topRight</literal>:: <literal>bottomLeft</literal>:: <literal>bottomRight</literal>:: When used with the <literal>jointPoint</literal> attribute, the menu is attached to the top-left, top-right, bottom-left, or bottom-right of the control as appropriate.
When used with the <literal>direction</literal> attribute, the menu appears to the top-left, top-right, bottom-left, or bottom-right of the joint location as appropriate.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>auto</literal>
    </term>
    
    <listitem>
      
      <simpara>The direction or joint location is determined automatically.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>autoLeft</literal>:: <literal>autoRight</literal>:: <literal>autoTop</literal>:: <literal>autoBottom</literal>
    </term>
    
    <listitem>
      
      <simpara>When used with the <literal>jointPoint</literal> attribute, the joint location is determined automatically, but defaults to either the left, right, top, or bottom of the control as appropriate.
When used with the <literal>direction</literal> attribute, the menu direction is determined automatically, but defaults to either the left, right, top, or bottom of the joint location as appropriate.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richdropDownMenu-Expanding_and_collapsing_the_menu">
  <title>Expanding and collapsing the menu</title>
  <simpara>By default, the menu drops down when the title is clicked. To drop down with a different event, use the <literal>showEvent</literal> attribute to define the event instead.</simpara>
<simpara>Menus can be navigated using the keyboard. Additionally, menus can be navigated programmatically using the JavaScript API. The JavaScript API allows the following methods:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      show()
    </term>
    
    <listitem>
      
      <simpara>The show()method shows the menu.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      hide()
    </term>
    
    <listitem>
      
      <simpara>The hide()method hides the menu.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      activateItem(menuItemId)
    </term>
    
    <listitem>
      
      <simpara>The activateItem(menuItemId)activates the menu item with the <literal>menuItemId</literal> identifier.
Use the <literal>mode</literal> attribute to determine how the menu requests are submitted:</simpara>
      
      

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>server</literal>, the default setting, submits the form normally and completely refreshes the page.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>ajax</literal> performs an Ajax form submission, and re-renders elements specified with the <literal>render</literal> attribute.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client</literal> causes the <literal>action</literal> and <literal>actionListener</literal> items to be ignored, and the behavior is fully defined by the nested components or custom JavaScript instead of responses from submissions.</simpara>
      
    </listitem>
  
</itemizedlist>


      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richdropDownMenu-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.DropDownMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIDropDownMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DropDownMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.DropDownMenuRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richdropDownMenu-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richdropDownMenu-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-lbl</literal>:: This class defines styles for the label of the drop-down menu.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-dis</literal>:: This class defines styles for the drop-down menu when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-lbl-dis</literal>:: This class defines styles for the label of the drop-down menu when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-pos</literal>:: This class defines the positioning of the drop-down menu.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-lbl-unsel</literal>:: This class defines styles for the label of the drop-down menu when it is unselected.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-lst</literal>:: This class defines styles for the drop-down list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-lst-bg</literal>:: This class defines styles for the background of the drop-down list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-sublst</literal>:: This class defines the positioning of the menu when used as a sub-menu.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-itm</literal>:: This class defines styles for a menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-itm-sel</literal>:: This class defines styles for a menu item when it is selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-itm-unsel</literal>:: This class defines styles for a menu item when it is unselected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-itm-dis</literal>:: This class defines styles for a menu item when it is disabled.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-itm-lbl</literal>:: This class defines styles for the label in a menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-itm-ic</literal>:: This class defines styles for the icon in a menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-emptyIcon</literal>:: This class defines styles for an empty icon in a menu item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ddm-sep</literal>:: This class defines styles for a menu separator.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-top-color</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richcontextMenu">
  <title><literal>&lt;rich:contextMenu&gt;</literal></title>
  <simpara>The <literal>&lt;rich:contextMenu&gt;</literal> component is used for creating a hierarchical context menu that are activated on events like <literal>onmouseover</literal> , <literal>onclick</literal> etc. The component can be applied to any element on the page.</simpara>
<figure id="figu-Component_Reference-richcontextMenu-richcontextMenu">
  <title><literal>&lt;rich:contextMenu&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richcontextMenu-richcontextMenu.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richcontextMenu-richcontextMenu</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richcontextMenu-Basic_usage">
  <title>Basic usage</title>
  <simpara>To set the content of the context menu and any sub-menus, use the <literal>&lt;rich:menuItem&gt;</literal>, <literal>&lt;rich:menuGroup&gt;</literal>, and <literal>&lt;rich:menuSeparator&gt;</literal> components. These components are detailed in <xref linkend="sect-Component_Reference-Menus_and_toolbars-Menu_sub-components"/>.</simpara>

</section>
<section id="sect-Component_Reference-richcontextMenu-Appearance">
  <title>Appearance</title>
  <simpara>Use the <literal>direction</literal> attribute to determine the direction of the menu when it appears. The <literal>direction</literal> attribute uses the following settings:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>topLeft</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>topRight</literal>:: <literal>bottomLeft</literal>:: <literal>bottomRight</literal>:: The menu appears to the top-left, top-right, bottom-left, or bottom-right of the activation point.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>auto</literal>
    </term>
    
    <listitem>
      
      <simpara>The direction is determined automatically.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>autoLeft</literal>:: <literal>autoRight</literal>:: <literal>autoTop</literal>:: <literal>autoBottom</literal>
    </term>
    
    <listitem>
      
      <simpara>The menu direction is determined automatically, but defaults to either the left, right, top, or bottom of the activation point as appropriate.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richcontextMenu-Expanding_and_collapsing_the_menu">
  <title>Expanding and collapsing the menu</title>
  <simpara>By default, the menu is activated when the <literal>contextmenu</literal> event is observed (ie. a right-click). To activate on a different event, use the <literal>showEvent</literal> attribute to define the event instead.</simpara>
<simpara>Menus can be navigated using the keyboard. Additionally, menus can be navigated programmatically using the JavaScript API. The JavaScript API allows the following methods:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      show()
    </term>
    
    <listitem>
      
      <simpara>The show()method shows the menu.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      hide()
    </term>
    
    <listitem>
      
      <simpara>The hide()method hides the menu.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      activateItem(menuItemId)
    </term>
    
    <listitem>
      
      <simpara>The activateItem(menuItemId)activates the menu item with the <literal>menuItemId</literal> identifier.
Use the <literal>mode</literal> attribute to determine how the menu requests are submitted:</simpara>
      
      

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>server</literal>, the default setting, submits the form normally and completely refreshes the page.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>ajax</literal> performs an Ajax form submission, and re-renders elements specified with the <literal>render</literal> attribute.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client</literal> causes the <literal>action</literal> and <literal>actionListener</literal> items to be ignored, and the behavior is fully defined by the nested components or custom JavaScript instead of responses from submissions.</simpara>
      
    </listitem>
  
</itemizedlist>


      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richcontextMenu-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.ContextMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIContextMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.ContextMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.ContextMenuRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richcontextMenu-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richcontextMenu-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-lbl</literal>:: This class defines styles for the top level container of the context menu.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-dis</literal>:: This class defines styles for the context menu when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-lbl-dis</literal>:: This class defines styles for the top level of the context menu when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-pos</literal>:: This class defines the positioning of the context menu.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-lbl-unsel</literal>:: This class defines styles for the top level of the context menu when it is unselected.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-lst</literal>:: This class defines styles for the context list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-lst-bg</literal>:: This class defines styles for the background of the context list.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-sublst</literal>:: This class defines the positioning of the menu when used as a sub-menu.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-itm</literal>:: This class defines styles for a menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-itm-sel</literal>:: This class defines styles for a menu item when it is selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-itm-unsel</literal>:: This class defines styles for a menu item when it is unselected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-itm-dis</literal>:: This class defines styles for a menu item when it is disabled.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-itm-lbl</literal>:: This class defines styles for the label in a menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-itm-ic</literal>:: This class defines styles for the icon in a menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-emptyIcon</literal>:: This class defines styles for an empty icon in a menu item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ctx-sep</literal>:: This class defines styles for a menu separator.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-top-color</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-Menu_sub-components">
  <title>Menu sub-components</title>
  <simpara>The <literal>&lt;rich:menuItem&gt;</literal>, <literal>&lt;rich:menuGroup&gt;</literal>, and <literal>&lt;rich:menuSeparator&gt;</literal> components are used to construct menus for the <literal>&lt;rich:dropDownMenu&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-Menus_and_toolbars-richdropDownMenu"/> for more details on the <literal>&lt;rich:dropDownMenu&gt;</literal> component.</simpara>
<section id="sect-Component_Reference-Menus_and_toolbars-richmenuItem">
  <title><literal>&lt;rich:menuItem&gt;</literal></title>
  <simpara>The <literal>&lt;rich:menuItem&gt;</literal> component represents a single item in a menu control. The <literal>&lt;rich:menuItem&gt;</literal> component can be also be used as a seperate component without a parent menu component, such as on a toolbar.</simpara>
<section id="sect-Component_Reference-richmenuItem-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:menuItem&gt;</literal> component requires the <literal>label</literal> attribute for basic usage. The <literal>label</literal> attribute is the text label for the menu item.</simpara>

</section>
<section id="sect-Component_Reference-richmenuItem-Appearance">
  <title>Appearance</title>
  <simpara>Icons can be added to menu items through the use of two icon attributes. The <literal>icon</literal> attribute specifies the normal icon, while the <literal>iconDisabled</literal> attribute specifies the icon for a disabled item.</simpara>
<simpara>Alternatively, define facets with the names <literal>icon</literal> and <literal>iconDisabled</literal> to set the icons. If facets are defined, the <literal>icon</literal> and <literal>iconDisabled</literal> attributes are ignored. Using facets for icons allows more complex usage; example shows a checkbox being used in place of an icon.</simpara>
<example id="exam-Component_Reference-richmenuItem-Icon_facets">
  <title>Icon facets</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:menuItem value="Show comments"&gt;
   &lt;f:facet name="icon"&gt;
      &lt;h:selectBooleanCheckbox value="#{bean.property}"/&gt;
   &lt;/f:facet&gt;
&lt;/rich:menuItem&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richmenuItem-Submission_modes">
  <title>Submission modes</title>
  <simpara>Use the <literal>submitMode</literal> attribute to determine how the menu item requests are submitted:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>server</literal>, the default setting, submits the form normally and completely refreshes the page.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>ajax</literal> performs an Ajax form submission, and re-renders elements specified with the <literal>render</literal> attribute.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client</literal> causes the <literal>action</literal> and <literal>actionListener</literal> items to be ignored, and the behavior is fully defined by the nested components instead of responses from submissions.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richmenuItem-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:menuItem&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>activate()</literal>
    </term>
    
    <listitem>
      
      <simpara>Activate the menu item as though it were selected.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richmenuItem-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.MenuItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIMenuItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DropDownMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.MenuItemRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richmenuGroup">
  <title><literal>&lt;rich:menuGroup&gt;</literal></title>
  <simpara>The <literal>&lt;rich:menuGroup&gt;</literal> component represents an expandable sub-menu in a menu control. The <literal>&lt;rich:menuGroup&gt;</literal> component can contain a number of <literal>&lt;rich:menuItem&gt;</literal> components, or further nested <literal>&lt;rich:menuGroup&gt;</literal> components.</simpara>
<section id="sect-Component_Reference-richmenuGroup-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:menuGroup&gt;</literal> component requires the <literal>label</literal> attribute for basic usage. The <literal>label</literal> attribute is the text label for the menu item. Alternatively, use the <literal>label</literal> facet to define content for the label.</simpara>
<simpara>Additionally, the <literal>&lt;rich:menuGroup&gt;</literal> component must contain child <literal>&lt;rich:menuItem&gt;</literal> components or <literal>&lt;rich:menuGroup&gt;</literal> components.</simpara>

</section>
<section id="sect-Component_Reference-richmenuGroup-Appearance">
  <title>Appearance</title>
  <simpara>Icons can be added to menu groups through the use of two icon attributes. The <literal>icon</literal> attribute specifies the normal icon, while the <literal>iconDisabled</literal> attribute specifies the icon for a disabled group.</simpara>
<simpara>The <literal>&lt;rich:menuGroup&gt;</literal> component can be positioned using the <literal>jointPoint</literal> and <literal>direction</literal> attributes, the same as the parent menu control. For details on the <literal>jointPoint</literal> and <literal>direction</literal> attributes, refer to <xref linkend="sect-Component_Reference-richdropDownMenu-Appearance"/>.</simpara>

</section>
<section id="sect-Component_Reference-richmenuGroup-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:menuGroup&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>show()</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the menu group.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hide()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the menu group.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richmenuGroup-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.MenuGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIMenuGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DropDownMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.MenuGroupRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richmenuSeparator">
  <title><literal>&lt;rich:menuSeparator&gt;</literal></title>
  <simpara>The <literal>&lt;rich:menuSeparator&gt;</literal> component represents a separating divider in a menu control.</simpara>
<section id="sect-Component_Reference-richmenuSeparator-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:menuSeparator&gt;</literal> component does not require any attributes for basic usage. Add it as a child to a menu component to separator menu items and menu groups.</simpara>

</section>
<section id="sect-Component_Reference-richmenuSeparator-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.MenuSeparator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIMenuSeparator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DropDownMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.MenuSeparatorRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richpanelMenu">
  <title><literal>&lt;rich:panelMenu&gt;</literal></title>
  <simpara>The <literal>&lt;rich:panelMenu&gt;</literal> component is used in conjunction with <literal>&lt;rich:panelMenuItem&gt;</literal> and <literal>&lt;rich:panelMenuGroup&gt;</literal> to create an expanding, hierarchical menu. The <literal>&lt;rich:panelMenu&gt;</literal> component&#8217;s appearance can be highly customized, and the hierarchy can stretch to any number of sub-levels.</simpara>
<example id="exam-Component_Reference-richpanelMenu-richpanelMenu">
  <title>richpanelMenu</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panelMenu mode="ajax"
                topGroupExpandedRightIcon="chevronUp"
                topGroupCollapsedRightIcon="chevronDown"
                groupExpandedLeftIcon="disc"
                groupCollapsedLeftIcon="disc"&gt;
   &lt;rich:panelMenuGroup label="Group 1"&gt;
      &lt;rich:panelMenuItem label="Item 1.1"/&gt;
      &lt;rich:panelMenuItem label="Item 1.2"/&gt;
      &lt;rich:panelMenuItem label="Item 1.3"/&gt;
   &lt;/rich:panelMenuGroup&gt;
   &lt;rich:panelMenuGroup label="Group 2"&gt;
      &lt;rich:panelMenuItem label="Item 2.1"/&gt;
      &lt;rich:panelMenuItem   label="Item 2.2"/&gt;
      &lt;rich:panelMenuItem label="Item 2.3"/&gt;
      &lt;rich:panelMenuGroup label="Group 2.4"&gt;
         &lt;rich:panelMenuItem label="Item 2.4.1"/&gt;
         &lt;rich:panelMenuItem label="Item 2.4.2"/&gt;
         &lt;rich:panelMenuItem label="Item 2.4.3"/&gt;
      &lt;/rich:panelMenuGroup&gt;
      &lt;rich:panelMenuItem label="Item 2.5"/&gt;
   &lt;/rich:panelMenuGroup&gt;
   &lt;rich:panelMenuItem label="Item 3"/&gt;
&lt;/rich:panelMenu&gt;
</programlisting>


<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-richpanelMenu-richpanelMenu.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richpanelMenu-richpanelMenu</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A panel menu. The first menu group is collapsed. The second menu group is expanded; it contains menu items and a further menu group, which is currently selected and expanded. The third menu item is not a group and as such is not expandable.</simpara>

</example>
<section id="sect-Component_Reference-richpanelMenu-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:panelMenu&gt;</literal> component does not need any extra attributes declared for basic usage. However, it does require child <literal>&lt;rich:panelMenuGroup&gt;</literal> and <literal>&lt;rich:panelMenuItem&gt;</literal> components. Refer to <xref linkend="sect-Component_Reference-Menus_and_toolbars-richpanelMenuGroup"/> and <xref linkend="sect-Component_Reference-Menus_and_toolbars-richpanelMenuItem"/> for details on these child components.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenu-Interactivity_options">
  <title>Interactivity options</title>
  <simpara>The <literal>activeItem</literal> attribute is used to point to the name of the currently selected menu item.</simpara>
<simpara>By default, the event to expand the menu is a mouse click. Set the <literal>expandEvent</literal> attribute to specify a different event to expand menus. Multiple levels of sub-menus can be expanded in one action. Set <literal>expandSingle="true"</literal> to only expand one sub-menu at a time.</simpara>
<simpara>Similarly, the default event to collapse the menu is a mouse click. Set the <literal>collapseEvent</literal> attribute to specify a different event to collapse menus.</simpara>
<simpara>As with other control components, set <literal>disabled="true"</literal> to disable the <literal>&lt;rich:panelMenu&gt;</literal> comonent. Child menu components can be disabled in the same way.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenu-Appearance">
  <title>Appearance</title>
  <simpara>Icons for the panel menu can be chosen from a set of standard icons. Icons can be set for the top panel menu, child panel menus, and child item. There are three different menu states that the icon represents, as well as icons for both the left and right side of the item title.</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>topGroupExpandedLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>topGroupExpandedRightIcon</literal>:: These attributes determine the icons for the top level menu when it is expanded.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>topGroupCollapsedLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>topGroupCollapsedRightIcon</literal>:: These attributes determine the icons for the top level menu when it is collapsed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>topGroupDisabledLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>topGroupDisabledRightIcon</literal>:: These attributes determine the icons for the top level menu when it is disabled.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>topItemLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>topItemRightIcon</literal>:: These attributes determine the icons for a top level menu item.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>topItemDisabledLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>topItemDisabledRightIcon</literal>:: These attributes determine the icons for a top level menu item when it is disabled.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>groupExpandedLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>groupExpandedRightIcon</literal>:: These attributes determine the icons for sub-menus that are not the top-level menu when they are expanded.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>groupCollapsedLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>groupCollapsedRightIcon</literal>:: These attributes determine the icons for sub-menus that are not the top-level menu when they are collapsed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>groupDisabledLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>groupDisabledRightIcon</literal>:: These attributes determine the icons for sub-menus that are not the top-level menu when they are disabled.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>itemLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>itemRightIcon</literal>:: These attributes determine the icons for items in the menus.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>itemDisabledLeftIcon</literal>
    </term>
    
    <listitem>
      
      <simpara><literal>itemDisabledRightIcon</literal>:: These attributes determine the icons for items in the menus when they are disabled.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<simpara><xref linkend="exam-Component_Reference-richpanelMenu-richpanelMenu"/> demonstrates the use of icon declaration at the panel menu level. The standard icons are shown in <xref linkend="figu-Component_Reference-richpanelMenu-Standard_icons"/>.</simpara>
<figure id="figu-Component_Reference-richpanelMenu-Standard_icons">
  <title><literal>&lt;Standard icons&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richpanelMenuGroup-Standard_icons.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richpanelMenuGroup-Standard_icons</phrase></textobject>
  </mediaobject>
</figure>
<simpara>Alternatively, point the icon attributes to the paths of image files. The image files are then used as icons.</simpara>
<simpara>Any icons specified by child <literal>&lt;rich:panelMenuGroup&gt;</literal> and <literal>&lt;rich:panelMenuItem&gt;</literal> components overwrite the relevant icons declared with the parent <literal>&lt;rich:panelMenu&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenu-Submission_modes">
  <title>Submission modes</title>
  <simpara>The <literal>itemMode</literal> attribute defines the submission mode for normal menu items that link to content, and the <literal>groupMode</literal> attribute defines the submission mode for menu items that expand and collapse. The settings for these attributes apply to the entire menu unless a menu item defines its own individual <literal>itemMode</literal> or <literal>groupMode</literal>. The possible values for <literal>itemMode</literal> and <literal>groupMode</literal> are as follows:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>server</literal>, the default setting, which submits the form normally and completely refreshes the page.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>ajax</literal>, which performs an Ajax form submission, and re-renders elements specified with the <literal>render</literal> attribute.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client</literal>, which causes the <literal>action</literal> and <literal>actionListener</literal> items to be ignored, and the behavior is fully defined by the nested components instead of responses from submissions.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richpanelMenu-richpanelMenu_server-side_events">
  <title><literal>&lt;rich:panelMenu&gt;</literal> server-side events</title>
  <simpara>The <literal>&lt;rich:panelMenu&gt;</literal> component fires the <literal>ItemChangeEvent</literal> event on the server side when the menu is changed. The event only fires in the <literal>server</literal> and <literal>ajax</literal> submission modes. The event provides the <literal>itemChangeListener</literal> attribute to reference the event listener. Refer to <xref linkend="sect-Component_Reference-Panels-richitemChangeListener"/> for details on the <literal>&lt;rich:itemChangeListener&gt;</literal> tag.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenu-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:panelMenu&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>expandAll()</literal>
    </term>
    
    <listitem>
      
      <simpara>Expand all the panel menu groups in the component.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>collapseAll()</literal>
    </term>
    
    <listitem>
      
      <simpara>Collapse all the panel menu groups in the component.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>selectItem(id)</literal>
    </term>
    
    <listitem>
      
      <simpara>Select the menu item with the <literal>id</literal> identifier.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richpanelMenu-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.PanelMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPanelMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.PanelMenu</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PanelMenuRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.html.PanelMenuTagHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richpanelMenu-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richpanelMenu-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm</literal>:: This class defines styles for the panel menu itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr</literal>:: This class defines styles for a panel menu group.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-top-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-exp</literal>:: <literal>.rf-pm-colps</literal>:: These classes define styles for the panel menu when it is expanded or collapsed.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-ico</literal>:: This class defines styles for the panel menu icons.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-ico-exp</literal>:: <literal>.rf-pm-ico-colps</literal>:: These classes define styles for the panel menu icons when they are expanded or collapsed.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-hdr-exp</literal>:: <literal>.rf-pm-hdr-colps</literal>:: These classes define styles for the panel menu headers when they are expanded or collapsed.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm</literal>:: This class defines styles for a panel menu item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-top-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm-gr</literal>:: This class defines styles for a panel menu item as part of a panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm:hover</literal>:: This class defines styles for a panel menu item when the mouse hovers over it.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm-sel</literal>:: This class defines styles for a panel menu item when it is selected.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm-dis</literal>:: This class defines styles for a panel menu item when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm-ico</literal>:: This class defines styles for the icon in a panel menu item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm-exp-ico</literal>:: This class defines styles for the icon in a panel menu item when it is expanded.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-itm-lbl</literal>:: This class defines styles for the label in a panel menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr</literal>:: This class defines styles for a panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-top-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-gr</literal>:: This class defines styles for a panel menu group as part of another panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-sel</literal>:: This class defines styles for a panel menu group when it is selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-hdr</literal>:: This class defines styles for the header of a panel menu group.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-hdr:hover</literal>:: This class defines styles for the header of a panel menu group when the mouse hovers over it.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-hdr-dis</literal>:: This class defines styles for the header of a panel menu group when it is disabled.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-ico</literal>:: This class defines styles for the icon in a panel menu group.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-exp-ico</literal>:: This class defines styles for the icon in a panel menu group when it is expanded.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-lbl</literal>:: This class defines styles for the label in a panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-gr-cnt</literal>:: This class defines styles for the content of a panel menu group.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm</literal>:: This class defines styles for the top panel menu item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm-gr</literal>:: This class defines styles for the top panel menu item as part of a panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm:hover</literal>:: This class defines styles for the top panel menu item when the mouse hovers over it.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm-sel</literal>:: This class defines styles for the top panel menu item when it is selected.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm-dis</literal>:: This class defines styles for the top panel menu item when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm-ico</literal>:: This class defines styles for the icon in the top panel menu item.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm-exp-ico</literal>:: This class defines styles for the icon in the top panel menu item when it is expanded.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-itm-lbl</literal>:: This class defines styles for the label in the top panel menu item.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr</literal>:: This class defines styles for the top panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr-gr</literal>:: This class defines styles for the top panel menu group as part of another panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr-sel</literal>:: This class defines styles for the top panel menu group when it is selected.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr-hdr</literal>:: This class defines styles for the header of the top panel menu group.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr-hdr-dis</literal>:: This class defines styles for the header of the top panel menu group when it is disabled.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tabDisabledTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>additionalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr-ico</literal>:: This class defines styles for the icon in the top panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr-exp-ico</literal>:: This class defines styles for the icon in the top panel menu group when it is expanded.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pm-top-gr-lbl</literal>:: This class defines styles for the label in the top panel menu group.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richpanelMenuGroup">
  <title><literal>&lt;rich:panelMenuGroup&gt;</literal></title>
  <simpara>The <literal>&lt;rich:panelMenuGroup&gt;</literal> component defines a group of <literal>&lt;rich:panelMenuItem&gt;</literal> components inside a <literal>&lt;rich:panelMenu&gt;</literal>.</simpara>
<section id="sect-Component_Reference-richpanelMenuGroup-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:panelMenuGroup&gt;</literal> component needs the <literal>label</literal> attribute declared, which specifies the text to show for the menu entry. Alternatively, the <literal>label</literal> facet can be used to specify the menu text.</simpara>
<simpara>In addition, the <literal>&lt;rich:panelMenuGroup&gt;</literal> component at least one <literal>&lt;rich:panelMenuGroup&gt;</literal> or <literal>&lt;rich:panelMenuItem&gt;</literal> components as child elements.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuGroup-Appearance">
  <title>Appearance</title>
  <simpara>Icons for the menu group are inherited from the parent <literal>&lt;rich:panelMenu&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-richpanelMenu-Appearance"/> for details on icon attributes and facets. Alternatively, the menu group&#8217;s icons can be re-defined at the <literal>&lt;rich:panelMenuGroup&gt;</literal> component level, and these settings will be used instead of the parent component&#8217;s settings.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuGroup-Submission_modes">
  <title>Submission modes</title>
  <simpara>If the <literal>mode</literal> attribute is unspecified, the submission behavior for the group is inherited from the parent <literal>&lt;rich:panelMenu&gt;</literal>. Otherwise, the <literal>groupMode</literal> setting of the panel menu is used instead of the parent&#8217;s behavior. Refer to <xref linkend="sect-Component_Reference-richpanelMenu-Submission_modes"/> for submission mode settings.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuGroup-richpanelMenuGroup_server-side_events">
  <title><literal>&lt;rich:panelMenuGroup&gt;</literal> server-side events</title>
  <simpara>The <literal>&lt;rich:panelMenuGroup&gt;</literal> component fires the <literal>ActionEvent</literal> event on the server side when the menu group receives a user action. The event only fires in the <literal>server</literal> and <literal>ajax</literal> submission modes. The event provides the <literal>action</literal> attribute to specify the user action method, and the <literal>actionListener</literal> attribute to reference the event listener.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuGroup-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:panelMenuGroup&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>expand()</literal>
    </term>
    
    <listitem>
      
      <simpara>Expand this panel menu group.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>collapse()</literal>
    </term>
    
    <listitem>
      
      <simpara>Collapse this panel menu group.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>select(id)</literal>
    </term>
    
    <listitem>
      
      <simpara>Select the menu item with the <literal>id</literal> identifier.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richpanelMenuGroup-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.PanelMenuGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPanelMenuGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.PanelMenuGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PanelMenuGroupRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richpanelMenuItem">
  <title><literal>&lt;rich:panelMenuItem&gt;</literal></title>
  <simpara>The <literal>&lt;rich:panelMenuItem&gt;</literal> component represents a single item inside a <literal>&lt;rich:panelMenuGroup&gt;</literal> component, which is in turn part of a <literal>&lt;rich:panelMenu&gt;</literal> component.</simpara>
<section id="sect-Component_Reference-richpanelMenuItem-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:panelMenuItem&gt;</literal> component needs the <literal>label</literal> attribute declared, which specifies the text to show for the menu entry. Alternatively, the <literal>label</literal> facet can be used to specify the menu text.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuItem-Appearance">
  <title>Appearance</title>
  <simpara>Icons for the menu item are inherited from the parent <literal>&lt;rich:panelMenu&gt;</literal> or <literal>&lt;rich:panelMenuGroup&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-richpanelMenu-Appearance"/> for details on icon attributes and facets. Alternatively, the menu item&#8217;s icons can be re-defined at the <literal>&lt;rich:panelMenuItem&gt;</literal> component level, and these settings will be used instead of the parent component&#8217;s settings.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuItem-Submission_modes">
  <title>Submission modes</title>
  <simpara>If the <literal>mode</literal> is unspecified, the submission behavior for the item is inherited from the parent <literal>&lt;rich:panelMenu&gt;</literal>. Otherwise, the <literal>itemMode</literal> setting from the panel menu is used instead of the parent&#8217;s behavior.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuItem-richpanelMenuItem_server-side_events">
  <title><literal>&lt;rich:panelMenuItem&gt;</literal> server-side events</title>
  <simpara>The <literal>&lt;rich:panelMenuItem&gt;</literal> component fires the <literal>ActionEvent</literal> event on the server side when the menu item receives a user action. The event only fires in the <literal>server</literal> and <literal>ajax</literal> submission modes. The event provides the <literal>action</literal> attribute to specify the user action performed, and the <literal>actionListener</literal> attribute to reference the event listener.</simpara>

</section>
<section id="sect-Component_Reference-richpanelMenuItem-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:panelMenuItem&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>select()</literal>
    </term>
    
    <listitem>
      
      <simpara>Select this menu item.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richpanelMenuItem-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.PanelMenuItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPanelMenuItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.PanelMenuItem</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PanelMenuItemRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richtoolbar">
  <title><literal>&lt;rich:toolbar&gt;</literal></title>
  <simpara>The <literal>&lt;rich:toolbar&gt;</literal> component is a horizontal toolbar. Any JavaServer Faces ( JSF) component can be added to the toolbar.</simpara>
<figure id="figu-Component_Reference-richtoolbar-richtoolbar">
  <title><literal>&lt;rich:toolbar&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richtoolbar-richtoolbar.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richtoolbar-richtoolbar</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richtoolbar-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:toolbar&gt;</literal> component does not require any attributes to be defined for basic usage. Add child components to the <literal>&lt;rich:toolbar&gt;</literal> component to have them appear on the toolbar when rendered.</simpara>
<example id="exam-Component_Reference-richtoolbar-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:toolbar&gt;
   &lt;h:commandLink value="News" /&gt;
   &lt;h:commandLink value="Reviews" /&gt;
   &lt;h:commandLink value="Galleries" /&gt;
&lt;/rich:toolbar&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richtoolbar-Appearance">
  <title>Appearance</title>
  <simpara>Set the width and height of the toolbar using the common <literal>width</literal> and <literal>height</literal> attributes.</simpara>
<simpara>Items on the toolbar can be separated by a graphical item separator. Use the <literal>itemSeparator</literal> attribute to specify one of the standard separator styles:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>none</literal>, the default appearance, does not show any item separators.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>disc</literal> shows a small circular disc to separate items: image:</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>grid</literal> shows a grid pattern to separate items: image:</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>line</literal> shows a vertical line to separate items: image:</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>square</literal> shows a small square to separate items: image:</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Alternatively, use the <literal>itemSeparator</literal> attribute to specify a URL to an image. The image is then used as an item separator. The appearance of the item separator can be additionally customized by using the <literal>itemSeparator</literal> facet.</simpara>

</section>
<section id="sect-Component_Reference-richtoolbar-Grouping_items">
  <title>Grouping items</title>
  <simpara>Group together multiple items on the toolbar by using the <literal>&lt;rich:toolbarGroup&gt;</literal> child component. Refer to <xref linkend="sect-Component_Reference-Menus_and_toolbars-richtoolbarGroup"/> for full details on the <literal>&lt;rich:toolbarGroup&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richtoolbar-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Toolbar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIToolbar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Toolbar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.ToolbarRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtoolbar-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richtoolbar-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tb</literal>:: This class defines styles for the toolbar itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerWeightFont</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>font-weight</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tb-itm</literal>:: This class defines styles for an item in the toolbar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tb-sep</literal>:: This class defines styles for a separator in the toolbar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tb-sep-grid</literal>:: <literal>.rf-tb-sep-line</literal>:: <literal>.rf-tb-sep-disc</literal>:: <literal>.rf-tb-sep-square</literal>:: These classes define styles for grid, line, disc, and square separators.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tb-cntr</literal>:: This class defines styles for the container of the toolbar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>
<section id="sect-Component_Reference-Menus_and_toolbars-richtoolbarGroup">
  <title><literal>&lt;rich:toolbarGroup&gt;</literal></title>
  <simpara>The <literal>&lt;rich:toolbarGroup&gt;</literal> component is a child component of the <literal>&lt;rich:toolbar&gt;</literal> component. The <literal>&lt;rich:toolbarGroup&gt;</literal> component is used to group a number of items together on a toolbar.</simpara>
<section id="sect-Component_Reference-richtoolbarGroup-Basic_usage">
  <title>Basic usage</title>
  <simpara>Like the <literal>&lt;rich:toolbar&gt;</literal> parent component, the <literal>&lt;rich:toolbarGroup&gt;</literal> component does not require any extra attributes for basic functionality. Add child components to the <literal>&lt;rich:toolbarGroup&gt;</literal> component to have them appear grouped on the parent toolbar when rendered.</simpara>

</section>
<section id="sect-Component_Reference-richtoolbarGroup-Appearance">
  <title>Appearance</title>
  <simpara>Similar to the <literal>&lt;rich:toolbar&gt;</literal> component, items within a <literal>&lt;rich:toolbarGroup&gt;</literal> can be separated by specifying the <literal>itemSeparator</literal> attribute. Refer to <xref linkend="sect-Component_Reference-richtoolbar-Appearance"/> for details on using the <literal>itemSeparator</literal> attribute.</simpara>
<simpara>Groups of toolbar items can be located on either the left-hand side or the right-hand side of the parent toolbar. By default, they appear to the left. To locate the toolbar group to the right of the parent toolbar, set <literal>location="right"</literal>.</simpara>
<example id="exam-Component_Reference-richtoolbarGroup-richtoolbarGroup">
  <title><literal>&lt;rich:toolbarGroup&gt;</literal></title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:toolBar height="26" itemSeparator="grid"&gt;
   &lt;rich:toolBarGroup&gt;
      &lt;h:graphicImage value="/images/icons/create_doc.gif"/&gt;
      &lt;h:graphicImage value="/images/icons/create_folder.gif"/&gt;
      &lt;h:graphicImage value="/images/icons/copy.gif"/&gt;
   &lt;/rich:toolBarGroup&gt;
   &lt;rich:toolBarGroup&gt;
      &lt;h:graphicImage value="/images/icons/save.gif"/&gt;
      &lt;h:graphicImage value="/images/icons/save_as.gif"/&gt;
      &lt;h:graphicImage value="/images/icons/save_all.gif"/&gt;
   &lt;/rich:toolBarGroup&gt;
   &lt;rich:toolBarGroup location="right"&gt;
      &lt;h:graphicImage value="/images/icons/find.gif"/&gt;
      &lt;h:graphicImage value="/images/icons/filter.gif"/&gt;
   &lt;/rich:toolBarGroup&gt;
&lt;/rich:toolBar&gt;
</programlisting>


<simpara>The example shows how to locate a toolbar group to the right-hand side of the parent toolbar. It also demonstrates how item separators on the parent toolbar work with toolbar groups.</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/figu-Component_Reference-richtoolbarGroup-richtoolbarGroup.png"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richtoolbarGroup-richtoolbarGroup</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A toolbar using icons. Two toolbar groups are located on the left-hand side of the toolbar and separated by a grid pattern. The third toolbar group is located to the right-hand side.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richtoolbarGroup-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.ToolbarGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIToolbarGroup</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Toolbar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.ToolbarGroupRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Output_and_messages">
  <title>Output and messages</title>
  <simpara>Read this chapter for details on components that display messages and other feedback to the user.</simpara>
<section id="sect-Component_Reference-Output_and_messages-richmessage">
  <title><literal>&lt;rich:message&gt;</literal></title>
  <simpara>The <literal>&lt;rich:message&gt;</literal> component renders a single <literal>FacesMessage</literal> message instance added for the component. The appearance of the message can be customized, and tool-tips can be used for further information about the message.</simpara>
<simpara>The <literal>&lt;rich:message&gt;</literal> component is rendered in the same way as the standard <literal>&lt;h:message&gt;</literal> component, but allows separate styling of the message summary and detail. It allows unified icons to be set using background images in predefined classes.</simpara>
<figure id="figu-Component_Reference-richmessage-richmessage_component">
  <title>rich:message component</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richmessage-richmessage_component.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richmessage-richmessage_component</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richmessage-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:message&gt;</literal> component needs the <literal>for</literal> attribute to point to the <literal>id</literal> identifier of the related component. The message is displayed after the <literal>FacesMessage</literal> message instance is created and added for the client identifier of the related component.</simpara>
<simpara>The <literal>&lt;rich:message&gt;</literal> component is automatically rendered after an Ajax request. This occurs without the use of an <literal>&lt;a4j:outputPanel&gt;</literal> component or a specific reference through the <literal>render</literal> attribute of the Ajax request source.</simpara>
<example id="exam-Component_Reference-richmessage-richmessage_example">
  <title>rich:message example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:outputText value="Zip:" /&gt;
&lt;h:inputText label="Zip" id="zip" required="true"
             value="#{userBean.zip}"&gt;
   &lt;f:validateLength minimum="4" maximum="9" /&gt;
&lt;/h:inputText&gt;
&lt;rich:message for="zip" ajaxRendered="true"/&gt;
</programlisting>


<simpara>The example contains a text input for zip codes. The simple validation requires the entered zip code to be between 4 and 9 characters long. The <literal>&lt;rich:message&gt;</literal> component references the input box, and reports any messages relating to the input validation.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richmessage-Appearance">
  <title>Appearance</title>
  <simpara>The <literal>showSummary</literal> attribute specifies whether to display only a summary of the full message. The full message can be displayed in a tool-tip when hovering the mouse over the summary.</simpara>
<simpara>Use CSS (Cascading Style Sheets) to customize the appearance and icon for the <literal>&lt;rich:message&gt;</literal> component. To use a custom icon, set the background-imageproperty to the icon graphic, as shown in <xref linkend="exam-Component_Reference-richmessage-Message_icons"/>. Refer to <xref linkend="sect-Component_Reference-richmessage-Style_classes_and_skin_parameters"/> for a complete list of style classes for the <literal>&lt;rich:message&gt;</literal> component.</simpara>
<example id="exam-Component_Reference-richmessage-Message_icons">
  <title>Message icons</title>


<screen>.rf-msg-err{
   background-image: url('#{facesContext.externalContext.requestContextPath}/images/icons/error.gif');
}
</screen>


<simpara>The example demonstrates how an icon for an error message could be added using CSS.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richmessage-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.RichMessage</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIRichMessage</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Message</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.MessageRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richmessage-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richmessage-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msg</literal>:: This class defines styles for the message itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msg-err</literal>:: This class defines styles for an error message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>errorColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msg-ftl</literal>:: This class defines styles for a fatal message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>errorColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msg-inf</literal>:: This class defines styles for an information message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msg-wrn</literal>:: This class defines styles for a warning message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>warningTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msg-ok</literal>:: This class defines styles for a basic OKmessage.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msg-sum</literal>:: <literal>.rf-msg-det</literal>:: These classes define styles for the summary or details of a message.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Output_and_messages-richmessages">
  <title><literal>&lt;rich:messages&gt;</literal></title>
  <simpara>The <literal>&lt;rich:messages&gt;</literal> components works similarly to the <literal>&lt;rich:message&gt;</literal> component, but can display all the validation messages added for the current view instead of just a single message. Refer to <xref linkend="sect-Component_Reference-Output_and_messages-richmessage"/> for details on the <literal>&lt;rich:message&gt;</literal> component.</simpara>
<figure id="figu-Component_Reference-richmessages-richmessages_component">
  <title>rich:messages component</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richmessages-richmessages_component.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richmessages-richmessages_component</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richmessages-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:messages&gt;</literal> component doesn&#8217;t require any extra attributes for basic usage. It displays all messages relating to requests from components.</simpara>
<simpara>To limit the messages to a specific component, use the <literal>for</literal> attribute to reference the component&#8217;s identifier.</simpara>
<simpara>To show only those messages that are not attached to specific components, set <literal>globalOnly="true"</literal>.</simpara>
<simpara>The <literal>&lt;rich:messages&gt;</literal> component is automatically rendered after an Ajax request. This occurs without the use of an <literal>&lt;a4j:outputPanel&gt;</literal> component or a specific reference through the <literal>render</literal> attribute of the Ajax request source.</simpara>

</section>
<section id="sect-Component_Reference-richmessages-Appearance">
  <title>Appearance</title>
  <simpara>The <literal>&lt;rich:messages&gt;</literal> component displays error messages for each validating component in the same container.</simpara>
<simpara>The <literal>&lt;rich:messages&gt;</literal> component can be further styled through CSS, the same as for the <literal>&lt;rich:message&gt;</literal> component. Refer to <xref linkend="sect-Component_Reference-richmessage-Appearance"/> for an example of message styling, and refer to <xref linkend="sect-Component_Reference-richmessages-Style_classes_and_skin_parameters"/> for a complete list of style classes for the <literal>&lt;rich:message&gt;</literal> component.</simpara>
<simpara>The layout of the messages can also be customized through CSS. By default, the messages are arranged in a block as shown in <xref linkend="figu-Component_Reference-richmessages-Messages_in_a_block"/>.</simpara>
<figure id="figu-Component_Reference-richmessages-Messages_in_a_block">
  <title>Messages in a block</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richmessages-Messages_in_a_block.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richmessages-Messages_in_a_block</phrase></textobject>
  </mediaobject>
</figure>
<simpara>Override the displayproperty for all CSS message classes to customize the layout as follows:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      Display messages in a list with no icons
    </term>
    
    <listitem>
      
      <simpara>To display the messages in a list format without the default icons, override the message styles as follows:</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>


<screen>.rf-msg-err, .rf-msgs-err, .rf-msg-ftl, .rf-msgs-ftl, .rf-msg-inf,
.rf-msgs-inf, .rf-msg-wrn, .rf-msgs-wrn, .rf-msg-ok, .rf-msgs-ok {
   display: list-item;
   margin-left: 20px;
   padding-left: 0px; }

.rf-msg-err, .rf-msgs-err{ background-image:none; }
</screen>


<figure id="figu-Component_Reference-richmessages-Messages_in_a_list">
  <title>Messages in a list</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richmessages-Messages_in_a_list.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richmessages-Messages_in_a_list</phrase></textobject>
  </mediaobject>
</figure>

<variablelist>
  
  
  <varlistentry>
    <term>
      Display in-line messages
    </term>
    
    <listitem>
      
      <simpara>To display the messages in line with text, override the message styles as follows:</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>


<screen>.rf-msg-err, .rf-msgs-err, .rf-msg-ftl, .rf-msgs-ftl, .rf-msg-inf,
.rf-msgs-inf, .rf-msg-wrn, .rf-msgs-wrn, .rf-msg-ok, .rf-msgs-ok { display:inline; }
</screen>


<figure id="figu-Component_Reference-richmessages-In-line_messages">
  <title>In-line messages</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richmessages-In-line_messages.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richmessages-In-line_messages</phrase></textobject>
  </mediaobject>
</figure>

</section>
<section id="sect-Component_Reference-richmessages-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.RichMessages</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIRichMessages</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Messages</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.MessagesRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richmessages-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richmessages-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msgs</literal>:: This class defines styles for the message itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-size</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msgs-err</literal>:: This class defines styles for an error message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>errorColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msgs-ftl</literal>:: This class defines styles for a fatal message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>errorColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msgs-inf</literal>:: This class defines styles for an information message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msgs-wrn</literal>:: This class defines styles for a warning message.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>warningTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msgs-ok</literal>:: This class defines styles for a basic OKmessage.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-msgs-sum</literal>:: <literal>.rf-msgs-det</literal>:: These classes define styles for the summary or details of a message.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Output_and_messages-richnotify">
  <title><literal>&lt;rich:notify&gt;</literal></title>
  <simpara>The <literal>&lt;rich:notify&gt;</literal> component serves for advanced user interaction, using notification boxes to give the user instant feedback on what&#8217;s happening within the application. Each time this component is rendered, a floating notification box is displayed in the selected corner of the browser screen.</simpara>
<section id="sect-Component_Reference-richnotify-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:notify&gt;</literal> has two message customization attributes: <literal>summary</literal> is short text summarizing the message, while <literal>detail</literal> configures the detailed body of the message. Both attributes have their counterparts in form of facets with the same names as the corresponding attributes.</simpara>

</section>
<section id="sect-Component_Reference-richnotify-Customizing_notifications">
  <title>Customizing notifications</title>
  <simpara>A notification appears on the page each time it is rendered, either on full-page or ajax requests. The notification remains on the screen for 8 seconds and then disappears. Users can close the notification with the close button in the top-right corner of the notification.</simpara>
<simpara>Notification stacks can be used to create sequences. For customization of stacking see the <literal>&lt;rich:notifyStack&gt;</literal> component.</simpara>
<simpara>There are several attributes that can change default behavior:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>sticky</literal>: notifications does not disappear automatically, they needs to be closed explicitly with close button (this attribute can&#8217;t be used together with <literal>nonblocking</literal> and <literal>stayTime</literal>)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>stayTime</literal>: configures how long notification stays on the screen before it disappears (in miliseconds)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>styleClass</literal>: defines the class customizing the notification</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>nonblocking</literal>: defines notifications which becomes partially transparent and user can click through. Non-blocking notifications don&#8217;t have close button.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>nonblockingOpacity</literal>: defines opacity of nonblocking notifications when mouse hovers over notification (decimal number between 0 and 1)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>showShadow</literal>: defines whether shadow will be displayed under the notification</simpara>
      
    </listitem>
  
</itemizedlist>

<note>
  
  

<literallayout class="monospaced">Nonblocking notifications can be clicked through, but because they are using jQuery mechanism to bypass events, only jQuery event handlers are triggered. IThis means that standard links won't be triggered.</literallayout>


  
</note>

</section>
<section id="sect-Component_Reference-richnotify-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Notify</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UINotify</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Notify</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.NotifyRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richnotify-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <simpara>Note that skinning is common for <literal>&lt;rich:notify&gt;</literal>, <literal>&lt;rich:notifyMessage&gt;</literal> and <literal>&lt;rich:notifyMessages&gt;</literal></simpara>
<table id="tabl-richnotify-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf</literal>:: This class defines styles for notification</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-shdw</literal>:: This class defines style of the shadow under notification box.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>headerBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>headerTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-cnt</literal>:: This class defines style of the content of notification box.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalBackgroundColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-ico</literal>:: This class defines style for notification icon.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-sum</literal>:: This class defines style for notification message summary.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-det</literal>:: This class defines style for notification message detail.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-cls</literal>:: This class defines style for element wrapping close button.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-cls-ico</literal>:: This class defines style for close button icon.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Output_and_messages-richnotifyMessage">
  <title><literal>&lt;rich:notifyMessage&gt;</literal></title>
  <section id="sect-Component_Reference-richnotifyMessage-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>&lt;rich:notifyMessage&gt;</literal> component is built on top of <literal>&lt;rich:notify&gt;</literal>, the difference is in usage. The <literal>&lt;rich:notifyMessage&gt;</literal> component displays <literal>FacesMessage</literal> s associated with a given component, similar to <literal>&lt;rich:message&gt;</literal>: one notification is displayed for first <literal>FacesMessage</literal> in the stack that is risen either programatically or during conversion/validation of the component. The severity of the message determines the color and icon of the resulting notification.</simpara>
<simpara>For customization of notification behavior, please refer to <link linkend="sect-Component_Reference-richnotify-Customizing_notifications">Customizing notifications</link> of <literal>&lt;rich:notify&gt;</literal>.</simpara>

</section>
<section id="sect-Component_Reference-richnotifyMessage-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.HtmlNotifyMessage</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.html.HtmlNotifyMessage</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Message</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.NotifyMessageRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richnotifyMessage-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <simpara>Note that <literal>&lt;rich:notifyMessage&gt;</literal> shares common classes with <literal>&lt;rich:notify&gt;</literal>, since there is exactly one notification rendered for each JSF message.</simpara>
<simpara>The <literal>&lt;rich:notifyMessage&gt;</literal> specific classes are redefining the look for various message severity levels.</simpara>
<table id="tabl-richnotifyMessage-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-inf</literal>:: This class defines styles for an informative message.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-wrn</literal>:: This class defines styles for a warning notifications.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-err</literal>:: This class defines styles for a error notifications.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-ftl</literal>:: This class defines styles for a fatal notifications.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Output_and_messages-richnotifyMessages">
  <title><literal>&lt;rich:notifyMessages&gt;</literal></title>
  <simpara>The <literal>&lt;rich:notifyMessages&gt;</literal> component is the same as the <literal>&lt;rich:notifyMessage&gt;</literal> component, but each of the available messages generates one notification.</simpara>
<simpara><literal>&lt;rich:notifyMessages&gt;</literal> shares the same set of attributes with <literal>&lt;rich:notifyMessage&gt;</literal></simpara>
<simpara id="figu-Component_Reference-richnotifyMessages-richnotifyMessages">.
<inlinemediaobject>
  <imageobject>
    <imagedata fileref=":images/figu-Component_Reference-richnotifyMessages-richnotifyMessages.png" width="200"/>
  </imageobject>
  <textobject><phrase>figu-Component_Reference-richnotifyMessages-richnotifyMessages</phrase></textobject>
</inlinemediaobject></simpara>
<section id="sect-Component_Reference-richnotifyMessages-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.HtmlNotifyMessages</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.html.HtmlNotifyMessages</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>javax.faces.Messages</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.NotifyMessagesRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richnotifyMessages-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <simpara><literal>&lt;rich:notifyMessages&gt;</literal> shares style classes with <literal>&lt;rich:notifyMessage&gt;</literal>.</simpara>

</section>

</section>
<section id="sect-Component_Reference-Output_and_messages-richnotifyStack">
  <title><literal>&lt;rich:notifyStack&gt;</literal></title>
  <simpara>Notifications emited by <literal>&lt;rich:notify&gt;</literal>, <literal>&lt;rich:notifyMessage&gt;</literal> and <literal>&lt;rich:notifyMessages&gt;</literal> are displayed in top-right corner of the screen by default.</simpara>
<simpara>It is <literal>&lt;rich:notifyStack&gt;</literal> which defines where messages will appear and handles their stacking.</simpara>
<simpara>Stack also provides way how to remove messages from screen - when stack is re-rendered, current notifications are destroyed, freeing place for new notifications.</simpara>
<section id="sect-Component_Reference-richnotifyStack-Basic_usage">
  <title>Basic usage</title>
  <simpara>They are three alternative ways to bind notifications with a stack:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><emphasis>wrapping</emphasis>: nesting <literal>&lt;rich:notify&gt;</literal>, <literal>&lt;rich:notifyMessage&gt;</literal> or <literal>&lt;rich:notifyMessages&gt;</literal> binds notifications with the stack in which they are wrapped</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><emphasis>binding by id</emphasis>: notification can be bound directly to a stack using it&#8217;s <literal>componentId</literal> in the <literal>stack</literal> attribute</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><emphasis>using default stack</emphasis>: a default stack is used when no other binding is defined for a given notification</simpara>
      
    </listitem>
  
</itemizedlist>



<programlisting language="XML" linenumbering="unnumbered">&lt;rich:notifyStack position="bottomRight"&gt;
    &lt;rich:notifyMessages /&gt;
&lt;/rich:notifyStack&gt;</programlisting>


<simpara>The sample above defines the stack explicitly, where notifications use the stack in which they are wrapped.</simpara>
<simpara>The sample bellow uses a notification rendered into the top-left corner of the screen. The notification is bound to a stack using it&#8217;s id.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:notifyStack id="leftStack" position="topLeft" /&gt;

&lt;rich:notify stack="leftStack" /&gt;</programlisting>



</section>
<section id="sect-Component_Reference-richnotifyStack-Positioning_notifications">
  <title>Positioning notifications</title>
  <simpara>To redefine the position of a notification, one needs to define a stack and bind it with the given notification.</simpara>
<simpara><literal>&lt;rich:notifyStack&gt;</literal> uses the <literal>position</literal> attribute to place the stack and it&#8217;s notifications into one of four corners: <literal>topRight</literal> (default), <literal>bottomRight</literal>, <literal>bottomLeft</literal>, <literal>topLeft</literal>.</simpara>

</section>
<section id="sect-Component_Reference-richnotifyStack-Stacking_notifications">
  <title>Stacking notifications</title>
  <simpara>There are two attributes which influences how notifications are placed into a stack:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>method</literal>: defines where new notifications are placed and how they are removed. Options: <literal>first</literal> (default), <literal>last</literal>.
<literal>direction</literal>: defines in which direction will be messages stacked. Options: <literal>vertical</literal> (default), <literal>horizontal</literal></simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>The following sample shows a stack which will place new notifications up front - the incoming message will appear first, causing all notifications currently in stack to shift. Subsequently, messages at the end of stack will be then removed.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:notifyStack method="first" /&gt;</programlisting>


<simpara>On the other hand, stacking method <literal>last</literal> provides a method to place messages on the end of the stack, and when removing a notification, it is removed from the start, causing all other notifications to shift.</simpara>

</section>
<section id="sect-Component_Reference-richnotifyStack-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.NotifyStack</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UINotifyStack</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.NotifyStack</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.NotifyStackRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richnotifyStack-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richnotifyStack-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-pos-tl</literal>:: This class defines where top-left stack of notification will be positioned</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-pos-tr</literal>:: This class defines where top-right stack of notification will be positioned</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-ntf-pos-bl</literal>:: This class defines where bottom-left stack of notification will be positioned</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Output_and_messages-richprogressBar">
  <title><literal>&lt;rich:progressBar&gt;</literal></title>
  <simpara>The <literal>&lt;rich:progressBar&gt;</literal> component displays a progress bar to indicate the status of a process to the user. It can update either through Ajax or on the client side, and the look and feel can be fully customized.</simpara>
<figure id="figu-Component_Reference-richprogressBar-richprogressBar">
  <title><literal>&lt;rich:progressBar&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richprogressBar-richprogressBar.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richprogressBar-richprogressBar</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richprogressBar-Basic_usage">
  <title>Basic usage</title>
  <simpara>Basic usage of the <literal>&lt;rich:progressBar&gt;</literal> component requires the <literal>value</literal> attribute, which points to the property that holds the current progress value. When the value is greater than or equal to the minimum value ( <literal>0</literal> by default), the progress bar becomes active, and starts sending Ajax requests if in <literal>ajax</literal> mode.</simpara>
<example id="exam-Component_Reference-richprogressBar-Basic_usage">
  <title>Basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:progressBar value="#{bean.incValue}" /&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richprogressBar-Customizing_the_appearance">
  <title>Customizing the appearance</title>
  <simpara>By default, the minimum value of the progress bar is <literal>0</literal> and the maximum value of the progress bar is <literal>100</literal>. These values can be customized using the <literal>minValue</literal> and <literal>maxValue</literal> attributes respectively.</simpara>
<simpara>The progress bar can be labeled in one of two ways:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using the <literal>label</literal>  attribute
    </term>
    
    <listitem>
      
      <simpara>The content of the <literal>label</literal> attribute is displayed over the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<example id="exam-Component_Reference-richprogressBar-Using_the_label_attribute">
  <title>Using the <literal>label</literal> attribute</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:progressBar value="#{bean.incValue}" id="progrs" label="#{bean.incValue} % complete"/&gt;
</programlisting>



</example>

<variablelist>
  
  
  <varlistentry>
    <term>
      Using nested child components
    </term>
    
    <listitem>
      
      <simpara>Child components, such as the JSF <literal>&lt;h:outputText&gt;</literal> component, can be nested in the <literal>&lt;rich:progressBar&gt;</literal> component to display over the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<example id="exam-Component_Reference-richprogressBar-Using_nested_child_components">
  <title>Using nested child components</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:progressBar value="#{bean.incValue}"&gt;
    &lt;h:outputText value="#{bean.incValue} % complete"/&gt;
&lt;/rich:progressBar&gt;
</programlisting>



</example>
<simpara>Define the <literal>initial</literal> and <literal>finish</literal> facets to customize the progress bar&#8217;s appearance before progress has started and after progress has finished. When the current progress bar value is less than the minimum value, the <literal>initial</literal> facet is displayed. When the current progress bar is greater than the maximum value, the <literal>finish</literal> facet is displayed.</simpara>
<example id="exam-Component_Reference-richprogressBar-Initial_and_complete_states">
  <title>Initial and finished states</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:progressBar value="#{bean.incValue1}"&gt;
    &lt;f:facet name="initial"&gt;
        &lt;h:outputText value="Process has not started"/&gt;
    &lt;/f:facet&gt;
    &lt;f:facet name="finish"&gt;
        &lt;h:outputText value="Process has completed"/&gt;
    &lt;/f:facet&gt;
&lt;/rich:progressBar&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richprogressBar-Update_mode">
  <title>Update mode</title>
  <simpara>The mode for updating the progress bar is determined by the <literal>mode</literal> attribute, which can have one of the following values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>The progress bar updates in the same way as the <literal>&lt;a4j:poll&gt;</literal> component. The <literal>&lt;rich:progressBar&gt;</literal> component repeatedly polls the server for the current progress value.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>The progress bar must be explicitly updated on the client side through the JavaScript API.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richprogressBar-Using_set_intervals">
  <title>Using set intervals</title>
  <simpara>The <literal>&lt;rich:progressBar&gt;</literal> component can be set to constantly poll for updates at a constant interval. Use the <literal>interval</literal> component to set the interval in milliseconds. The progress bar is updated whenever the polled value changes. Polling is only active when the <literal>enabled</literal> attribute is set to <literal>true</literal>.</simpara>
<example id="exam-Component_Reference-richprogressBar-Using_set_intervals">
  <title>Using set intervals</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:progressBar value="#{bean.incValue1}" id="progress" interval="900" enabled="#{bean.enabled1}"/&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richprogressBar-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:progressBar&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>getValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the current value displayed on the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>setValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Set the current value to display on the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getMinValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the minimum value for the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>getMaxValue()</literal>
    </term>
    
    <listitem>
      
      <simpara>Return the maximum value for the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>disable()</literal>
    </term>
    
    <listitem>
      
      <simpara>Disables the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>enable()</literal>
    </term>
    
    <listitem>
      
      <simpara>Enables the progress bar.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>isEnabled()</literal>
    </term>
    
    <listitem>
      
      <simpara>Returns a boolean value indicating whether the progress bar is enabled.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richprogressBar-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.ProgressBar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIProgressBar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.ProgressBar</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.ProgressBarRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richprogressBar-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richprogressBar-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pb-lbl</literal>:: This class defines styles for labels on the progress bar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pb-prgs</literal>:: This class defines styles for the progressed portion of the progress bar.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>panelBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>selectControlColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>background-color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-pb-init</literal>:: <literal>.rf-pb-fin</literal>:: These classes define styles for the initial state and finished state.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalTextColor</literal></simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>color</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>
<section id="sect-Component_Reference-Output_and_messages-richtooltip">
  <title><literal>&lt;rich:tooltip&gt;</literal></title>
  <simpara>The <literal>&lt;rich:tooltip&gt;</literal> component provides an informational tool-tip. The tool-tip can be attached to any control and is displayed when hovering the mouse cursor over the control.</simpara>
<figure id="figu-Component_Reference-richtooltip-richtooltip">
  <title><literal>&lt;rich:tooltip&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richtoolTip-richtoolTip.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richtoolTip-richtoolTip</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richtooltip-Basic_usage">
  <title>Basic usage</title>
  <simpara>For basic usage, define the tool-tip text using the <literal>value</literal> attribute. The <literal>&lt;rich:tooltip&gt;</literal> component is then automatically attached to the parent element, and is usually shown when the mouse cursor hovers.</simpara>
<simpara>Alternatively, the content of the tool-tip can be defined inside the <literal>&lt;rich:tooltip&gt;</literal> tags, and the <literal>value</literal> attribute is not used. This allows HTML tags to be used to define the content, and provides for rich content such as images, links, buttons, and other RichFaces components.</simpara>
<example id="exam-Component_Reference-richtooltip-Defining_tool-tip_content">
  <title>Defining tool-tip content</title>

<variablelist>
  
  
  <varlistentry>
    <term>
      Basic content
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel&gt;
    &lt;rich:tooltip value="This is a tool-tip."/&gt;
&lt;/rich:panel&gt;
</programlisting>



<variablelist>
  
  
  <varlistentry>
    <term>
      Rich content
    </term>
    
  </varlistentry>
  
</variablelist>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel&gt;
    &lt;rich:tooltip&gt;
        This is a &lt;b&gt;tool-tip&lt;/b&gt;.
    &lt;/rich:tooltip&gt;
&lt;/rich:panel&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richtooltip-Attaching_the_tool-tip_to_another_component">
  <title>Attaching the tool-tip to another component</title>
  <simpara>If not otherwise specified, the tool-tip is attached to the parent element in which it is defined. The <literal>target</literal> attribute is used to attach the tool-tip to another component, pointing to the target component&#8217;s <literal>id</literal> identifier. This allows the <literal>&lt;rich:tooltip&gt;</literal> component to be specified outside the target element. This approach is demonstrated in <xref linkend="exam-Component_Reference-richtooltip-Attaching_the_tool-tip"/>.</simpara>
<example id="exam-Component_Reference-richtooltip-Attaching_the_tool-tip">
  <title>Attaching the tool-tip</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel id="panelId"&gt;
...
&lt;/rich:panel&gt;

&lt;rich:tooltip value="This is a tool-tip." target="panelId"/&gt;
</programlisting>



</example>
<simpara>The <literal>&lt;rich:tooltip&gt;</literal> component can alternatively be left unattached, and is instead invoked through an event handler on the target component. To leave the <literal>&lt;rich:tooltip&gt;</literal> component unattached, set <literal>attached="false"</literal>, and define the event handler to trigger the tool-tip on the target component. This approach is demonstrated in <xref linkend="exam-Component_Reference-richtooltip-Unattached_tool-tips"/>. When leaving the <literal>&lt;rich:tooltip&gt;</literal> component unattached, ensure it has an <literal>id</literal> identifier defined. If it is defined outside the target element, it must be nested in an <literal>&lt;h:form&gt;</literal> component.</simpara>
<example id="exam-Component_Reference-richtooltip-Unattached_tool-tips">
  <title>Unattached tool-tips</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:panel id="panelId" onclick="#{rich:component('tooltipId')}.show(event);" /&gt;

&lt;h:form&gt;
    &lt;rich:tooltip id="toolTipId" attached="false" value="This is a tool-tip."/&gt;
&lt;/h:form&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richtooltip-Appearance">
  <title>Appearance</title>
  <simpara>By default, the <literal>&lt;rich:tooltip&gt;</literal> component is positioned intelligently based on the position of the mouse cursor. Use the <literal>jointPoint</literal> attribute to specify a corner of the target component at which to display the tool-tip instead, and use the <literal>direction</literal> attribute to specify the direction the tool-tip will appear relative to that corner. Possible values for both attributes are <literal>top-left</literal>, <literal>top-right</literal>, <literal>bottom-left</literal>, and <literal>bottom-right</literal>. Use the <literal>horizontalOffset</literal> and <literal>verticalOffset</literal> attributes to specify the horizontal offset and vertical offset at which to display the tool-tip.</simpara>
<simpara>Use the <literal>showEvent</literal> attribute to specify when the tool-tip is shown. By default it appears when the attached component is hovered-over with the mouse. Use the <literal>hideEvent</literal> attribute to specify when the tool-tip is hidden. The default value is <literal>none</literal>, so the tool-tip remains shown. However, it can be linked to an event on the target component, such as the <literal>mouseout</literal> event.</simpara>
<simpara>Set <literal>followMouse="true"</literal> to cause the tool-tip to follow the user&#8217;s mouse movements.</simpara>
<simpara>Advanced appearance features are demonstrated in <xref linkend="exam-Component_Reference-richtooltip-Advanced_tool-tip_usage"/>.</simpara>

</section>
<section id="sect-Component_Reference-richtooltip-Update_mode">
  <title>Update mode</title>
  <simpara>The mode for updating the tool-tip is determined by the <literal>mode</literal> attribute, which can have one of the following values:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>ajax</literal>
    </term>
    
    <listitem>
      
      <simpara>The tool-tip content is requested from the server with every activation.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>client</literal>
    </term>
    
    <listitem>
      
      <simpara>The tool-tip content is rendered once on the server. An external submit causes the content to re-render.
When using <literal>mode="ajax"</literal>, define the <literal>defaultContent</literal> facet. The tool-tip displays the content of the <literal>defaultContent</literal> facet while loading the actual content from the server.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<example id="exam-Component_Reference-richtooltip-Advanced_tool-tip_usage">
  <title>Advanced tool-tip usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:commandLink value="Simple Link" id="link"&gt;
    &lt;rich:tooltip followMouse="true" direction="topRight" mode="ajax" value="#{bean.toolTipContent}"
                  horizontalOffset="5" verticalOffset="5" layout="block"&gt;
        &lt;f:facet name="defaultContent"&gt;
            &lt;f:verbatim&gt;Loading...&lt;/f:verbatim&gt;
        &lt;/f:facet&gt;
    &lt;/rich:tooltip&gt;
&lt;/h:commandLink&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richtooltip-richtooltip_client-side_events">
  <title><literal>&lt;rich:tooltip&gt;</literal> client-side events</title>
  <simpara>The <literal>&lt;rich:tooltip&gt;</literal> component supports the following client-side events:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>click</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the tool-tip is clicked with the mouse.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>dblclick</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the tool-tip is double-clicked with the mouse.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>mouseout</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the mouse cursor leaves the tool-tip.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>mousemove</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the mouse cursor moves over the tool-tip.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>mouseover</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the mouse cursor hovers over the tool-tip.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>show</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the tool-tip is shown.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>complete</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the tool-tip is completed.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hide</literal>
    </term>
    
    <listitem>
      
      <simpara>This event is activated when the tool-tip is hidden.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtooltip-JavaScript_API">
  <title>JavaScript API</title>
  <simpara>The <literal>&lt;rich:tooltip&gt;</literal> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>show(event)</literal>
    </term>
    
    <listitem>
      
      <simpara>Show the tool-tip.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>hide()</literal>
    </term>
    
    <listitem>
      
      <simpara>Hide the tool-tip.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richtooltip-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Tooltip</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UITooltip</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Tooltip</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.TooltipRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richtooltip-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richtooltip-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tt</literal>:: This class defines styles for the tool-tip itself.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tt-loading</literal>:: This class defines styles for the tool-tip when it is loading.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tt-cnt</literal>:: This class defines styles for the tool-tip content.</simpara></entry>
        
        <entry align="left" valign="top"><simpara>No skin parameters.</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-tt-cntr</literal>:: This class defines styles for the progressed portion of the progress bar.</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>tipBorderColor</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>border-color</simpara></entry>
        
      </row>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>generalFamilyFont</literal></simpara></entry>
        
        <entry align="left" valign="top"><simpara>font-family</simpara></entry>
        
        <entry align="left" valign="top"><simpara><literal>generalSizeFont</literal></simpara></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Drag_and_drop">
  <title>Drag and drop</title>
  <simpara>Read this chapter for details on adding drag and drop support to controls.</simpara>
<section id="sect-Component_Reference-Drag_and_drop-richdragSource">
  <title><literal>&lt;rich:dragSource&gt;</literal></title>
  <simpara>The <literal>&lt;rich:dragSource&gt;</literal> component can be added to a component to indicate it is capable of being dragged by the user. The dragged item can then be dropped into a compatible drop area, designated using the <literal>&lt;rich:dropTarget&gt;</literal> component.</simpara>
<section id="sect-Component_Reference-richdragSource-Basic_usage">
  <title>Basic usage</title>
  <simpara>To add drag support to a component, attach the <literal>&lt;rich:dragSource&gt;</literal> component as a child element.</simpara>
<simpara>The <literal>type</literal> attribute must be specified, and can be any identifying string. Dragged items can only be dropped in drop zones where the <literal>type</literal> attribute of the <literal>&lt;rich:dragSource&gt;</literal> component is listed in the <literal>acceptedTypes</literal> attribute of the <literal>&lt;rich:dropTarget&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-richdragSource-Dragging_an_object">
  <title>Dragging an object</title>
  <simpara>Use the <literal>dragIndicator</literal> parameter to customize the appearance of a dragged object while it is being dragged. The <literal>dragIndicator</literal> parameter must point to the <literal>id</literal> identifier of a <literal>&lt;rich:dragIndicator&gt;</literal> component. If the <literal>dragIndicator</literal> attribute is not defined, the drag indicator appears as a clone of the <literal>&lt;rich:dragSource&gt;</literal> component&#8217;s parent control.</simpara>
<simpara>To bind data to the dragged object, use the <literal>dragValue</literal> attribute. The <literal>dragValue</literal> attribute specifies a server-side object, which is then bound to the parent component when it is dragged. This facilitates handling event data during a drop event.</simpara>

</section>
<section id="sect-Component_Reference-richdragSource-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.DragSource</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIDragSource</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DragSource</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.DragSourceRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Drag_and_drop-richdropTarget">
  <title><literal>&lt;rich:dropTarget&gt;</literal></title>
  <simpara>The <literal>&lt;rich:dropTarget&gt;</literal> component can be added to a component so that the component can accept dragged items. The dragged items must be defined with a compatible drop type for the <literal>&lt;rich:dragSource&gt;</literal> component.</simpara>
<section id="sect-Component_Reference-richdropTarget-Basic_usage">
  <title>Basic usage</title>
  <simpara>To allow dragged items to be dropped on a component, attach the <literal>&lt;rich:dropTarget&gt;</literal> component as a child element to the component.</simpara>
<simpara>The <literal>acceptedTypes</literal> attribute must be specified. The <literal>acceptedTypes</literal> attribute is a comma-separated list of strings that match the types of dragged items. Dragged items can only be dropped in drop zones where the <literal>type</literal> attribute of the <literal>&lt;rich:dragSource&gt;</literal> component is listed in the <literal>acceptedTypes</literal> attribute of the <literal>&lt;rich:dropTarget&gt;</literal> component.</simpara>
<simpara>The <literal>acceptedTypes</literal> attribute can optionally be set to either <literal>@none</literal> or <literal>@all</literal>. If set to <literal>@none</literal>, the component will not accept any type of dropped object. If set to <literal>@all</literal>, the component accepts all dropped objects. If the <literal>acceptedTypes</literal> attribute is not specified, the default value is <literal>null</literal>, which is the same as a <literal>@none</literal> setting.</simpara>

</section>
<section id="sect-Component_Reference-richdropTarget-Handling_dropped_data">
  <title>Handling dropped data</title>
  <simpara>To provide additional parameters for the server-side drop event, use the <literal>dropValue</literal> attribute.</simpara>
<simpara>The <literal>&lt;rich:dropTarget&gt;</literal> component raises the <literal>DropEvent</literal> server-side event when an object is dropped. The event uses the following parameters:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>dragSource</literal> identifies the component being dragged (the parent of the <literal>&lt;rich:dragSource&gt;</literal> component).</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>dragValue</literal> parameter is the content of the <literal>&lt;rich:dragSource&gt;</literal> component&#8217;s <literal>dragValue</literal> attribute.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>The <literal>dropValue</literal> parameter is the content of the <literal>&lt;rich:dropTarget&gt;</literal> component&#8217;s <literal>dropValue</literal> attribute.</simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richdropTarget-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.DropTarget</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIDropTarget</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DropTarget</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.DropTargetRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.DropHandler</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richdropTarget-Style_classes">
  <title>Style classes</title>
  
</section>

</section>
<section id="sect-Component_Reference-Drag_and_drop-richdragIndicator">
  <title><literal>&lt;rich:dragIndicator&gt;</literal></title>
  <formalpara>
  <title>rf-drp-hlight:: This class defines styles for a highlighted drop target.</title>
  <para>The <literal>&lt;rich:dragIndicator&gt;</literal> component defines a graphical element to display under the mouse cursor during a drag-and-drop operation.</para>
</formalpara>
<section id="sect-Component_Reference-richdragIndicator-Basic_usage">
  <title>Basic usage</title>
  <simpara>To use a drag indicator, define the inner content that appears during a drag event. No additional attributes are required. If a drag indicator is not used, a clone of the drag source is used instead.</simpara>

</section>
<section id="sect-Component_Reference-richdragIndicator-Styling_the_indicator">
  <title>Styling the indicator</title>
  <simpara>The drag indicator can be styled depending on the current state of the dragged element. There are three attributes for different states. The attributes reference the CSS class to use for styling the drag indicator when the dragged element is in the relevant state.</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>acceptClass</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>acceptClass</literal> attribute specifies the style when the dragged element is over an acceptable drop target. It indicates that the <literal>type</literal> attribute of the element&#8217;s <literal>&lt;rich:dragSource&gt;</literal> component matches <literal>acceptedTypes</literal> attribute of the drop target&#8217;s <literal>&lt;rich:dropTarget&gt;</literal> component.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>rejectClass</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>rejectClass</literal> attribute specifies the style when the dragged element is over a drop target that is not acceptable. It indicates that the <literal>type</literal> attribute of the element&#8217;s <literal>&lt;rich:dragSource&gt;</literal> component is not found in the <literal>acceptedTypes</literal> attribute of the drop target&#8217;s <literal>&lt;rich:dropTarget&gt;</literal> component.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>draggingClass</literal>
    </term>
    
    <listitem>
      
      <simpara>The <literal>draggingClass</literal> attribute specifies the style when the dragged element is being dragged. It indicates that the dragged element is not over a drop target.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richdragIndicator-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.DragIndicator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIDragIndicator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.DragIndicator</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.DragIndicatorRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richdragIndicator-Style_classes">
  <title>Style classes</title>
  
</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Layout_and_appearance">
  <title>Layout and appearance</title>
  <formalpara>
  <title>rf-ind-drag.default:: This class defines styles for the indicator when it is being dragged, and is not over any drop targets.</title>
  <para>Read this chapter to alter the layout and appearance of web applications using special components.</para>
</formalpara>
<section id="sect-Component_Reference-Layout_and_appearance-richjQuery">
  <title><literal>&lt;rich:jQuery&gt;</literal></title>
  <simpara>The <literal>&lt;rich:jQuery&gt;</literal> component applies styles and custom behavior to both JSF(JavaServer Faces) objects and regular DOM(Document Object Model) objects. It uses the jQueryJavaScript framework to add functionality to web applications.</simpara>
<section id="sect-Component_Reference-richjQuery-Basic_usage">
  <title>Basic usage</title>
  <simpara>The query triggered by the <literal>&lt;rich:jQuery&gt;</literal> component is specified using the <literal>query</literal> attribute.</simpara>
<simpara>With the query defined, the component is used to trigger the query as either a timed queryor a named query. The query can be bound to an event to act as an event handler. These different approaches are covered in the following sections.</simpara>

</section>
<section id="sect-Component_Reference-richjQuery-Defining_a_selector">
  <title>Defining a selector</title>
  <simpara>Any objects or lists of objects used in the query are specified using the <literal>selector</literal> attribute. The <literal>selector</literal> attribute references objects using the following method:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>The <literal>selector</literal> attribute can refer to the elements by using syntax of the jQuery Selectors (a superset of CSS selectors defined by W3C consortium) and additionally it expands JSF component IDs to client-side IDs (see the VDL documentation for the <literal>selector</literal> attribute).</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>If the <literal>selector</literal> attribute does not match the <literal>id</literal> identifier attribute of any JSF components or clients on the page, it instead uses syntax defined by the World Wide Web Consortium (W3C)for the CSSrule selector.</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>Refer to the syntax specification at link:http://api.jquery.com/category/selectors/ for full details.</simpara>
<simpara>Because the <literal>selector</literal> attribute can be either an <literal>id</literal> identifier attribute or CSS selector syntax, conflicting values could arise. <xref linkend="exam-Component_Reference-richjQuery-Avoiding_syntax_confusion"/> demonstrates how to use double backslashes to escape colon characters in <literal>id</literal> identifier values.</simpara>
<example id="exam-Component_Reference-richjQuery-Avoiding_syntax_confusion">
  <title>Avoiding syntax confusion</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form id="form"&gt;
    &lt;h:panelGrid id="menu"&gt;
        &lt;h:graphicImage value="pic1.jpg" /&gt;
        &lt;h:graphicImage value="pic2.jpg" /&gt;
    &lt;/h:panelGrid&gt;
&lt;/h:form&gt;
</programlisting>


<simpara>The <literal>id</literal> identifier for the <literal>&lt;h:panelGrid&gt;</literal> element is <literal>form:menu</literal>, which can conflict with CSS selector syntax. Double backslashes can be used to escape the colon character such that the identifier is read correctly instead of being interpreted as CSS selector syntax.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:jQuery selector="#form\\:menu img" query="..." /&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richjQuery-Event_handlers">
  <title>Event handlers</title>
  <simpara>Queries set as event handlers are triggered when the component specified in the <literal>selector</literal> attribute raises an event. The query is bound to the event defined using the <literal>event</literal> attribute.</simpara>
<simpara>Use the <literal>attachType</literal> attribute to specify how the event-handling queries are attached to the events:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>bind</literal>
    </term>
    
    <listitem>
      
      <simpara>This is the default for attaching queries to events. The event handler is bound to all elements currently defined by the <literal>selector</literal> attribute.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>live</literal>
    </term>
    
    <listitem>
      
      <simpara>The event handler is bound to all current and future elements defined by the <literal>selector</literal> attribute.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>one</literal>
    </term>
    
    <listitem>
      
      <simpara>The event handler is bound to all elements currently defined by the <literal>selector</literal> attribute. After the first invocation of the event, the event handler is unbound such that it no longer fires when the event is raised.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>

</section>
<section id="sect-Component_Reference-richjQuery-Timed_queries">
  <title>Timed queries</title>
  <simpara>Timed queries are triggered at specified times. This can be useful for calling simple methods when a page is rendered, or for adding specific functionality to an element. Use the <literal>timing</literal> attribute to specify the point at which the timed query is triggered:</simpara>

<variablelist>
  
  
  <varlistentry>
    <term>
      <literal>domready</literal>
    </term>
    
    <listitem>
      
      <simpara>This is the default behavior. The query is triggered when the document is loaded and the DOM is ready. The query is called as a jQuery()function.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
  <varlistentry>
    <term>
      <literal>immediate</literal>
    </term>
    
    <listitem>
      
      <simpara>The query is triggered immediately. The query is called as an in-line script.</simpara>
      
      
    </listitem>
    
  </varlistentry>
  
</variablelist>
<example id="exam-Component_Reference-richjQuery-richjQuery_example">
  <title><literal>&lt;rich:jQuery&gt;</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:dataTable id="customList" ... &gt;
   ...
&lt;/rich:dataTable&gt;

&lt;rich:jQuery selector="#customList tr:odd" timing="domready" query="addClass(odd)" /&gt;
</programlisting>


<simpara>In the example, the selector picks out the odd <literal>&lt;tr&gt;</literal> elements that are children of the element with an <literal>id="customlist"</literal> attribute. The query <literal>addClass(odd)</literal> is then performed on the selection during page loading ( <literal>load</literal>) such that the <literal>odd</literal> CSS class is added to the selected elements.</simpara>
<simpara><inlinemediaobject>
  <imageobject>
    <imagedata fileref="images/Component_Reference-richjQuery-richjQuery_example.png"/>
  </imageobject>
  <textobject><phrase>Component_Reference-richjQuery-richjQuery_example</phrase></textobject>
</inlinemediaobject></simpara>
<simpara>A table highlighted in a "zebra" fashion, with every odd row colored.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richjQuery-Named_queries">
  <title>Named queries</title>
  <simpara>Named queries are given a name such that they can be triggered by other functions or handlers. Use the <literal>name</literal> attribute to name the query. The query can then be accessed as though it were a JavaScript function using the specified <literal>name</literal> attribute as the function name.</simpara>
<simpara>Calls to the function must pass a direct reference ( <literal>this</literal>) to the calling object as a parameter. This is treated the same as an item defined through the <literal>selector</literal> attribute.</simpara>
<simpara>If the function requires extra parameters itself, these are provided in JavaScript Object Notation (JSON) syntax as a second parameter in the JavaScript call. The <literal>options</literal> namespace is then used in the <literal>&lt;rich:jQuery&gt;</literal> query to access the passed function parameters. <xref linkend="exam-Component_Reference-richjQuery-Calling_a_richjQuery_component_as_a_function"/> demonstrates the use of the <literal>name</literal> attribute and how to pass function parameters through the JavaScript calls.</simpara>
<example id="exam-Component_Reference-richjQuery-Calling_a_richjQuery_component_as_a_function">
  <title>Calling a <literal>&lt;rich:jQuery&gt;</literal> component as a function</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:graphicImage width="50" value="/images/price.png" onmouseover="enlargePic(this, {pwidth:'60px'})" onmouseout="releasePic(this)"  /&gt;
&lt;h:graphicImage width="50" value="/images/discount.png" onmouseover="enlargePic(this, {pwidth:'100px'})" onmouseout="releasePic(this)"  /&gt;
...
&lt;rich:jQuery name="enlargePic" query="animate({width:options.pwidth})" /&gt;
&lt;rich:jQuery name="releasePic" query="animate({width:'50px'})"/&gt;
</programlisting>


<simpara>The example enlarges the images when the mouse moves over them. The <literal>enlargePic</literal> and <literal>releasePic</literal> components are called like ordinary JavaScript functions from the image elements.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richjQuery-Dynamic_rendering">
  <title>Dynamic rendering</title>
  <simpara>The <literal>&lt;rich:jQuery&gt;</literal> component applies style and behavioral changes to DOM objects dynamically. As such, changes applied during an Ajax response are overwritten, and will need to be re-applied once the Ajax response is complete.</simpara>
<simpara>Any timed queries with the <literal>timing</literal> attribute set to <literal>domready</literal> may not update during an Ajax response, as the DOM document is not completely reloaded. To ensure the query is re-applied after an Ajax response, include the <literal>name</literal> attribute in the <literal>&lt;rich:jQuery&gt;</literal> component and invoke it using JavaScript from the <literal>complete</literal> event attribute of the component that triggered the Ajax interaction.</simpara>

</section>
<section id="sect-Component_Reference-richjQuery-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.JQuery</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIJQuery</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.JQuery</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.JQueryRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>

</chapter>
<chapter id="chap-Component_Reference-Functions">
  <title>Functions</title>
  <simpara>Read this chapter for details on special functions for use with particular components. Using JavaServer Faces Expression Language ( JSFEL), these functions can be accessed through the <literal>data</literal> attribute of components. Refer to <xref linkend="sect-Component_Reference-Events_and_JavaScript_interactions-data"/> for details on the <literal>data</literal> attribute.</simpara>
<section id="sect-Component_Reference-Functions-richclientId">
  <title><literal>rich:clientId</literal></title>
  <simpara>The <literal>rich:clientId('id')</literal> function returns the client identifier related to the passed component identifier ( <literal>'id'</literal>). If the specified component identifier is not found, <literal>null</literal> is returned instead.</simpara>

</section>
<section id="sect-Component_Reference-Functions-richcomponent">
  <title><literal>rich:component</literal></title>
  <simpara>The <literal>rich:component('id')</literal> function is equivalent to the <literal>RichFaces.$('clientId')</literal> code. It returns the client object instance based on the passed server-side component identifier ( <literal>'id'</literal>). If the specified component identifier is not found, <literal>null</literal> is returned instead. The function can be used to get an object from a component to call a JavaScript API function without using the <literal>&lt;rich:componentControl&gt;</literal> component.</simpara>

</section>
<section id="sect-Component_Reference-Functions-richelement">
  <title><literal>rich:element</literal></title>
  <simpara>The <literal>rich:element('id')</literal> function is a shortcut for the equivalent <literal>document.getElementById(#{rich:clientId('id')})</literal> code. It returns the element from the client, based on the passed server-side component identifier. If the specified component identifier is not found, <literal>null</literal> is returned instead.</simpara>

</section>
<section id="sect-Component_Reference-Functions-richjquery">
  <title><literal>rich:jQuery</literal></title>
  <simpara>The <literal>rich:jQuery('id')</literal> function is a shortcut for the equivalent <literal>jQuery('##{rich:clientId('id')})</literal> code. It returns the jQuery object for the element located by the passed server-side component identifier. If the specified component identifier is not found, <literal>null</literal> is returned instead.</simpara>

</section>
<section id="sect-Component_Reference-Functions-richfindComponent">
  <title><literal>rich:findComponent</literal></title>
  <simpara>The <literal>rich:findComponent('id')</literal> function returns the a UIComponent instance of the passed component identifier. If the specified component identifier is not found, <literal>null</literal> is returned instead.</simpara>
<example id="exam-Component_Reference-richfindComponent-richfindComponent_example">
  <title><literal>rich:findComponent</literal> example</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:inputText id="myInput"&gt;
   &lt;a4j:support event="keyup" render="outtext"/&gt;
&lt;/h:inputText&gt;
&lt;h:outputText id="outtext" value="#{rich:findComponent('myInput').value}" /&gt;
</programlisting>



</example>

</section>
<section id="sect-Component_Reference-Functions-richisUserInRole">
  <title><literal>rich:isUserInRole</literal></title>
  <simpara>The <literal>rich:isUserInRole(Object)</literal> function checks whether the logged-in user belongs to a certain user role, such as being an administrator. User roles are defined in the _web.xml_settings file.</simpara>
<example id="exam-Component_Reference-richisUserInRole-richisUserInRole_example">
  <title><literal>rich:isUserInRole</literal> example</title>
<simpara>The <literal>rich:isUserInRole(Object)</literal> function can be used in conjunction with the <literal>rendered</literal> attribute of a component to only display certain controls to authorized users.</simpara>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:editor value="#{bean.text}" rendered="#{rich:isUserInRole('admin')}"/&gt;
</programlisting>



</example>

</section>

</chapter>
<chapter id="chap-Component_Reference-Functionality_extension">
  <title>Functionality extension</title>
  <simpara>Read this chapter for details on miscellaneous components that provide extended functionality to web applications.</simpara>
<section id="sect-Component_Reference-Functionality_extension-richcomponentControl">
  <title><literal>&lt;rich:componentControl&gt;</literal></title>
  <simpara>The <literal>&lt;rich:componentControl&gt;</literal> behavior allows JavaScript API functions to be called on target components. The functions are called after defined events are triggered on the component to with the <literal>&lt;rich:componentControl&gt;</literal> behavior is attached. Initialization variants and activation events can be customized, and parameters can be passed to the target component.</simpara>
<section id="sect-Component_Reference-richcomponentControl-Basic_usage">
  <title>Basic usage</title>
  <simpara>The <literal>operation</literal> attribute is required to attach JavaScript functions to the parent component, along with either the <literal>target</literal> or <literal>selector</literal> attributes. Use the <literal>operation</literal> attribute to specify the JavaScript API function to perform. Use the <literal>target</literal> attribute to define the <literal>id</literal> identifier of the target component, or use the <literal>selector</literal> attribute to define a number of target components through the use of valid jQuery selectors.</simpara>
<simpara>Use the <literal>event</literal> attribute to specify the event that triggers the JavaScript API function call if it is different from the default triggering event for the parent component.</simpara>
<example id="exam-Component_Reference-richcomponentControl-richcomponentControl_basic_usage">
  <title><literal>&lt;rich:componentControl&gt;</literal> basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:commandButton value="Show Modal Panel"&gt;
    &lt;!--componentControl is attached to the commandButton--&gt;
    &lt;rich:componentControl target="ccModalPanelID" event="click" operation="show"/&gt;
&lt;/h:commandButton&gt;
</programlisting>


<simpara>The example contains a single command button, which when clicked shows the modal panel with the identifier <literal>ccModalPanelID</literal>.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richcomponentControl-Passing_parameters_to_API_methods">
  <title>Passing parameters to API methods</title>
  <simpara>The operation can receive parameters through nested <literal>&lt;f:param&gt;</literal> elements.</simpara>
<example id="exam-Component_Reference-richcomponentControl-Using_parameters">
  <title>Using parameters</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:componentControl event="click" target="modalPanel" operation="show"&gt;
   &lt;f:param value="width" name="500"/&gt;
&lt;/rich:componentControl&gt;
</programlisting>



</example>
<simpara>To group multiple parameters for a function, use the <literal>&lt;rich:hashParam&gt;</literal> component to create a hash map. Refer to <xref linkend="sect-Component_Reference-Functionality_extension-richhashParam"/> for details.</simpara>

</section>
<section id="sect-Component_Reference-richcomponentControl-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>client-behavior-renderer-type</literal>: <literal>org.richfaces.behavior.ComponentControlBehavior</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-id</literal>: <literal>org.richfaces.behavior.ComponentControlBehavior</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.taglib.ComponentControlHandler</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>behavior-class</literal>: <literal>org.richfaces.component.behavior.ComponentControlBehavior</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>client-behavior-renderer-class</literal>: <literal>org.richfaces.renderkit.html.ToggleControlRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Functionality_extension-richfocus">
  <title><literal>&lt;rich:focus&gt;</literal></title>
  <simpara>The <literal>&lt;rich:focus&gt;</literal> component allows one to manipulate the focus of components on a page. It is intended to be used with any input field.</simpara>
<section id="sect-Component_Reference-richfocus-Placement">
  <title>Placement</title>
  <simpara>The component will behave differently when placed:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>in a form - defines behavior for components in the given form</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>in a view (outside of forms) - defines behavior for components in all forms in the view</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>There can be only one focus per form.</simpara>
<simpara>If both, form- and view-based focuses are defined, the form one takes a priority.</simpara>

</section>
<section id="sect-Component_Reference-richfocus-Applying_focus">
  <title>Applying Focus</title>
  <simpara>The focus is applied each time it is rendered - either on form submission or after an AJAX request. Only focuses inside the form which is submitted are applied.</simpara>
<simpara>You can turn focusing-after-AJAX-requests off by setting the <literal>ajaxRendered</literal> attribute to <literal>false</literal>.</simpara>

</section>
<section id="sect-Component_Reference-richfocus-Validation_aware">
  <title>Validation-Aware</title>
  <simpara>The <literal>&lt;rich:focus&gt;</literal> component reflects the results of validation of components in a view. Focus is given to the first input component in the page which is invalid.</simpara>
<simpara>If all components are valid, then first component in the form is focused.</simpara>
<simpara>The order of input components is determined on the client-side and reflects the <literal>tabindex</literal> and position in the page. You can prioritize the focusing of a specific component by increasing its tabindex.</simpara>
<simpara>You can turn validation awareness off by setting the <literal>validationAware</literal> attribute to <literal>false</literal>.</simpara>
<figure id="figu-Component_Reference-richfocus-Validation_aware">
  <title>Validation-aware <literal>&lt;rich:focus&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richfocus-Validation_aware.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richfocus-Validation_aware</phrase></textobject>
  </mediaobject>
</figure>

</section>
<section id="sect-Component_Reference-richfocus-Preserving_focus">
  <title>Preserving Focus</title>
  <simpara>Focus can be configured to keep focus on the input component which had focus before sending the JSF request (using either AJAX or form submission).</simpara>
<example id="exam-Component_Reference-richfocus-richfocus_preserving_focus">
  <title><literal>&lt;rich:focus&gt;</literal> preserving focus</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:form&gt;
    &lt;rich:focus preserve="true" /&gt;

    &lt;h:inputText id="query" value="#{query}" /&gt;
    &lt;a4j:commandButton value="Search" render="output" /&gt;

    &lt;h:outputText value="Searched query:" /&gt;
    &lt;h:outputText id="output" value="#{query}" /&gt;
&lt;/h:form&gt;</programlisting>


<simpara>In the example above, everytime the user hits Search (or hits enter), the focus is given back to the query input after the request.</simpara>

</example>
<simpara>This configuration will take priority over any other focus setup.</simpara>

</section>
<section id="sect-Component_Reference-richfocus-Delaying_focus">
  <title>Delaying Focus</title>
  <simpara>In certain situations, focus needs to be applied with a delay - once suitable conditions are met.</simpara>
<simpara>By configuring a focus with the attribute <literal>delayed</literal> to <literal>true</literal>, the focus won&#8217;t be applied on initial page request.</simpara>
<simpara>Then it is possible to call the <literal>applyFocus()</literal> JavaScript API method in order to let the focus be applied.</simpara>

</section>
<section id="sect-Component_Reference-richfocus-Focus_Manager">
  <title>Focus Manager</title>
  <simpara>For a situation when none of the options above help one to achieve the desired focus behavior, one can use the server-side component <literal>FocusManager</literal>.</simpara>
<simpara>A component focus chosen by the <literal>FocusManager</literal> will take priority over any focus configuration.</simpara>
<example id="exam-Component_Reference-richfocus-Focus_Manager">
  <title><literal>&lt;rich:focus&gt;</literal> preserving focus</title>


<programlisting language="Java" linenumbering="unnumbered">FocusManager focusManager = ServiceTracker.getService(FocusManager.class);
focusManager.focus("input2");</programlisting>



</example>

</section>
<section id="sect-Component_Reference-richfocus-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Focus</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIFocus</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Focus</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.FocusRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Functionality_extension-richhotKey">
  <title><literal>&lt;rich:hotKey&gt;</literal></title>
  <simpara>The <literal>&lt;rich:hotKey&gt;</literal> component allows one to register hot keys for the page or particular elements and to define client-side processing functions for these keys.</simpara>
<section id="sect-Component_Reference-richhotKey-Basic_usage">
  <title>Basic usage</title>
  <simpara>There are two ways to register <literal>&lt;rich:hotKey&gt;</literal>:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>place it anywhere on the page. In this case the <literal>&lt;rich:hotKey&gt;</literal> component is attached to the whole page. This is the default scenario.</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>attach it to specific elements by defining the <literal>selector</literal> attribute. This attribute uses the syntax of the jQuery Selectors (a superset of CSS selectors defined by W3C consortium) and additionally it expands JSF component IDs to client-side IDs (see the VDL documentation for the <literal>selector</literal> attribute).</simpara>
      
    </listitem>
  
</itemizedlist>

<simpara>The <literal>key</literal> attribute defines the hot key itself, which is processed by the component.</simpara>
<simpara>The key sequences can be defined using a " <literal>+</literal>" key separator. The key sequence modifiers needs to be defined in alphabetical order, e.g. <literal>alt+ctrl+shift</literal>.</simpara>
<simpara>Hot key processing can be disabled by setting <literal>rendered</literal> to <literal>false</literal>.</simpara>
<example id="exam-Component_Reference-richhotkey-richhotkey_basic_usage">
  <title><literal>&lt;rich:hotKey&gt;</literal> basic usage</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:hotKey key="ctrl+z"&gt;
    &lt;rich:componentControl target="popup" operation="show" /&gt;
&lt;/rich:hotKey&gt;

&lt;rich:popupPanel id="popup"&gt;
	...
&lt;/rich:popupPanel&gt;</programlisting>


<simpara>The example contains <literal>&lt;rich:hotKey&gt;</literal> which handles the <literal>Ctrl+Z</literal> key sequence on the whole page. When the key sequence is pressed, the <literal>&lt;rich:popupPanel&gt;</literal> is displayed.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richhotKey-Event_processing">
  <title>Event processing</title>
  <simpara>The <literal>enabledInInput</literal> attribute enables the hot key event processing when form inputs are focused. This attribute is <literal>false</literal> by default.</simpara>
<simpara>The <literal>preventDefault</literal> attribute specifies whether the hot key binding should prevent default browser-specific actions to be taken (e.g. <literal>Ctrl+A</literal> hot key selecting all available text, Ctrl+B opening bookmarks bar, etc.). This attribute has a default value of <literal>true</literal>.</simpara>
<note>
  <title>Cross-browser support for preventing default actions</title>
  
<simpara>Even though RichFaces instructs the browser to prevent the default action, browser implementations do not support preventing browser&#8217;s native actions for selected key combinations.</simpara>
<simpara>Although the inability to prevent default action is not usual, you may experience that both the programatically-defined action and the browser&#8217;s native action are triggered (e.g. native popup appears).</simpara>
<simpara>To keep an application accessible, it is convenient to not depend on hot keys or hot key combinations heavily. Best practice is using a hot key only as shortcut for a given action.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-richhotKey-Event_handlers">
  <title>Event handlers</title>
  <simpara>The following event handlers could be used to trigger client-side behaviors or to invoke javascript directly:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara><literal>keydown</literal> (default event) is fired when the hot key sequence is initiated (the keys are down)</simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>keyup</literal> is fired when the hot key sequence is finished (the keys are up)</simpara>
      
    </listitem>
  
</itemizedlist>

<example id="exam-Component_Reference-richhotKey-richhotkKey_event_handlers">
  <title><literal>&lt;rich:hotKey&gt;</literal> event handlers</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;rich:hotKey key="ctrl+a" onkeyup="alert('Ctrl+A was pressed')" /&gt;</programlisting>



</example>
<note>
  <title>Hot Key in Editor</title>
  
<simpara>The <literal>&lt;rich:editor&gt;</literal> uses <literal>&lt;iframe&gt;</literal> for the editable area.</simpara>
<simpara>The <literal>&lt;iframe&gt;</literal> doesn&#8217;t allow one to propagate events outside of the <literal>&lt;rich:editor&gt;</literal>, making <literal>&lt;rich:hotKey&gt;</literal> unusable for handling events from <literal>&lt;rich:editor&gt;</literal>.</simpara>
<simpara>The CKEditor specific event handling mechanism should be used instead.</simpara>

  
</note>

</section>
<section id="sect-Component_Reference-richhotKey-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.HotKey</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIHotKey</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.HotKey</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.HotKeyRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Functionality_extension-richhashParam">
  <title><literal>&lt;rich:hashParam&gt;</literal></title>
  <simpara>The <literal>&lt;rich:hashParam&gt;</literal> component allows client-side parameters to be grouped into a hash map. The hash map can then be passed to the client JavaScript API functions of any RichFaces component.</simpara>
<section id="sect-Component_Reference-richhashParam-Basic_usage">
  <title>Basic usage</title>
  <simpara>Nest parameter tags in the <literal>&lt;rich:hashParam&gt;</literal> component to group them in the hash map. The hash map itself can then be passed as a function parameter.</simpara>
<example id="exam-Component_Reference-richhashParam-richhashParam">
  <title><literal>&lt;rich:hashParam&gt;</literal></title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:commandButton value="Show popup"&gt;
   &lt;rich:componentControl target="popupPanel" operation="show"&gt;
      &lt;a4j:param noEscape="true" value="event" /&gt;
      &lt;rich:hashParam&gt;
         &lt;f:param name="width" value="500" /&gt;
         &lt;f:param name="height" value="300" /&gt;
         &lt;f:param name="minWidth" value="300" /&gt;
         &lt;f:param name="minHeight" value="150" /&gt;
         &lt;a4j:param noEscape="true" name="left" value="(jQuery(window).width()/2)-250" /&gt;
         &lt;a4j:param noEscape="true" name="top" value="(jQuery(window).height()/2)-150" /&gt;
      &lt;/rich:hashParam&gt;
   &lt;/rich:componentControl&gt;
&lt;/h:commandButton&gt;
</programlisting>


<simpara>The example illustrates the use of the <literal>&lt;rich:hashParam&gt;</literal> component to group multiple parameters into a hash map. The parameters are passed through to the <literal>show</literal> function pop-up panel with the <literal>popupPanel</literal> identifier.</simpara>

</example>

</section>
<section id="sect-Component_Reference-richhashParam-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.HashParam</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIHashParam</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.HashParam</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.HashParamRenderer</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>handler-class</literal>: <literal>org.richfaces.view.facelets.HashParamTag</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>

</section>
<section id="sect-Component_Reference-Functionality_extension-richplaceholder">
  <title><literal>&lt;rich:placeholder&gt;</literal></title>
  <simpara>The <literal>&lt;rich:placeholder&gt;</literal> component allows one to use functionality similar to the HTML5 <literal>placeholder</literal> attribute for input components.</simpara>
<simpara>This component brings a backward compatibility for HTML5 non-compliant browsers and some additional features:</simpara>

<itemizedlist>
  
  
    <listitem>
      <simpara>per-component styling using <literal>styleClass</literal> attribute</simpara>
      
    </listitem>
  
    <listitem>
      <simpara>application to multiple components at once using <literal>selector</literal> attribute</simpara>
      
    </listitem>
  
</itemizedlist>

<example id="exam-Component_Reference-richplaceholder-Input_components">
  <title><literal>&lt;rich:placeholder&gt;</literal> with input components</title>


<programlisting language="XML" linenumbering="unnumbered">&lt;h:outputLabel value="Input text:" /&gt;
&lt;h:inputText id="input"&gt;
    &lt;rich:placeholder value="Type text here..." /&gt;
&lt;/h:inputText&gt;

&lt;h:outputLabel value="Textarea:" /&gt;
&lt;h:inputTextarea id="textarea"&gt;
    &lt;rich:placeholder value="A space for long content..." /&gt;
&lt;/h:inputTextarea&gt;

&lt;h:outputLabel value="Date:" /&gt;
&lt;rich:calendar datePattern="dd/M/yyyy" enableManualInput="true"&gt;
    &lt;rich:placeholder value="dd/mm/yyyy" /&gt;
&lt;/rich:calendar&gt;</programlisting>



</example>
<figure id="figu-Component_Reference-richplaceholder-Input_components">
  <title><literal>&lt;rich:placeholder&gt;</literal></title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/figu-Component_Reference-richplaceholder-Input_components.png"/>
    </imageobject>
    <textobject><phrase>figu-Component_Reference-richplaceholder-Input_components</phrase></textobject>
  </mediaobject>
</figure>
<section id="sect-Component_Reference-richplaceholder-Reference_data">
  <title>Reference data</title>
  
<itemizedlist>
  
  
    <listitem>
      <simpara><literal>component-type</literal>: <literal>org.richfaces.Placeholder</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-class</literal>: <literal>org.richfaces.component.UIPlaceholder</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>component-family</literal>: <literal>org.richfaces.Placeholder</literal></simpara>
      
    </listitem>
  
    <listitem>
      <simpara><literal>renderer-type</literal>: <literal>org.richfaces.PlaceholderRenderer</literal></simpara>
      
    </listitem>
  
</itemizedlist>


</section>
<section id="sect-Component_Reference-richplaceholder-Style_classes_and_skin_parameters">
  <title>Style classes and skin parameters</title>
  <table id="tabl-richplaceholder-Style_classes_and_corresponding_skin_parameters" frame="all"
    rowsep="1" colsep="1">
  <title>Style classes (selectors) and corresponding skin parameters</title>
  
  <tgroup cols="3">
    
    <colspec colname="col_1" colwidth="33*"/>
    
    <colspec colname="col_2" colwidth="33*"/>
    
    <colspec colname="col_3" colwidth="33*"/>
    
    
    <thead>
      
      <row>
        
        <entry align="left" valign="top">Class (selector)</entry>
        
        <entry align="left" valign="top">Skin Parameters</entry>
        
        <entry align="left" valign="top">Mapped CSS properties</entry>
        
      </row>
      
    </thead>
    
    <tbody>
      
      <row>
        
        <entry align="left" valign="top"><simpara><literal>.rf-plhdr</literal>:: This class identifies which input elements have their placeholder text managed by the placeholder component. Use this class to apply custom styles to the placeholder text.</simpara></entry>
        
        <entry align="left" valign="top"></entry>
        
        <entry align="left" valign="top"></entry>
        
      </row>
      
    </tbody>
    
  </tgroup>
</table>

</section>

</section>

</chapter>
<appendix id="appe-Component_Reference-Revision_History">
  <title>Revision History</title>
  <simpara>1.0Mon Apr 11 2011SeanRogers
4.0.0.Final Release
1.1Wed Nov 16 2011BrianLeathemLukasFryc
4.1.0.Final Release
1.2Wed Feb 22 2011BrianLeathemLukasFryc
4.2.0.Final Release</simpara>

</appendix>

</chapter>

</book>