Create new RichFaces Documentation Jira issue
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.
JBoss.orgCommunity Documentation
The <rich:inplaceSelect> is used for the creation of select based inputs: it shows the value as a text in one state and enables editing the value, providing a list of options in another state
View/changed/edit states in highly customizable representations
Optional "inline" or "block" element rendering on a page
Changing state event customization
Possibility to call custom JavaScript function on state changes
Edit mode activation when the component got focus with the "Tab"
Sizes synchronizations between modes
Highly customizable look and feel
The "value" attribute is a value-binding expression for the current value of the component.
The <rich:inplaceSelect> component has three functional states:
View state displays default label with the value taken from "value" or "defaultLabel" attributes.
If the initial value of the "value" attribute is "null" or empty string, the "defaultLabel" attribute is used to define a default label.
Example:
...
<rich:inplaceSelect value="#{bean.value}" defaultLabel="click to edit">
<f:selectItems value="#{bean.selectItems}" />
</rich:inplaceSelect>
...
In the example above the
"value"
attribute is not initialized,
therefore the "click to edit" text, that
"defaultLabel"
contains, is displayed.
This is the result:
Edit state - select representation to allow value edit
Changed state - value representation after it was changed
You can form the list of the options using <f:selectItem/> and <f:selectItems/> JSF components.
Please, see the example below.
Example:
...
<rich:inplaceSelect value="#{bean.inputValue}" defaultLabel="click to edit">
<f:selectItems value="#{bean.selectItems}"/>
<f:selectItem itemValue="1" itemLabel="factory"/>
<f:selectItem itemValue="2" itemLabel="newspaper"/>
</rich:inplaceSelect>
...
In the example above the value of the selected item is available via "value" attribute.
The "editEvent" attribute provides an option to assign a JavaScript action that initiates the change of the state from view to edit. The default value is "onclick".
Example:
...
<rich:inplaceSelect value="#{bean.inputValue}" defaultLabel="Double Click to edit" editEvent="ondblclick">
<f:selectItems value="#{demo.selectItems}" />
</rich:inplaceSelect>
...
The <rich:inplaceSelect> component provides specific event attributes:
"oneditactivation" fired on edit state activation
"oneditactivated" fired when edit state is activated
"onviewactivation" fired on view state activation
"onviewactivated" fired after the component is changed to representation state
Example:
...
<rich:inplaceSelect value="#{bean.inputValue}" oneditactivation="if (!confirm('Are you sure you want to change the value?')){return false;}">
<f:selectItems value="#{demo.selectItems}" />
</rich:inplaceSelect>
...
The given code illustrates how
"oneditactivation"
attribute works,
namely when the state is being changed from view to edit,
a confirmation window with a message "Are you sure you want to change value?" comes up.
To prevent opening the drop-down list by default, once edit state is activated, set the "openOnEdit" attribute to "false". The default value is "true".
Example:
...
<rich:inplaceSelect value="#{bean.inputValue}" showControls="true" openOnEdit="false">
<f:selectItems value="#{bean.selectItems}"/>
</rich:inplaceSelect>
...
This is the result:
Nowever, if you want to confirm the data saving explicitly you can use the "showControls" attribute, which makes "Save" and "Cancel" buttons (displayed as icons) appear next to the input field. Edit state can be deactivated by pressing "Esc" key. An option in the drop-drown list can be also selected by pressing "Enter".
Example:
...
<rich:inplaceSelect value="#{bean.inputValue}" showControls="true">
<f:selectItems value="#{bean.selectItems}"/>
</rich:inplaceSelect>
...
This is the result:
You can also position the controls relatively to the input field, by means of
the "controlsHorizontalPosition" attribute with "left", "right" and "center" definitions
the "controlsVerticalPosition " attribute with "bottom" and "top" definitions
Example:
...
<rich:inplaceSelect value="#{bean.inputValue}" controlsHorizontalPosition="left" controlsVerticalPosition="center" showControls="true">
<f:selectItems value="#{bean.selectItems}"/>
</rich:inplaceSelect>
...
This is the result:
It is also possible to use "controls" facet in order to replace the default controls with facets content. See the example below.
Example:
...
<rich:inplaceSelect value="#{bean.inputValue}" showControls="true">
<f:facet name="controls">
<button onclick="#{rich:component('inplaceSelect')}.save();" type="button">Save</button>
<button onclick="#{rich:component('inplaceSelect')}.cancel();" type="button">Cancel</button>
</f:facet>
<f:selectItems value="#{bean.selectItems}"/>
</rich:inplaceSelect>
...
This is the result:
The "controls" facet also implies using "showControls" attribute and it has to be defined as "true".
The <rich:inplaceSelect> component could be rendered with <span> or <div> elements to display its value. In order to change default <span> output, use the "layout" attribute with "block" value.
The <rich:inplaceSelect> component supports the standard "tabindex" attribute. When the component gets focus the edit mode is activated and drop-down list is opened.
The "selectWidth" , "minSelectWidth" and "maxSelectWidth" attributes are provided to specify the width, minimal width and maximal width for the input element respectively.
In order to specify the height and width parameters for the list items of the component, you can use "listHeight" and " listWidth" attributes.
Table of <rich:inplaceSelect> attributes.
Table 6.191. Component Identification Parameters
| Name | Value |
|---|---|
| component-type | org.richfaces.InplaceSelect |
| component-class | org.richfaces.component.html.HtmlInplaceSelect |
| component-family | org.richfaces.InplaceSelect |
| renderer-type | org.richfaces.renderkit.InplaceSelectRenderer |
| tag-class | org.richfaces.taglib.InplaceSelectTag |
Table 6.192. JavaScript API
| Function | Description |
|---|---|
| edit() | Changes the state to edit |
| cancel() | Changes its state to the previous one before editing (changed or view) |
| save() | Changes its state to changed with a new value |
| getValue() | Gets the current value |
| setValue(newValue) | Sets the current value and name |
Table 6.193. Facets
| Facet name | Description |
|---|---|
| controls | Defines the contols contents. Related attributes are "saveControlIcon" and "cancelControlIcon" |
Table 6.194. Style classes (selectors) with the corresponding skin parameters
| Class (selector) name | Description | Skin Parameters | CSS properties mapped |
|---|---|---|---|
| .rich-inplace-select-view | Defines styles for the component in the view state | editorBackgroundColor | background-color |
| generaTextColor | border-bottom-color | ||
| input.rich-inplace-select-field, .rich-inplace-select-field | Define styles for the component input field | editorBackgroundColor | background-color |
| panelBorderColor | border-color | ||
| .rich-inplace-select-control | Defines styles for the component control | tabBackgroundColor | background-color |
| panelBorderColor | border-color | ||
| .rich-inplace-select-control-press | Defines styles for the pressed control | tabBackgroundColor | background-color |
| panelBorderColor | border-color | ||
| .rich-inplace-select-list-decoration | Defines styles for a wrapper <table> element of the component | editBackgroundColor | background-color |
| panelBorderColor | border-color | ||
| .rich-inplace-select-selected-item | Defines styles for the selected item | headerBackgroundColor | background-color, border-color |
| headerTextColor | color | ||
| input.rich-inplace-select-arrow | Defines styles for the drop-down arrow | editBackgroundColor | background-color |
Table 6.195. Style classes (selectors) without skin parameters
| Class name | Description |
|---|---|
| .rich-inplace-select-changed | Defines styles for the component in the changed state |
| .rich-inplace-select-shadow-tl | Defines styles for the top-left shadow |
| .rich-inplace-select-shadow-tr | Defines styles for the top-right shadow |
| .rich-inplace-select-shadow-bl | Defines styles for the bottom-left shadow |
| .rich-inplace-select-shadow-br | Defines styles for the bottom-right shadow |
You can find all necessary information about style classes redefinition in Definition of Custom Style Classes section.
On the component Live Demo page you can see the example of <rich:inplaceSelect> usage and sources for the given example.
