Web applications
often need web
pages that display a form to get input from a user. Command
submission is the process of triggering an application-specific command
or an action when a UICommand
type component is activated
by the user. One example is the submission
of a web form when a user clicks the Submit button on a web page. This
submission is typically used to take action on the
server side. Other examples include logging in a user, and navigating a
user to
the next
page.
A web page developer must decide how to handle these command
submissions. The JavaServer[TM] Faces API provides two options: Action
or ActionListener
.
This entry describes which strategy is good for each situation.
Some considerations for making this design choice include the following:
ActionListener
can not. ActionListener
has access to the ActionEvent
.The following table summarizes
the recommendations for handling command submissions.
Strategy | Recommendation |
---|---|
Use Action |
For normal event handling of JavaServer Faces components |
Use ActionListener |
For event handling of JavaServer Faces components only in cases where you need to identify the component that caused the event |
Action listeners should generally be used when a component needs to have its state modified whenever another (UICommand) component is activated. For example, you might have a button on your form that switches between the "compact" version of a form (with only a few fields) and the "full" version of the form (with all possible fields). Although it is possible for the page author to register action listeners directly in the page, most of the time this could be done programmatically by the components themselves. Action listeners cannot directly influence navigation.
An action, on the other hand,
should be considered the primary
design element for invoking application actions that might potentially
affect navigation, including any scenario where the command in question
is the submit button on a form. The action method can return
null
to cause the current page to be
redisplayed, or
return an outcome string that can be mapped to a navigation rule to
determine which page is to be displayed next.
While designing custom JavaServer Faces components, sometimes
you
need both
behaviors. For example, consider a custom tree component for navigating
a hierarchy of objects. If a button is clicked, you want other
components to be notified, and you want to associate an outcome to a
navigation rule. Here you can use action and action listener together.
However, in most cases the registration of action listener could be
transparent to the page author because the components register the
action listeners themselves. A well-designed custom component avoids
requiring a page author to explicitly register
action listeners (with the <f:action_listener>
tag), because it results in exposing implementation details of the
component to the page author.
One consequence to consider is that the resulting design primarily uses
Action
for handling most command submissions.
The use of
ActionListener
is limited to the few cases
where you need
to extract information from the UI element that generated the
event.
For the button labeled Guest
Login, the action mapping is specified
to be success
.
This results in the invocation of the navigation rule corresponding to
the success
outcome from this page. Code Example 2
shows the corresponding definition of the
navigation rule from the faces-config.xml
file:
Note that multiple navigation cases can be defined with each corresponding to a different outcome.
The action mapping can also bedefined dynamically by specifying an action method instead of specifying the outome. The Code Example 3 illustrates how this can be done:
For the button labeled Login,
the action mapping is to invoke the login
method in the backing bean, CommandSubmissionBean
.
If the login
method returns the success
outcome, the response.jsp
is invoked as per
the
navigation rule in Code
Example 2.
For the button labeled Show
More Details, the method detailsActionListener
of the
backing bean
CommandSubmissionBean
is specified as an
action listener.
This method
is invoked whenever the button is pressed. This method can access all
other components in the page and modify their state as needed.