JBoss.orgCommunity Documentation
This chapter details rich components for user input and interaction.
The <rich:autocomplete>
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.
The auto-complete box is a standard JSF UIInput
control with added validation.
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:
The autocompleteMethod
attribute points to a method which returns a list of suggestions according to a supplied prefix.
The prefix is normally ignored in client
and lazyClient
modes. In these modes, the component requests the suggestion list once only, and performs filtering on the client.
The autocompleteList
attribute points to a collection of suggestions.
Example 8.1. Defining suggestion values
autocompleteMethod
attribute<rich:autocomplete value="#{bean.state}" autocompleteMethod="#{bean.autocomplete}" />
The <rich:autocomplete>
component uses the bean.autocomplete
method to provide suggestions, based on the entered prefix.
autocompleteList
attribute<rich:autocomplete value="#{bean.state}" autocompleteList="#{bean.suggestions}" />
The <rich:autocomplete>
component retrieve the suggestion list from bean.suggestions
.
Use the mode
attribute to determine how the suggestion list is requested:
The client
setting pre-loads data to the client and uses the input to filter the possible suggestions.
The ajax
setting fetches suggestions with every input change using Ajax requests.
The lazyClient
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 minChars
attribute.
The cachedAjax
setting pre-loads data via Ajax requests when the input length matches a minimum value. Set the minimum value with the minChars
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.
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
causes the combo-box to fill the text field box with a matching suggestion as the user types.
autoFill
="true"
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.
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.
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.
Example 8.2. Customizing the filter
This example demonstrates how to use a custom filter with the clientFilterFunction
attribute. The custom filter determines if the sub-string is contained anywhere in the suggestion item, instead of just at the start.
<script>
function customFilter(subString, value){
if(subString.length>=1) {
if(value.indexOf(subString)!=-1)
return true;
}else return false;
};
</script>
<h:form>
<rich:autocomplete mode="client" minChars="0" autofill="false"
clientFilterFunction="customFilter"
autocompleteMethod="#{autocompleteBean.autocomplete}" />
</h:form>
The <rich:autocomplete>
component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()
Get the current value of the text field.
setValue(newValue)
Set the value of the text field to the newValue
string passed as a parameter.
showPopup()
Show the pop-up list of completion values.
hidePopup()
Hide the pop-up list.
component-type
: org.richfaces.Autocomplete
component-class
: org.richfaces.component.UIAutocomplete
component-family
: javax.faces.Input
renderer-type
: org.richfaces.AutocompleteRenderer
handler-class
: org.richfaces.view.facelets.AutocompleteHandler
Table 8.1. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
|
| color |
| font-family | |
| font-size | |
|
| background-color |
|
| border-color |
| background-color | |
| No skin parameters. | |
|
| background-color |
| border-left-color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
|
| background-color |
| border-color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. |
The <rich:calendar>
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.
Basic usage of the <rich:calendar>
component requires only the value
attribute, which holds the currently selected date. Example 8.3, “Basic usage” shows a basic declaration, with the value pointing to a bean property. The bean property holds the selected date.
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 todayControlMode
attribute:
hidden
, which does not display the button;
select
, the default setting, which scrolls the calendar to the current month and selects the date; and
scroll
, which scrolls the calendar to the month but does not select the date.
inactive
, which displays the date but performs no action when clicked.
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.
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.
In RichFaces 4, the <rich:calendar>
component supports times that include seconds. Previous versions of RichFaces only supported hours and minutes.
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:
The RICH_CALENDAR_APPLY_LABEL string is the label for the button.
The RICH_CALENDAR_TODAY_LABEL string is the label for the button.
The RICH_CALENDAR_CLOSE_LABEL string is the label for the button.
The RICH_CALENDAR_OK_LABEL string is the label for the button.
The RICH_CALENDAR_CLEAN_LABEL string is the label for the button.
The RICH_CALENDAR_CANCEL_LABEL string is the label for the button.
Alternatively, use the org.richfaces.calendar
resource bundle with Java Archive files (JARs) 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.
Instead of using a data model, the <rich:calendar>
component can be customized on the client-side using JavaScript. Use the dayClassFunction
attribute to reference the function that determines the CSS style class for each day cell. Use the dayDisableFunction
to reference the function that enables or disables a day cell. Example 8.4, “Client-side customization” demonstrates how client-side customization can be used to style different days in a calendar.
Example 8.4. Client-side customization
<style>
.everyThirdDay {
background-color: gray;
}
.weekendBold {
font-weight: bold;
font-style: italic;
}
</style>
<script type="text/javascript">
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() < 0) return true;
else return false;
}
function disabledClassesProv(day){
if (curDt.getTime() - day.date.getTime() >= 0) return 'rf-ca-boundary-dates';
var res = '';
if (day.isWeekend) res+='weekendBold ';
if (day.day%3==0) res+='everyThirdDay';
return res;
}
</script>
<rich:calendar dayDisableFunction="disablementFunction"
dayClassFunction="disabledClassesProv"
boundaryDatesMode="scroll" />
The <rich:calendar>
component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
showPopup()
Expand the pop-up calendar element.
hidePopup()
Collapse the pop-up calendar element.
switchPopup()
Invert the state of the pop-up calendar element.
getValue()
Return the selected date value of the calendar.
getValueAsString()
Return the selected date value of the calendar as a formatted string.
setValue(newValue)
Set the selected date value to the newValue
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.
resetValue()
Clear the selected date value.
today()
Select today's date.
getCurrentMonth()
Return the number of the month currently being displayed.
getCurrentYear()
Return the number of the year currently being displayed.
showSelectedDate()
Show the calendar month that contains the currently selected date.
showDateEditor()
Show the date editor pop-up.
hideDateEditor()
Hide the date editor pop-up.
showTimeEditor()
Show the time editor pop-up.
hideTimeEditor()
Hide the time editor pop-up.
component-type
: org.richfaces.Calendar
component-class
: org.richfaces.component.UICalendar
component-family
: org.richfaces.Calendar
renderer-type
: org.richfaces.CalendarRenderer
handler-class
: org.richfaces.view.facelets.CalendarHandler
Table 8.2. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
|
| border-color |
| No skin parameters. | |
|
| border-bottom-color |
| background-color | |
| font-size | |
| font-family | |
|
| border-bottom-color |
| background-color | |
| font-size | |
| font-family | |
|
| background-color |
| font-size | |
| font-family | |
| font-weight | |
| color | |
|
| border-right-color, border-bottom-color |
| background | |
| font-size | |
| font-family | |
|
| border-right-color, border-bottom-color |
| background | |
| font-size | |
| font-family | |
|
| background-color |
| font-size | |
| font-family | |
| font-weight | |
| color | |
|
| background |
| font-size | |
| font-family | |
| No skin parameters. | |
| No skin parameters. | |
|
| background-color |
| color | |
| border-color | |
| border-right-color, border-bottom-color | |
|
| border-color |
| border-right-color, border-bottom-color | |
| No skin parameters. | |
|
| border-bottom-color, border-right-color |
| background-color | |
| font-size | |
| font-family | |
| No skin parameters. | |
|
| background-color |
| color | |
|
| background-color |
| color | |
|
| background-color |
| color | |
|
| border-bottom-color, border-right-color |
| background-color | |
| font-size | |
| font-family | |
|
| background-color |
| color | |
| No skin parameters. | |
|
| font-size |
| font-family | |
|
| background-color |
| border-color | |
| border-right-color, border-bottom-color | |
|
| background-color, border-color |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
|
| background |
|
| background-color |
| No skin parameters. | |
|
| border-color |
| background | |
|
| background-color |
| color | |
|
| background |
| border-color | |
| border-right-color, border-bottom-color | |
|
| background |
| border-color | |
| border-right-color, border-bottom-color | |
| No skin parameters. | |
|
| border-color |
| border-right-color, border-bottom-color | |
|
| border-right-color, border-bottom-color |
| border-color | |
| background-color | |
|
| border-color |
| background | |
| font-size | |
| font-family | |
|
| font-size |
| font-family | |
| No skin parameters. | |
| No skin parameters. | |
|
| border-color |
| background | |
| font-size | |
| font-family | |
|
| background |
| border-top-color | |
|
| background |
| border-top-color | |
|
| border-right-color |
The <rich:editor>
component is used for creating a WYSIWYG editor on a page.
<rich:editor>
component is based on the CKEditor implementation.
When rendering a <rich:editor>
, 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.
Basic usage requires the value
attribute to point to the expression for the current value of the component.
Example 8.5. Basic usage of <rich:editor>
<rich:editor value="#{backingBean.editedValue}" />
<h:outputText escape="false" value="#{backingBean.editedValue}" />
Note that the editor produces HTML markup and to be able to render it's output, the markup needs to be unescaped (as with <h:outputText>
component in example above).
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.
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.
<rich:editor>
requires the <h:body>
component to be present in the view and must be an ancestor of the editor in order for the resource dependencies to render correctly.
There are several options to customize the style of the editor:
style, styleClass
: customizes the style of the editor and underlying textarea
editorStyle, editorClass
: customizes the style of the CKEditor instance
textareaStyle, textareaClass
: customizes the style of the underlying textarea
The <rich:editor>
is skinnable using the skin
attribute and either of the two approaches:
By default, <rich:editor>
has a skin called richfaces
that is optimized to match rest of the component suite look & feel and changes to match the active RichFaces skin (refer to RichFaces Developer's Guide for details about Skinning and theming).
Example 8.6. The skin richfaces
of <rich:editor>
A <rich:editor>
with the default richfaces
editor skin rendered against several RichFaces Skin options.
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: kama, v2, office2003
.
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>
comes with a lang
attribute which allows you to change the localization of the editor.
For language configuration options, refer to http://www.w3.org/TR/html4/struct/dirlang.html.
The lang
attribute influences following settings:
underlying textarea - specifies the i18n settings for received and submitted content
editor value - specifies the i18n settings for value edited in WYSIWYG mode
default settings of localization of editor controls and interface
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 language
, as in following sample:
<rich:editor lang="fr" config="language: 'fr'" />
The above sample forces the editor to use a french interface, suppressing the browser preferred settings.
The <rich:editor>
component produces set of events for handling component specific interaction.
init
- once the editor is initialized and ready to be handle user interaction
focus
- once the editor is focused
blur
- once the editor is blurred
change
- fired on blur event when editor content has been changed after previous focus
dirty
- fired immediately after editor content has been changed
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:
getValue()
Get the current value of the input control.
setValue(newValue)
Set the value of the input control to the newValue
string passed as a parameter.
getEditor()
Returns the CKEditor object instance associated to given <rich:editor>
component.
getInput()
Returns the associated textarea.
focus()
Gives focus to this component
blur()
Removes focus from this component
isFocused()
Returns true
if this component is focused
isDirty()
Returns true
if editor is focused and it was edited from last focus event (reset by blur event, by using setValue(newValue)
call and when component is re-rendered)
isValueChanged()
Returns true
if the control's value has been changed from the default (reset by setValue(newValue)
call and when component is re-rendered)
isReadonly()
Returns true
if editor content is editable.
setReadonly(readonly)
When readonly
is true
, editor will be switched to editable state. Otherwise, it will be switched to readonly state.
component-type
: org.richfaces.Editor
component-class
: org.richfaces.component.UIEditor
component-family
: org.richfaces.Editor
renderer-type
: org.richfaces.EditorRenderer
Table 8.3. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
|
| border-color |
|
| background-color |
|
| border-color |
| background | |
|
| repeat-x |
| font-weight | |
| color | |
| font-family | |
| font-size | |
|
| color |
|
| background-color |
| border-color | |
|
| border-color |
| background-color | |
|
| border-color |
| font-size | |
| font-family | |
| color | |
| background-color | |
|
| background-color |
| border-left-color |
The <rich:fileUpload>
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.
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 org.richfaces.fileUpload.maxRequestSize
context parameter of the web.xml
settings file for the project.
Any file is accepted by rich:fileUpload component by default. There are three parameters available for limiting what can user upload to the server:
maxFilesQuantity
The maxFilesQuantity
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.
acceptedTypes
The acceptedTypes
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 ontyperejected
parameter.
ontyperejected
The ontyperejected
parameter defines event handler when file does not meet conditions stated by acceptedTypes
parameter.
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 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:
addLabel
The addLabel
parameter sets the label for the button.
clearAllLabel
The clearAllLabel
parameter sets the label for the button.
clearLabel
The clearLabel
parameter sets the label for the button.
uploadLabel
The uploadLabel
parameter sets the label for the button.
The <rich:fileUpload>
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 <rich:progressBar>
component added to the progress
facet. Refer to Section 13.7, “<rich:progressBar>” for details on the <rich:progressBar>
component.
To disable the <rich:fileUpload>
component, use the disabled
attribute.
There are a number of event handlers specific to the <rich:fileUpload>
component:
filesubmit
is triggered before a file is uploaded.
uploadcomplete
is triggered after all files in the list have finished uploading.
component-type
: org.richfaces.FileUpload
component-class
: org.richfaces.component.UIFileUpload
component-family
: org.richfaces.FileUpload
renderer-type
: org.richfaces.FileUploadRenderer
handler-class
: org.richfaces.view.facelets.FileUploadHandler
Table 8.4. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
|
| background-color |
| border-color | |
|
| background-color, border-color |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
|
| background-color |
| border-color | |
|
| color |
| font-family | |
| font-size | |
|
| background-color |
| border-color | |
|
| color |
| font-family | |
| font-size | |
|
| background-color |
| border-color | |
|
| color |
| font-family | |
| font-size | |
|
| background-color |
| border-color | |
|
| color |
| font-family | |
| font-size | |
|
| border-bottom-color |
| No skin parameters. | |
|
| color |
| font-family | |
| font-size | |
|
| color |
| font-family | |
| font-size | |
|
| color |
| font-family | |
| font-size | |
| No skin parameters. | |
| No skin parameters. |
The <rich:inplaceInput>
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 view state, where the component displays its initial setting, such as "click to edit"; the edit 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.
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.
Once the user has entered text, the label is stored in the model specified by the value
attribute. The use of the default label and value is shown in Example 8.9, “Default label and value”.
Example 8.9. Default label and value
<rich:inplaceInput value="#{bean.value}" defaultLabel="click to edit"/>
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:
By default, pressing the Enter key will confirm and save the input.
If showControls="true"
is set, buttons for confirming or canceling are added to the component.
If saveOnBlur="true"
is set, the input is saved on the component's blur event.
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:
getValue()
Get the current value of the input control.
setValue(newValue)
Set the value of the input control to the newValue
string passed as a parameter.
isEditState()
Returns true
if the control is currently in the edit state, or false
if the control is currently in the view state.
isValueChanged()
Returns true
if the control's value has been changed from the default.
save()
Saves the current item as the control's value.
cancel()
Cancel editing the value.
getInput()
Return the DOM element for the input.
component-type
: org.richfaces.InplaceInput
component-class
: org.richfaces.component.UIInplaceInput
component-family
: org.richfaces.InplaceInput
renderer-type
: org.richfaces.InplaceInputRenderer
Table 8.5. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
|
| background-color |
| border-bottom-color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
|
| background-color, border-bottom-color |
| color | |
| font-family | |
| font-size | |
| No skin parameters. | |
| No skin parameters. | |
|
| background-color |
| border-color | |
|
| background-color |
| border-color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. |
The <rich:inplaceSelect>
component is similar to the <rich:inplaceInput>
component, except that the <rich:inplaceSelect>
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 UISelectOne
component, so all the standard rules for value definition, processing, conversion, and validation apply.
The component has three functional states:
When in the view state, the component displays its initial setting, such as "click to edit".
When in the edit state, the user can select a value from a drop-down list.
When in the changed state, the new value for the component has been confirmed, but it can be edited again if required.
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/>
.
Example 8.10. Defining list items for <rich:inplaceSelect>
<rich:inplaceSelect value="#{bean.inputValue}" defaultLabel="click to edit" >
<f:selectItems value="#{bean.selectItems}" />
<f.selectItem itemValue="1" itemLabel="Item 1" />
<f.selectItem itemValue="2" itemLabel="Item 2" />
<f.selectItem itemValue="3" itemLabel="Item 3" />
<f.selectItem itemValue="4" itemLabel="Item 4" />
</rich:comboBox>
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:
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 saveOnSelect="false"
is set, the component applies the selected item but remains in the edit state so a different selection could be chosen. The value is then applied when the Enter key is pressed.
If saveOnBlur="true"
is set, the selected item is saved as the new control value when the control loses focus.
If showControls="true"
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.
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:
getValue()
Get the current value of the select control.
setValue(newValue)
Set the value of the select control to the newValue
string passed as a parameter.
isEditState()
Returns true
if the control is currently in the edit state, or false
if the control is currently in the view state.
isValueChanged()
Returns true
if the control's value has been changed from the default.
save()
Saves the current item as the control's value.
cancel()
Cancel editing the value.
getInput()
Return the input entered into the control by the user.
getLabel()
Return the default label of the control.
setLabel(newLabel)
Set the default label of the control to the newLabel
string passed as a parameter.
showPopup()
Show the pop-up list of possible values.
hidePopup()
Hide the pop-up list.
component-type
: org.richfaces.InplaceSelect
component-class
: org.richfaces.component.UIInplaceSelect
component-family
: org.richfaces.Select
renderer-type
: org.richfaces.InplaceSelectRenderer
Table 8.6. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
|
| background-color |
| border-bottom-color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
|
| background |
| color | |
| font-family | |
| font-size | |
|
| border-color |
|
| border-color |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
|
| background-color |
| border-color | |
|
| background-color |
| border-color | |
| No skin parameters. | |
| No skin parameters. | |
|
| background-color |
| border-color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. |
The <rich:inputNumberSlider>
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's range.
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
. The tool-tip showing the current value can be hidden by setting showBoundaryValues
="false"
.
showToolTip
="false"
Arrow controls can be added to either side of the slider to adjust the value incrementally by setting
. 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 showArrows
="true"delay
attribute.
The <rich:inputNumberSlider>
component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()
Get the current value of the slider control.
setValue(newValue)
Set the value of the slider control to the newValue
integer passed as a parameter.
increase()
Increase the value of the slider control by the gradient step amount.
decrease()
Decrease the value of the slider control by the gradient step amount.
component-type
: org.richfaces.InputNumberSlider
component-class
: org.richfaces.component.UIInputNumberSlider
component-family
: org.richfaces.Input
renderer-type
: org.richfaces.inputNumberSliderRenderer
Table 8.7. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
| No skin parameters. | |
|
| background-color |
| border-bottom-color | |
| No skin parameters. | |
|
| font-size |
| font-family | |
| color | |
| border-left-color | |
|
| font-size |
| font-family | |
| color | |
| border-right-color | |
|
| font-size |
| font-family | |
| color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
|
| font-size |
| font-family | |
| color | |
| border | |
| background-color |
The <rich:inputNumberSpinner>
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.
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:
getValue()
Get the current value of the spinner control.
setValue(newValue)
Set the value of the spinner control to the newValue
integer passed as a parameter.
increase()
Increase the value of the spinner control by the gradient step amount.
decrease()
Decrease the value of the spinner control by the gradient step amount.
component-type
: org.richfaces.InputNumberSpinner
component-class
: org.richfaces.component.UIInputNumber
component-family
: org.richfaces.Input
renderer-type
: org.richfaces.InputNumberSpinnerRenderer
Table 8.8. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
|
| border-color |
|
| font-size |
| font-family | |
| color | |
| background-color | |
|
| background-color |
| border-left-color | |
| No skin parameters. | |
| No skin parameters. |
The <rich:select>
component provides a drop-down list box for selecting a single value from multiple options. The <rich:select>
component can be configured as a combo-box, where it will accept typed input. The component also supports keyboard navigation. The <rich:select>
component functions similarly to the JSF UISelectOne
component.
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.
Example 8.11. Selection items
<f:selectItem>
tags<rich:select>
<f:selectItem itemValue="0" itemLabel="Option 1" />
<f:selectItem itemValue="1" itemLabel="Option 2" />
<f:selectItem itemValue="2" itemLabel="Option 3" />
<f:selectItem itemValue="3" itemLabel="Option 4" />
<f:selectItem itemValue="4" itemLabel="Option 5" />
</rich:select>
<f:selectItems>
tag<rich:select>
<f:selectItems value="#{bean.options}" />
</rich:select>
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:
getValue()
Get the current value of the text field.
setValue(newValue)
Set the value of the text field to the newValue
string passed as a parameter.
getLabel()
Return the default label of the control.
showPopup()
Show the pop-up list of completion values.
hidePopup()
Hide the pop-up list.
component-type
: org.richfaces.Select
component-class
: org.richfaces.component.UISelect
component-family
: org.richfaces.Select
renderer-type
: org.richfaces.SelectRenderer
Table 8.9. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
| No skin parameters. | |
|
| border-color |
|
| background-color |
| No skin parameters. | |
|
| color |
| font-size | |
| font-family | |
|
| border-color |
| No skin parameters. | |
|
| background-color |
| border-left-color | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. | |
| No skin parameters. |
The <rich:orderingList>
is a component for ordering items in a list (client-side).
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.
Example 8.12. ItemLabel/ItemValue use
itemLabel
and itemValue
attributes<rich:orderingList value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}">
<f:converter converterId="CapitalsConverter" />
</rich:orderingList>
The arrow keys on a keyboard can be used to highlight different items in the list. Pressing the ctrl modifier 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.
Example 8.13. Nested <rich:column>
tags
<rich:column>
tags nested within the <rich:orderingList>
<rich:orderingList value="#{listSelectBean.capitals}" var="capital" listWidth="300px">
<f:converter converterId="CapitalsConverter" />
<rich:column>
<f:facet name="header">Flag</f:facet>
<h:graphicImage value="#{capital.stateFlag}" alt="flag" width="33"/>
</rich:column>
<rich:column>
<f:facet name="header">Name</f:facet>
#{capital.name}
</rich:column>
<rich:column>
<f:facet name="header">State</f:facet>
#{capital.state}
</rich:column>
</rich:orderingList>
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:
getList()
Returns the javascript list object backing the <rich:orderingList>
. This list can be used to select/unselect item(s).
up()
Move the currently selected item(s) up one step.
down()
Move the currently selected item(s) down one step.
upTop()
Move the currently selected item(s) to the top of the list.
downBottom()
Move the currently selected item(s) to the bottom of the list.
toggleButtons()
Activate/de-activate the orderingList buttons based on the current component item state.
component-type
: org.richfaces.OrderingList
component-class
: org.richfaces.component.UIOrderingList
component-family
: org.richfaces.SelectMany
renderer-type
: org.richfaces.OrderingListRenderer
Table 8.10. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
| No skin parameters. | |
| No skin parameters. | |
|
| color |
| font-size | |
| font-family | |
| font-weight | |
| No skin parameters. | |
|
| background-color |
| color | |
| font-size | |
| font-family | |
| font-weight | |
|
| color |
| font-size | |
| font-family | |
|
| border-color |
| No skin parameters. | |
|
| background-color |
| border-left-color | |
| No skin parameters. | |
| No skin parameters. |
The <rich:pickList>
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.
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.
Example 8.14. Simple pickList use
SelectItem
itemLabel to generate the pickList source and target items.<rich:pickList value="#{listSelectBean.selectedCapitals}"
sourceCaption="Available cities" targetCaption="Selected cities"
listWidth="170px" listHeight="100px"
orderable="true">
<f:selectItems value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}" />
<f:converter converterId="CapitalsConverter" />
</rich:pickList>
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 ctrl modifier 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.
Example 8.15. Nested <rich:column>
tags
<rich:column>
tags nested within the <rich:pickList>
<rich:pickList value="#{listSelectBean.selectedCapitals}" var="capital" listHeight="200px">
<f:selectItems value="#{listSelectBean.capitals}" />
<f:converter converterId="CapitalsConverter" />
<rich:column>
<f:facet name="header">Flag</f:facet>
<h:graphicImage value="#{capital.stateFlag}" alt="flag" width="33"/>
</rich:column>
<rich:column>
<f:facet name="header">Name</f:facet>
#{capital.name}
</rich:column>
<rich:column>
<f:facet name="header">State</f:facet>
#{capital.state}
</rich:column>
</rich:pickList>
The <rich:pickList>
component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getSourceList()
Returns the javascript list object backing the <rich:pickList>
source list. This list can be used to select/unselect item(s).
getTargetList()
Returns the javascript list object backing the <rich:pickList>
target list. This list can be used to select/unselect item(s).
add()
Add the currently selected items to the target list, removing them from the source list.
addAll()
Add all the source items to the target list, removing them from the source list.
remove()
Remove the currently selected items from the target list, adding them to the source list.
removeAll()
Remove all the source items from the target list, adding them to the source list.
toggleButtons()
Activate/de-activate the pickList buttons based on the current component item state.
component-type
: org.richfaces.PickList
component-class
: org.richfaces.component.UIPickList
component-family
: org.richfaces.SelectMany
renderer-type
: org.richfaces.PickListRenderer
Table 8.11. Style classes (selectors) and corresponding skin parameters
Class (selector) | Skin Parameters | Mapped CSS properties |
---|---|---|
| No skin parameters. | |
|
| color |
| font-size | |
| font-family | |
| font-weight | |
| No skin parameters. | |
|
| background-color |
| color | |
| font-size | |
| font-family | |
| font-weight | |
|
| color |
| font-size | |
| font-family | |
|
| border-color |
| No skin parameters. | |
|
| background-color |
| border-left-color | |
| No skin parameters. | |
| No skin parameters. |