13 Using Popup Dialogs, Menus, and Windows

13.4.1.1 Defining a JSF Navigation Rule for Opening a Dialog

You manage the navigation into a dialog by defining a standard JSF navigation rule with a special dialog: outcome. Using the dialog sample application shown in Figure 13-8, three navigation outcomes are possible from the Login page:

• Show the Orders page in the same window (successful login).

• Show the Error dialog page in a dialog (login failure).

• Show the New Account dialog page in a dialog (new user).

Example 13-7 shows the navigation rule for the three navigation cases from the Login page (login.jspx).

<navigation-rule>

  <!-- Originating JSF page -->
  <from-view-id>/login.jspx</from-view-id>

  <!-- Navigation case for the New Account dialog page (new user)-->
  <navigation-case>
    <from-outcome>dialog:newAccount</from-outcome>
    <to-view-id>/new_account.jspx</to-view-id>
  </navigation-case>

  <!-- Navigation case for the Error dialog page (upon login failure) -->
  </navigation-case>
    <from-outcome>dialog:error</from-outcome>
    <to-view-id>/error.jspx</to-view-id>
  </navigation-case>

  <!-- Navigation case for the Orders page (upon login success) -->
  </navigation-case>
    <from-outcome>orders</from-outcome>
    <to-view-id>/orders.jspx</to-view-id>
  </navigation-case>

</navigation-rule>

At runtime, the dialog navigation rules on their own simply show the specified pages in the originating page. But when used with command components with dialog: action outcomes and with useWindow attributes set to true, ADF Faces knows to open the pages in dialogs. This is described in the next step.

13.4.1.2 Creating the JSF Page That Opens a Dialog

In the originating page from which a popup dialog is launched, you can use either an action method or a static action outcome on the ActionSource component. Whether you specify a static action outcome or use an action method that returns an action outcome, this action outcome must begin with dialog:.

The page flow we are describing uses an action method binding on the commandButton component to determine programmatically whether to navigate to the Orders page or to the Error dialog page, and the page flow also uses a static action outcome on the commandLink component to navigate directly to the New Account dialog page. Both command components are on the Login page. Example 13-8 shows the code for the Login commandButton component.

af:commandButton id="cmdBtn"
                 text="Login"
                 action="#{backing_login.commandButton_action}"
                 useWindow="true"
                 windowHeight="200"
                 windowWidth="500"
                 partialSubmit="true"/>

The attributes useWindow, windowHeight, and windowWidth are used in opening pages in popup dialogs. These attributes are ignored if the client device does not support popup dialogs.

When useWindow="true" ADF Faces knows to open the dialog page in a new popup dialog. The windowHeight and windowWidth attributes specify the size of the popup dialog.

The action attribute on the af:commandButton component specifies a reference to an action method in the page's backing bean, Login.java. The action method must return an outcome string, which JSF uses to determine the next page to display by comparing the outcome string to the outcomes in the navigation cases defined in the faces-config.xml file. The code for this action method is shown in Example 13-9.

public String commandButton_action()
{
  String retValue;
  retValue = "orders";
  _cust = getListCustomer();
  if (_cust == null || !password.equals(_cust.getPassword()))
  {
    retValue = "dialog:error";
  }
  
  return retValue;
}

Example 13-10 shows the code for the New User commandLink component that uses a static action outcome.

<af:commandLink id="cmdLink" 
                text="New User?"
                action="dialog:newAccount"
                useWindow="true"
                partialSubmit="true"
                windowHeight="200"
                windowWidth="500" />

Instead of referencing an action method, the action attribute value is simply a static outcome string that begins with dialog:.

At runtime, ADF Faces uses the attribute useWindow="true" in conjunction with an action outcome that begins with dialog: to determine whether to start a dialog process and open a page in a popup dialog (assuming dialog: navigation rules have been defined in the faces-config.xml file).

If the action outcome does not begin with dialog:, ADF Faces does not start a process or open a popup dialog even when useWindow="true". Conversely, if the action outcome begins with dialog:, ADF Faces does not open a popup dialog if useWindow="false" or if useWindow is not set, but ADF Faces does start a new process.

If the client device does not support popup dialogs, ADF Faces shows the dialog page in the current window after preserving all of the state of the current page - you do not have to write any code to facilitate this.

When a command component is about to open a dialog, it delivers a LaunchEvent event. The LaunchEvent event stores information about the component that is responsible for opening a popup dialog, and the root of the component tree to display when the dialog process starts. A LaunchEvent can also pass a map of parameters into the dialog. For more information, see Section 13.4.1.4, "Passing a Value into a Dialog".

13.4.1.3 Creating the Dialog Page and Returning a Dialog Value

The dialog pages in our sample page flow are the Error page, the New Account page, and the Account Details page. The dialog process for a new user actually contains two pages: the New Account page and the Account Details page. The dialog process for a user login failure contains just the Error page.

