10.6. <rich:inplaceSelect>

⁠10.6. `<rich:inplaceSelect>`

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.

⁠

Figure 10.4. <rich:inplaceSelect>

⁠10.6.1. Basic usage

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 10.8. 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:inplaceSelect>

⁠10.6.2. Interactivity options

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.

⁠10.6.3. JavaScript API

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.

⁠10.6.4. Reference data

component-type: org.richfaces.InplaceSelect
component-class: org.richfaces.component.UIInplaceSelect
component-family: org.richfaces.Select
renderer-type: org.richfaces.InplaceSelectRenderer

⁠10.6.5. Style classes and skin parameters

⁠

Table 10.6. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-is` This class defines styles for the in-place select when it is in the default state.	`editorBackgroundColor`	background-color
	`generalTextColor`	border-bottom-color
`.rf-is-act` This class defines styles for the in-place select when it is in the editing state.	No skin parameters.
`.rf-is-chng` This class defines styles for the in-place select when it is in the changed state.	No skin parameters.
`.rf-is-dis` This class defines styles for the in-place select when it is in the disabled state.	No skin parameters.
`.rf-is-fld` This class defines styles for the in-place select field.	`editBackgroundColor`	background
	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-is-opt` This class defines styles for an option for the in-place select.	`generalTextColor`	border-color
`.rf-is-sel` This class defines styles for the selected option of the in-place select.	`generalTextColor`	border-color
`.rf-is-lbl` This class defines styles for the label of the in-place select.	No skin parameters.
`.rf-is-dflt-lbl` This class defines styles for the default label of the in-place select.	No skin parameters.
`.rf-is-edit` This class defines styles for the in-place select when it is being edited.	No skin parameters.
`.rf-is-btn` This class defines styles for the buttons for the in-place select.	`tabBackgroundColor`	background-color
	`panelBorderColor`	border-color
`.rf-is-btn-p` This class defines styles for the buttons for the in-place select when they are pressed.	`tabBackgroundColor`	background-color
	`panelBorderColor`	border-color
`.rf-is-btn-set`, `.rf-is-btn-prepos`, `.rf-is-btn-pos` These classes define the positioning of the buttons.	No skin parameters.
`.rf-is-lst-pos` This class defines the positioning of the list.	No skin parameters.
`.rf-is-lst-dec` This class defines styles for a decreasing list for the in-place select.	`editBackgroundColor`	background-color
	`panelBorderColor`	border-color
`.rf-is-lst-scrl` This class defines styles for the list scrollbar.	No skin parameters.
`.rf-is-shdw` This class defines styles for the in-place select shadow.	No skin parameters.
`.rf-is-shdw-t`, `.rf-is-shdw-b`, `.rf-is-shdw-l`, `.rf-is-shdw-r` These classes define the top, bottom, left, and right edge of the in-place select shadows.	No skin parameters.
`.rf-is-btn-shdw` This class defines styles for the button shadows for the in-place select.	No skin parameters.
`.rf-is-none` This class defines styles for the in-place select when it cannot be edited.	No skin parameters.