Action Handlers and Event Listeners
Clicking a button, a hyperlink or changing a value in a form element normally requires an action of some type. Desktop GUI applications have for years provided a well defined model for event handling, JSF provides a similar mechanism. The primary distinction with JSF event handling is that the event is triggered on the client but handled on the server.
JSF provides two types of methods for handling events; listeners and action handlers, both of these may be defined within a managed bean. A listener takes an FacesEvent as a parameter and a void return type, while an action handler takes no parameters and returns a String. An advantage of using a listener is that the FacesEvent object provides additional information, such as the form element that initiated the event. An action handler in contrast has no knowledge of the source of the event but can, based upon its return value,initiate page navigation.
Action handlers are generally used for page navigation. A common use is processing form post and navigating to a new page based upon some business logic. Page navigation is determined by the return value of the action handler and the navigation-rule
specified in faces-config.xml.
Let’s look at an example…
In the above example a user populates the username and password form elements and presses the submit button (<h:commandButton>). The action attribute within <h:commandButton> identifies an actionHandler in the managedBean (submitButtonAction()) which, in this example, returns success. The navigation rule within faces-config.xml specifies that the user will now be directed to “home.jsf”; this assumes that FacesServlet is mapped to *.jsf in web.xml.
When the user clicks a button or link, changes a value in a field, or makes a selection in a list, the application may need to react. JSF user interface components signal user actions by firing an event handled by application code that has registered itself to be notified of the event.
The two most commonly used event listeners are action and value-change, the others, data-model and phase will not be covered here. Listeners can be declared in a managed bean or in a separate listener class. Placing listeners in a separate class allows reuse across multiple page views. If creating a listener class the class must implement ActionListener or ValueChangeListener interfaces. As stated previously a listener takes a FacesEvent object its only parameter. The FacesEvent provides information about the event such as the form element that initiated the event and the phaseId related to the JSF life cycle phase. A FacesEvent has two sub interfaces, ActionEvent and ValueChangeEvent.
The actionListener attribute is supported by the <h:commandButton> and <h:commandLink> components. Lets look at an example…
When the user presses the “Create User” button (<h:commandButton>) the JSF implementation will broadcast the event to any registered listeners; In this example the listener(submit_listener) in the createUser managed bean is executed. As an alternative to the actionListener attribute you may use an actionListener tag.
This code will invoke the method processAction on the action listener class ActionListenerImpl. ActionListenerImpl must implement the ActionListener interface, which defines the method processAction.
A ValueChangeEvent is useful whenever you want to be notified when there is a change in the value of a component, such as text modification in a text field or a check box selection. Most JSF components support the valueChangeListener attribute. Lets see an example…
When the user modifies text in the name form element (<h:inputText>) the JSF implementation will broadcast the event to any registered listeners; In this example the listener(nameChange_listener) in the createUser managed bean is executed. Notice that the ValueChangeEvent provides the original value of the component and its new (changed) value.
As an alternative to the valueChangeListener attribute the valueChangeListener tag may be used.
This code will invoke the method processValueChange on the action listener class ValueChangeListenerImpl. ValueChangeListenerImpl must implement the ValueChangeListener interface, which defines the method processValueChange.
Action handlers and event listeners are important features of JSF providing an event driven mechanism. Every time the user does something, such as clicking a button or submitting a form, an event occurs. Event notification is then sent via HTTP to the server and handled by the FacesServlet. Events can invoke custom business logic or initiate page navigation.