A dialog page is just like any other JSF page, with one exception. In a dialog page, you must provide a way to tell ADF Faces when the dialog process finishes, that is, when the user dismisses the dialog. Generally, you do this programmatically or declaratively name a command component. Example 13-11 shows how to accomplish this programmatically using a Cancel button on the Error page.

<af:commandButton text="Cancel"
                  actionListener="#{backing_error.cancel}" />

The actionListener attribute on the af:commandButton component specifies a reference to an action listener method in the page's backing bean, Error.java. The action listener method processes the action event that is generated when the Cancel button is clicked. You call the AdfFacesContext.getCurrentInstance()returnFromDialog() method in this action listener method, as shown in Example 13-12.

public void cancel(ActionEvent actionEvent)
{
  AdfFacesContext.getCurrentInstance().returnFromDialog(null, null);
}

To accomplish telling ADF Faces that the dialog process is finished declaratively on the Account Details dialog page, attach a af:returnActionListener tag to the Cancel button component, as shown in Example 13-13. The af:returnActionListener tag calls the returnFromDialog method on the AdfFacesContext - no backing bean code is needed.

<af_commandButton text="Cancel" immediate="true">
  <af:returnActionListener/>
</af:commandButton>

No attributes are used with the af:returnActionListener tag. The immediate attribute on the af:commandButton component is set to true: if the user clicks Cancel without entering values in the required Password and Confirm Password fields, the default JSF ActionListener can execute during the Apply Request Values phase instead of the Invoke Application phase, thus bypassing input validation. For more information, see Chapter 4, "The JSF Lifecycle".

The New Account page and Account Details page belong in the same dialog process. A dialog process can have as many pages as you desire, but you only need to call AdfFacesContext.getCurrentInstance().returnFromDialog() once.

The same af:returnActionListener tag or AdfFacesContext.getCurrentInstance().returnFromDialog() method can also be used to end a process and return a value from the dialog. For example, when the user clicks Done on the Account Details page, the process ends and returns the user input values. Example 13-14 shows the code for the Done button.

<af:commandButton text="Done"
                  actionListener="#{backing_new_account.done}" />

The actionListener attribute on the af:commandButton component specifies a reference to an action listener method in the page's backing bean, New_account.java. The action listener method processes the action event that is generated when the Done button is clicked. Example 13-15 shows the code for the action listener method, where the return value is retrieved, and then returned using the AdfFacesContext.returnFromDialog() method.

