⁠19.2. <rich:focus>

The <rich:focus> component allows one to manipulate the focus of components on a page. It is intended to be used with any input field.

⁠19.2.1. Placement

The component will behave differently when placed:
  • in a form - defines behavior for components in the given form
  • in a view (outside of forms) - defines behavior for components in all forms in the view
There can be only one focus per form.
If both, form- and view-based focuses are defined, the form one takes a priority.

⁠19.2.2. Applying Focus

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.
You can turn focusing-after-AJAX-requests off by setting the ajaxRendered attribute to false.

⁠19.2.3. Validation-Aware

The <rich:focus> 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.
If all components are valid, then first component in the form is focused.
The order of input components is determined on the client-side and reflects the tabindex and position in the page. You can prioritize the focusing of a specific component by increasing its tabindex.
You can turn validation awareness off by setting the validationAware attribute to false.
⁠
Validation-aware <rich:focus>

Figure 19.1. Validation-aware <rich:focus>

⁠19.2.4. Preserving Focus

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).
⁠

Example 19.3. <rich:focus> preserving focus

​<h:form>
​    <rich:focus preserve="true" />
​
​    <h:inputText id="query" value="#{query}" />
​    <a4j:commandButton value="Search" render="output" />
​ 
​    <h:outputText value="Searched query:" />
​    <h:outputText id="output" value="#{query}" />
​</h:form>
In the example above, everytime the user hits Search (or hits enter), the focus is given back to the query input after the request.
This configuration will take priority over any other focus setup.

⁠19.2.5. Delaying Focus

In certain situations, focus needs to be applied with a delay - once suitable conditions are met.
By configuring a focus with the attribute delayed to true, the focus won't be applied on initial page request.
Then it is possible to call the applyFocus() JavaScript API method in order to let the focus be applied.

⁠19.2.6. Focus Manager

For a situation when none of the options above help one to achieve the desired focus behavior, one can use the server-side component FocusManager.
A component focus chosen by the FocusManager will take priority over any focus configuration.
⁠

Example 19.4. <rich:focus> preserving focus

​FocusManager focusManager = ServiceTracker.getService(FocusManager.class);
​focusManager.focus("input2");

⁠19.2.7. Reference data

  • component-type: org.richfaces.Focus
  • component-class: org.richfaces.component.UIFocus
  • component-family: org.richfaces.Focus
  • renderer-type: org.richfaces.FocusRenderer