The value 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:

Use the mode attribute to determine how the suggestion list is requested:

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 selectFirst="false".

Setting autofill="true" causes the <rich:autocomplete> to fill the text field box with a matching suggestion as the user types.

To allow users to enter multiple values separated by specific characters, use the tokens 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 tokens=", " is set, the <rich:autocomplete> 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.

The <rich:autocomplete> component uses the JavaScript startsWith() method to create the list of suggestions. The filtering is performed on the client side. Alternatively, use the clientFilterFunction attribute to specify a custom filtering function. The custom function must accept two parameters: the subString parameter is the filtering value as typed into the text box by the user, and the value parameter is an item in the list of suggestions against which the subString must be checked. Each item is iterated through and passed to the function as the value 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.

The <rich:autocomplete> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

The <rich:calendar> 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 popup="false. This displays the full calendar without the text field and display button.

To add keyboard support for manual input, set enableManualInput="true". To disable the calendar from any user input, set disabled="true".

To change the appearance of the display button from the standard calendar icon, use the buttonIcon and buttonDisabledIcon attributes to replace the icon with a specified file. Alternatively, use the buttonLabel attribute to display text on the button without an icon. If buttonLabel is specified then both the buttonIcon and buttonDisabledIcon attributes are ignored. To hide the text field box, set showInput="false".

The calendar features a Today button for locating today’s date on the calendar. This can be set to three different values using the todayControlMode attribute:

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

Calendar also supports keyboard navigation, with the pop-up appearing when calendar gains focus, if enableManualInput="true" is set the pop-up can be brought up by the up arrow key.

The <rich:calendar> 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 defaultTime attribute. If the time is altered and a new date is selected, it will not reset unless resetTimeOnDateSelect="true" is specified.

The date selection feature is activated if the time is present in the datePattern attribute for the calendar.

Date and time strings can be formatted in a set pattern. Use standard locale formatting strings specified by ISO 8601 (for example, d/M/yy HH:mm a) with the datePattern attribute to format date and time strings.

To set the locale of the calendar, use the locale attribute. The calendar will render month and day names in the relevant language. For example, to set the calendar to the US locale, specify locale="en/US".

Use an application resource bundle to localize the calendar control labels. Define the following strings in the resource bundle:

Alternatively, use the org.richfaces.calendar resource bundle with Java Archive files ( JAR s) defining the same properties.

The look and feel of the <rich:calendar> 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 mode attribute.

When the mode attribute is not specified, the component uses the client mode. The client mode loads an initial portion of data within a set date range. The range can be defined by using the preloadDateRangeBegin and preloadDateRangeEnd attributes. Additional data requests for months outside the range are not sent.

Alternatively, with mode="ajax" the <rich:calendar> requests portions of data from the data model every time the month is switched. The data model can be defined through the dataModel attribute, which points to an object that implements the CalendarDataModel interface. If the dataModel attribute is not defined or has a value of null, the ajax mode functions the same as the client mode.

The <rich:calendar> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

Basic usage requires the value attribute to point to the expression for the current value of the component.

The dimensions of the editor can be managed using width and height attributes.

The readonly attribute can be used to switch the editor into a read-only mode.

The tabindex attribute specifies the position of the current element in the tabbing order for the current document.

There are several options to customize the style of the editor:

The basic set of <rich:editor> attributes allows you to support common use-cases for a WYSIWYG editor. However the underlying CKEditor implementation supports many more configuration options.

Use the config 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).

There are two ways to define the configuration: the config attribute or a facet named config. The facet takes precedence over attribute when both are defined.

<rich:editor config="startupFocus: #{userPreferences.startupFocus}" />



<rich:editor>

    <f:facet name="config">

        startupFocus: #{userPreferences.startupFocus}

    </f:facet>

</rich:editor>

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

The <rich:editor> supports a toolbar attribute, which is able to change the configuration of the toolbar’s button set. There are two configurations available: basic (default), full (enables all of the features).

It is also possible to define a custom toolbar using the CKEditor toolbar configuration in a config facet:

<rich:editor toolbar="CustomToolbar">

    <f:facet name="config">

        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' ] }

        ]

        </f:facet>

</rich:editor>

Note that toolbar name ( CustomToolbar) needs to match the toolbar_<name> configuration option.

The <rich:editor> component produces set of events for handling component specific interaction.

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

<rich:editor value="#{backingBean.editorValue}">

    <a4j:ajax event="change" render="editorOutput" />

    <a4j:ajax event="dirty" render="editorOutput">

        <a4j:attachQueue requestDelay="1000" />

    </a4j:ajax>

</rich:editor>



<a4j:outputPanel id="editorOutput">

    <h:outputText escape="false" value="#{backingBean.editorValue}" />

</a4j:outputPanel>

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.

The <rich:editor> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

Basic usage requires the fileUploadListener 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.

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 org.richfaces.fileUpload.createTempFiles context parameter of the web.xml settings file for the project. If the parameter is set to true, the files are uploaded to the temporary folder.