public void done(ActionEvent e)
{
  AdfFacesContext afContext = AdfFacesContext.getCurrentInstance();
  String firstname = afContext.getPageFlowScope().get("firstname").toString();
  String lastname = afContext.getPageFlowScope().get("lastname").toString();
  String street = afContext.getPageFlowScope().get("street").toString();
  String zipCode = afContext.getPageFlowScope().get("zipCode").toString();
  String country = afContext.getPageFlowScope().get("country").toString();
  String password = afContext.getPageFlowScope().get("password").toString();
  String confirmPassword =
   afContext.getPageFlowScope().get("confirmPassword").toString();
  if (!password.equals(confirmPassword))
  {
    FacesMessage fm = new FacesMessage();
    fm.setSummary("Confirm Password");
    fm.setDetail("You've entered an incorrect password. Please verify that you've
     entered a correct password!");
    FacesContext.getCurrentInstance().addMessage(null, fm);
  }
  else
  {
    //Get the return value 
    Customer cst = new Customer();
    cst.setFirstName(firstname);
    cst.setLastName(lastname);
    cst.setStreet(street);
    cst.setPostalCode(zipCode);
    cst.setCountry(country);
    cst.setPassword(password);
    // And return it
    afContext.getCurrentInstance().returnFromDialog(cst, null);
    afContext.getPageFlowScope().clear();
  }
}

The AdfFacesContext.returnFromDialog() method lets you send back a return value in the form of a java.lang.Object or a java.util.Map of parameters. You do not have to know where you are returning the value to - ADF Faces automatically takes care of it.

At runtime, the AdfFacesContext.returnFromDialog() method tells ADF Faces when the user dismisses the dialog. This method can be called whether the dialog page is shown in a popup dialog or in the main window. If a popup dialog is used, ADF Faces automatically closes it.

In the sample application, when the user clicks the Cancel button on the Error page or Account Details page, ADF Faces calls AdfFacesContext.returnFromDialog(), (which returns null), closes the popup dialog, and returns to the originating page.

The first page in the new user dialog process is the New Account page. When the Details button on the New Account page is clicked, the application shows the Account Details dialog page in the same popup dialog (because useWindow="false"), after preserving the state of the New Account page.

When the Done button on the Account Details page is clicked, ADF Faces closes the popup dialog and the AdfFacesContext.returnFromDialog() method returns cst to the originating page.

When the dialog is dismissed, ADF Faces generates a return event (ReturnEvent). The AdfFacesContext.returnFromDialog() method sends a return value as a property of the return event. The return event is delivered to the return listener (ReturnListener) that is registered on the command component that opened the dialog (which would be the New User commandLink on the Login page). How you would handle the return value is described in Section 13.4.1.5, "Handling the Return Value".

13.4.1.4 Passing a Value into a Dialog

The AdfFacesContext.returnFromDialog() method lets you send a return value back from a dialog. Sometimes you might want to pass a value into a dialog. To pass a value into a dialog, you use a LaunchListener listener.

In the sample application, a new user can enter a name in the Username field on the Login page, and then click the New User link. When the New Account dialog page displays in a popup dialog, the First Name input field is automatically populated with the name that was entered in the Login page. To accomplish this, you register a LaunchListener listener on the command component that opened the dialog (which would be commandLink). Example 13-16 shows the code for the commandLink component.

<af:inputText label="Username" value="#{backing_login.username}"/>
<af:commandLink id="cmdLink" text="New User?"
                action="dialog:newAccount"
                useWindow="true" partialSubmit="true"
                launchListener="#{backing_login.handleLaunch}"
                returnListener="#{backing_login.handleReturn}"
                windowHeight="200" windowWidth="500" />

The launchListener attribute on af:commandLink specifies a reference to a listener method for the LaunchEvent in the page's backing bean, Login.java. In the launchListener method you use the getDialogParameters() method to add a parameter to a Map using a key-value pair. Example 13-17 shows the code for the launchListener method.

public void handleLaunch(LaunchEvent event)
{
  //Pass the current value of the field into the dialog
  Object usr = username;
  event.getDialogParameters().put("firstname", getUsername());
}
// Use by inputText value binding 
private String username;
public String getUsername()
{
  return username;
}
public void setUsername(String username)
{
  this.username = username;
}

To show the parameter value in the New Account dialog page, use the ADF Faces pageFlowScope to retrieve the key and value via a special EL expression in the format #{pageFlowScope.someKey}, as shown in Example 13-18.

<af:inputText label="First name" value="#{pageFlowScope.firstname}"/>

At runtime when a command component is about to launch a dialog (assuming all conditions have been met), ADF Faces queues a LaunchEvent. This event stores information about the component that is responsible for launching a dialog, and the root of the component tree to display when the dialog process starts. Associated with a LaunchEvent is a launchListener, which takes the LaunchEvent as a single argument and processes the event as needed.

In the sample application, when ADF Faces delivers the LaunchEvent to the launchListener registered on the commandLink component, the handleLaunch() method is called and the event processed accordingly.

In ADF Faces, a process always gets a copy of all the values that are in the pageFlowScope of the page from which a dialog is launched. When the getDialogParameters() method has added parameters to a Map, those parameters also become available in pageFlowScope, and any page in the dialog process can get the values out of pageFlowScope by referring to the pageFlowScope objects via EL expressions.

Unlike sessionScope, pageFlowScope values are visible only in the current page flow or process. If the user opens a new window and starts navigating, that series of windows has its own process; values stored in each window remain independent. Clicking on the browser's Back button automatically resets pageFlowScope to its original state. When you return from a process the pageFlowScope is back to the way it was before the process started. To pass values out of a process you would use AdfFacesContext.returnFromDialog(), sessionScope or applicationScope.

13.4.1.5 Handling the Return Value

To handle a return value, you register a return listener on the command component that launched the dialog, which would be the New User link component on the Login page in the sample application. Example 13-19 shows the code for the New User link component.

<af:commandLink id="cmdLink" text="New User?"
                action="dialog:newAccount"
                useWindow="true" partialSubmit="true"
                returnListener="#{backing_login.handleReturn}"
                windowHeight="200" windowWidth="500" />

The returnListener attribute on commandLink specifies a reference to a return listener method in the page's backing bean, Login.java. The return listener method processes the return event that is generated when the dialog is dismissed. Example 13-20 shows the code for the return listener method that handles the return value.

public void handleReturn(ReturnEvent event)
{
  if (event.getReturnValue() != null)
  {
    Customer cst;
    String name;
    String psw;
    cst = (Customer)event.getReturnValue();
    name = cst.getFirstName();
    psw = cst.getPassword();
    CustomerList.getCustomers().add(cst);
    inputText1.setSubmittedValue(null);
    inputText1.setValue(name);
    inputText2.setSubmittedValue(null);
    inputText2.setValue(psw);
  }
}

You use the getReturnValue() method to retrieve the return value, because the return value is automatically added as a property of the ReturnEvent.

At runtime in the sample application, when ADF Faces delivers a ReturnEvent to the ReturnListener registered on the af:commandLink component, the handleReturn() method is called and the return value is processed accordingly. The new user is added to a customer list, and as a convenience to the user any previously submitted values in the Login page are cleared and the input fields are populated with the new information.