To limit the maximum size of the uploaded files, define the byte size with the maxfileSize parameter on the component or with org.richfaces.fileUpload.maxRequestSize context parameter of the web.xml settings file for the project. Locally set maxFileSize (if not set to 0) will override the global maxRequestSize.

Any file is accepted by rich:fileUpload component by default. There are several parameters available for limiting what can user upload to the server:

Set the immediateUpload attribute to true to upload files as soon as they are added to the list, rather than waiting for the user to press the Upload button.

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:

There are a number of event handlers specific to the <rich:fileUpload> component:

Basic usage requires the value attribute to point to the expression for the current value of the component. Validation and conversion rules for the JSF UIInput control apply as usual.

When in the initial view state, the starting label can be set using the defaultLabel attribute. Alternatively, if the initial value is already set through the value attribute, this is displayed instead.

By default, the event to switch the component to the edit state is a single mouse click. This can be changed using the editEvent attribute to specify a different event.

The user can confirm and save their input in multiple ways:

Pressing the Esc key cancels editing in all cases.

The <rich:inplaceInput> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

Basic usage requires the value 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 <f:selectItem/> and <f:selectItems/>.

When in the initial view state, the starting label can be set using the defaultLabel attribute, such as defaultLabel="click to edit". Alternatively, if the initial value is already set through the value attribute, this is displayed instead.

By default, the event to switch the component to the edit state is a single mouse click. This can be changed using the editEvent attribute to specify a different event. When switching to edit mode, the drop-down list of possible values will automatically be displayed; this can be deactivated by setting openOnEdit="false".

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:

Pressing the Esc key cancels editing in all cases.

The <rich:inplaceSelect> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

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 value attribute is used for storing the currently selected value of the slider. Standard conversion and validation for the JSF UIInput component is applied.

The text field can be removed by setting showInput="false".

The properties of the slider can be set with the attributes minValue, maxValue, and step.

The minimum and maximum labels on the slider can be hidden by setting showBoundaryValues="false". The tool-tip showing the current value can be hidden by setting showToolTip="false".

Arrow controls can be added to either side of the slider to adjust the value incrementally by setting showArrows="true". 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 delay attribute.

The <rich:inputNumberSlider> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

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.

These default properties can be re-defined with the attributes minValue, maxValue, and step respectively. The starting value of the spinner is the minimum value unless otherwise specified with the value attribute.

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 cycled="false", which will cause the buttons to stop responding when the reach the maximum or minimum value.

The ability to change the value by typing into the text field can be disabled by setting enableManualInput="false".

The <rich:inputNumberSpinner> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

Simple usage of the <rich:select> component requires the value 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 <f:selectItem> tags or a <f:selectItems> tag which points to a data model containing a list of selection items. The value attribute is used to store the current selection.

In auto-completing mode var attribute is required, <f:selectItems> tag is not used.

The arrow keys on a keyboard can be used to highlight different items in the list. If the control loses focus or the Enter key is pressed, the highlighted option is chosen as the value and the list is closed. Pressing the Esc key will close the list but not change the value.

The <rich:select> component allows the user to type into a text field to scroll through or filter the list. By default, the <rich:select> component functions as a drop-down list with no manual input. To add keyboard support for manual input, set enableManualInput="true".

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.

The standard JSF <h:selectOne> component does not offer this extended keyboard support. However, since the <rich:select> component is still based on the JSF UISelectOne 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.

Use the defaultLabel attribute to set a place-holder label, such as defaultLabel="select an option".

Server-side processing occurs in the same manner as for an <h:selectOneMenu> component. As such, custom objects used for selection items should use the same converters as for an <h:selectOneMenu> component.

The <rich:select> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

To use the <rich:orderingList> bind the value attribute to the list to be ordered. The var attribute specifies a variable to use when iterating through the list values. The var attribute is used within the itemLabel to assign the object value to be displayed. Similarly, the var attribute is used within the itemValue attribute to specify the object value mapped by the display value. If the itemValue is not of type String, a converter must be specified for this itemValue using either the converter attribute, or a nested <f:converter> tag.

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.

In addition to the above simple itemLabel display, the <rich:orderingList> supports a columnar layout of the itemValues to be sorted. This is achieved by nesting <rich:column> tags within the orderingList, and referencing the var attribute from within the <rich:column> EL.

When using <rich:column> tags to layout the <rich:orderingList> items, the itemLabel attribute is irrelevant, and may be left out.

The <rich:orderingList> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

To use the <rich:pickList> bind the value attribute to the target list, where the selected items will be stored. The list of source items is provided by nesting a SelectItem source, such as a <f:selectItems> tag, or a list of <f:selectItem> tags. If the itemValue of the SelectItem is not of type String, a converter must be specified for this itemValue using either the converter attribute, or a nested <f:converter> tag.

The items in the target list can be ordered client-side by setting the orderable attribute of the <rich:pickList> tag to true. 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.

In addition to the above simple SelectItem itemLabel display, the <rich:pickList> supports a columnar layout of the items to be selected. This is achieved by adding a var attribute used to represent the collection of nested SelectItems, and nesting <rich:column> tags within the pickList. The var attribute of the <f:selectItem> is then referenced from within the <rich:column> EL.