Skip Headers

Oracle® Application Development Framework Case Manual 10g Release 2 (10.1.2) B19163-01 |
| Library | Product | Contents

Previous | Next |

# 8 Lesson Five: Requiring the User to Sign Into an Account

This chapter contains the following sections:

- Section 8.1, "Introduction"

- Section 8.2, "Analyzing the Sign-In Page Flow"

- Section 8.3, "Laying Out the Sign-In Page"

- Section 8.4, "Laying Out the Register New User Page"

- Section 8.5, "Laying Out the Generic Form Control Page"

- Section 8.6, "Laying Out the Account Created Page"

- Section 8.7, "Hands-On for Lesson 5"

## 8.1 Introduction

The pages discussed in Lesson 4 demonstrate how to process the customer order. In this lesson, we examine how to require the customer to sign in to an existing account, and, in the case of a new customer, how to create an account. To accomplish this, we will examine the structure of these JSP pages:

- `registernewuser.jsp`, to take a new customer's account information

- `signin.jsp`, to accept an existing customer's user ID and password

- `accountcreated.jsp`, to confirm the new customer's account creation

In this lesson, we'll examine the layout of these new JSP pages and describe how the application returns the customer to the previous page after sig- in is verified.

## 8.2 Analyzing the Sign-In Page Flow

The page flow proceeds with the action forward `requireslogin` from the `/confirmshippinginfo` data page. The forward destination is the `/signin` data page. In this application, we have choosen to require sign-in before taking the customer's shipping information. Although this task could have been performed earlier, we prefer not to interfere with the customer's ability to browse the catalog until they proceed to checkout. To ensure that the customer does sign in, the `initializeModelForPage()` method in the `confirmshippinginfo` data action performs this test:

    protected void initializeModelForPage(DataActionContext ctx) {
       HttpServletRequest request = ctx.getHttpServletRequest();
       if (!AppUserInfo.isSignedOn(request)) {
           ctx.setActionForward("requireslogin");
       } else {
           getToyStoreService(ctx).createNewOrder(AppUserInfo.signedInUser(request));
         } }

If the user has signed in already, the order is created by the service method `createNewOrder()` and the application displays the `confirmshippinginfo.jsp` page, as described in Lesson 4. However, assuming that the customer has not signed in, the Struts method `setActionForward()` is invoked with the forward `requireslogin` to initiate the action mapping and display the `signin.jsp` page.

After programmatically invoking the action forward and displaying the `signin.jsp` page, the user must be able either to sign in or to register as a new customer for the first time. The page flow diagram represents the transition from `signin.jsp` to `registernewuser.jsp` as a dashed line to distinguish an ordinary page link from an action forward (represented by a solid line). The difference is that the page link does not map to an associated data action and therefore a link cannot cause the application to attach the binding container to the target page. As we will see, the register new user page is an empty form with no data displayed.

The last task of the sign-in page flow is to provide confirmation to the user once they have registered a new account. The account confirmation task is represented in the page flow diagram by the `save` action forward with the target /accountcreated page forward icon. The final diagram with the sign-in page flow is shown in Figure 8-1, "Sign-In Page Flow".

Figure 8-1 Sign-In Page Flow

The page forward has not yet been used in the Struts page flow of this application, but it is conceptually similar to a page link: in either case the target page requires no data binding. In the case of a page forward, the icon is a representation of a Struts action that always forwards to a specified destination web page.

Best Practice Tip: Although the Struts page flow diagram allows you to insert JSP page icons into the diagram, in most cases you will use the Page Forward icon instead of a JSP icon to represent the target web page. This standard practice ensures that all web pages are represented in the Struts configuration file and therefore permits the Struts controller to handle page navigation.

We'll reserve the action mapping discussion for the `confirmshippinginfo.do` action until the next lesson, when we also describe the target pages in the flow diagram.

## 8.3 Laying Out the Sign-In Page

The main design feature of the `signin.jsp` page is the use of a Struts form (`<html:form>` tag) to accept user input. The fields of the form are also Struts HTML elements that access the properties of the form bean:

- `<html:text>`, where the `property` attribute is the name of the Oracle ADF attribute binding that accesses the desired business object

- `<html:password>`, where the `property` attribute is the name of the Oracle ADF attribute binding that accesses the desired business object

When the user clicks to submit the form, with these additional attributes set, at runtime the Oracle ADF binding container populates the bindings with the values of the username and password HTML form fields. Those values are accessible by the `onVerifySignin()` event-handler method of the `SignInAction` class, which will handle the sign-in form's postback when the user submits the form.

The `onVerifySignin()` method in the data action first verifies that neither the `username` nor `password` properties is blank, and then calls the `validSignon()` method on the `ToyStoreService` business service interface to verify whether the username/password combination represents a valid web store user. If any validation check fails, `onVerifySignin()` adds a Struts `ActionError` object to the `ActionErrors` collection so that the view layer can present appropriate error messages to the user and so that the user is returned to the sign-in page to try again. If the sign-in validation check succeeds, then the `onVerifySignin()` method calls a helper method (`signIn()` method of the `AppUserInfo` class) to flag the current user as signed in, and returns the appropriate page to forward the request to.

Since several different actions in the application can require the user to log in, the `setForwardAction()` method in this data action uses the `target` parameter to return the correct "next" page in the flow, based on which action required the user to log in.

Best Practice Tip: With the addition of a secondary resource message file for global errors identified by the key `GlobalErrors`, you can ensure that error strings like those represented by the `INVALIDLOGIN` constant are translated into user-readable messages. You make Struts aware of the names of your message resource files in `struts-config.xml`, where the `<message-resources>` element with the key attribute defines the location of the secondary message resource:
    <message-resources key="GlobalErrors"
                        parameter="toystore.view.GlobalErrors"/>

## 8.4 Laying Out the Register New User Page

The `registernewuser.jsp` page (used by the `/register` data page) renders the data entry form that allows users to register on the site for the first time. Because the results produced in the browser of this page are nearly identical to the `editexistingaccount.jsp` page, we decided to render the entire form by the single `<jsp:include page="formControl.jsp">` tag. This tag works like a reusable component, including the contents of the `formControl.jsp` page. The nested `<jsp:param>` tags pass three parameters to the reusable component page:

- `dataPage` — the name of the current data page

- `saveButtonLabelKey` — the message bundle key to the label to be displayed on the Save button

- `saveButtonEvent` — the name of the event to be associated with the clicking of the Save button.

So the actual work being done lies in the `formControl.jsp` component page. The page builds a data entry form with one databound control for each control value binding in the current binding container.

Note: The following discussion represents a generic, metadata-driven way of rendering the binding data in contrast to the more traditional approach of specifying each binding in the page source. In contrast to this generic technique explained below, the Toy Store application also includes the register new user page to render a data entry form in the traditional way. Both forms render the same set of controls for account data, so you can compare the two approaches and pick the one that will suit your application needs best. See Lesson 6 for a discussion of the register new user page.

## 8.5 Laying Out the Generic Form Control Page

The form control page begins with some examples of using the `<c:choose>`, `<c:if>`, and `<c:set>` tags. The following excerpt uses these tags to conditionally set up the values of local page variables named `eventName`, `buttonLabel`, and `buttonLabelKey`, based on whether and which of the expected input parameters were provided. We'll use these variables later in the page as part of constructing the Save button at the bottom of the generated form.

    <c:choose>
       <c:when test="${not empty param.saveButtonEvent}">
         <c:set var="eventName" value="${param.saveButtonEvent}"/>
       </c:when>
       <c:otherwise>
         <c:set var="eventName" value="Commit"/>
       </c:otherwise>
    </c:choose>
    <c:if test="${not empty param.saveButtonLabel}">
       <c:set var="buttonLabel" value="${param.saveButtonLabel}"/>
    </c:if>
    <c:if test="${not empty param.saveButtonLabelKey}">
       <c:set var="buttonLabelKey" value="${param.saveButtonLabelKey}"/>
    </c:if>

The `formControl.jsp` page goes on to use the `<html:errors>` tag as part of a "global errors" section of the input form, where any errors that are not attribute-specific will show up:

    <center>
       <table border="0">
         <tr>
           <td><html:errors bundle="GlobalErrors"
                          property="<%= ActionErrors.GLOBAL_ERROR %>"/></td>
         </tr>
       </table>
    </center>

Next, the form uses the value of the `dataPage` parameter passed in by the `<jsp:include>` tag as part of opening the `<html:form>` tag. Notice that since we cannot use EL expressions directly in the `<html:form>` tag's `action` attribute, we first use `<c:set>` to set a local page variable named `name` with the EL-expression value we want, and then we use a JSP scriptlet to pass the value of this `name` variable to the `action` attribute:

    <c:set var="name" value="${param.dataPage}.do"/>
    <html:form action='<%= pageContext.getAttribute("name")%>'>
         <!-- etc. -->
    </html:form>

The form includes the standard hidden field that the Oracle ADF controller layer uses to detect whether the user has tried to submit the same form multiple times in rapid succession:

    <input type="hidden" name="<c:out value='${bindings.statetokenid}'/>"
                value="<c:out value='${bindings.statetoken}'/>"/>

Next we begin the loop that will create an HTML form field for each control value binding in the binding container. Inside the `<table>` tag, we have the following `<c:forEach>` iteration:

    <c:forEach var="curBinding" items="${bindings.ctrlBindingList}">
       <% JUControlBinding cb =
            (JUControlBinding)pageContext.getAttribute("curBinding");
          if (cb instanceof JUCtrlValueBinding &&
            !(cb instanceof JUCtrlRangeBinding) &&
            !(cb instanceof JUCtrlHierNodeBinding)) { %>
        <!-- Build control for current control value binding in here -->
      <% } %>
    </c:forEach>

The `<c:forEach>` loop iterates over the list of control value bindings from the binding container. Since this list might include control action bindings, we need to skip over these when rendering the input controls. Since we want to keep things simple, we'll also skip over `RangeBindings` and `TreeBindings` too. The EL expression language doesn't have a built-in `instanceof` operator, so we're using a JSP scriptlet to insert a regular Java-language `if` statement to perform the combination of `instanceof` checks.

Note: We could have decided to generically render a set of buttons for any of the action bindings found in the binding container, which would be of type `JUCtrlActionBinding` in the `oracle.jbo.uicli.binding package`; instead, the application just renders a single Save button on the form.

Since we specified the `var="curBinding"` attribute on the `<c:forEach>` tag, inside the loop we can refer to this `curBinding` loop variable to access the current control value binding as part of our generic form input control generation. In the following excerpt, notice how we're making use of the binding properties in our EL expressions like `tooltip`, `mandatory`, and `label` to access this metadata from the current control binding.

    <c:forEach var="curBinding" items="${bindings.ctrlBindingList}">
       <% JUControlBinding cb =
            (JUControlBinding)pageContext.getAttribute("curBinding");
          if (cb instanceof JUCtrlValueBinding &&
            !(cb instanceof JUCtrlRangeBinding) &&
            !(cb instanceof JUCtrlHierNodeBinding)) { %>
        <tr>
          <th align="right" title="<c:out value='${curBinding.tooltip}'/>">
            <c:if test="${curBinding.mandatory}">*&nbsp;</c:if>
            <c:out value="${curBinding.label}"/>
          </th>
          <td>
             <c:set var="name" value="bindings.${curBinding.name}"/>
             <adf:inputrender model='<%= pageContext.getAttribute("name")%>'/>
          </td>
          <c:set var="name" value="${curBinding.name}"/>
          <td>
            <html:errors property='<%= pageContext.getAttribute("name") %>'/>
          </td>
        </tr>
      <% } %>
    </c:forEach>

To actually render the HTML form control, we use the `<adf:inputrender>` tag, which is set up to render an appropriate tag based on the datatype of the current binding's attribute value (the use of Business Components metadata to invoke a custom renderer will be discussed in Lesson 6). We repeat our trick of using `<c:set>` to set a local page variable named `name` to the concatenation of the string "`bindings`." with the name of the current binding, which is what the `<adf:inputrender>` tag expects as the value of its model attribute. We use the `<html:errors>` tag to show any attribute-level validation errors that might occur next to the control to which they are relevant. We again use the `<c:set>` trick to make the value of the `<html:errors>` tag's `property` attribute match the name of the current binding.

Finally, as the following excerpt shows, we use a `<c:choose>` tag to put the appropriately labeled Save button at the bottom of the form. Based on whether the user specified a button label or a button label key, we either use the literal label string or employ the `<bean:message>` tag to look up the label key for us. We're using our local page variable `eventName` that we set up at the top of the page to fill in the right name for the button to generate that event when the user clicks it.

    <c:choose>
       <c:when test="${not empty buttonLabel}">
         <input name="event_<c:out value="${eventName}"/>" type="submit"
                 value='<c:out value="${buttonLabel}"/>'/>
       </c:when>
       <c:when test="${not empty buttonLabelKey}">
         <input name="event_<c:out value="${eventName}"/>" type="submit"
                 value='<bean:message name="buttonLabelKey"/>'>
       </c:when>
       <c:otherwise>
          <input name="event_<c:out value="${eventName}"/>" type="submit"
                 value='Submit'/>
       </c:otherwise>
    </c:choose>

## 8.6 Laying Out the Account Created Page

As previously explained, the Struts page flow uses a page forward to represent the `accountcreated.jsp` page. No data action is necessary to render this page because no bindings are used to display information. The page contains a single link that allows the user to return to the home page after creating their account:

    <a href="<c:url value='home.do'/>">
                  <bean:message key="accountcreated.gotomainpage"/></a>

In the following hands-on, you can optionally explore adding a databound text field to display the customer name in the page. This single change will necessitate changing the page forward to a data page element in the Struts diagram.

## 8.7 Hands-On for Lesson 5

The following hands-on shows how you can easily change a Struts page forward (`/accountcreated`) that displays no data bindings into an Oracle ADF data page capable of displaying the customer name in the page.

1. From the Struts page flow diagram, locate the /accountcreated page forward icon and double-click to open the `accountcreated.jsp` page in design view.

2. With the `accountcreated.jsp` page displayed, open the Data Control Palette and expand the ToyStoreService data control, Accounts.

3. Locate the Firstname attribute node under Accounts and drag the attribute node into the open page so that it appears before the message `accountcreated.header`.

4. In the Selected Page Flow Data Binding Option dialog, select Convert the selected page to a data page to convert the selected page to a data page and click OK.

5. Select the Source tab and locate the new value binding. The binding should appear before the `<bean:message>` tag. Type an extra space to separate the two:

       <h2><c:out value="${bindings.Firstname}"/> <bean:message
                                                       key="accountcreated.header"/>
       </h2>

6. Return to the Struts page flow diagram and observe the new /accountcreated data page substituted for the original page forward. Select the Source tab and observe the modified action mapping:

       <action path="/accountcreated"
               className="oracle.adf.controller.struts.actions.DataActionMapping"
               type="oracle.adf.controller.struts.actions.DataForwardAction"
               name="DataForm" parameter="/WEB-INF/jsp/accountcreated.jsp">
               <set-property property="modelReference"
                             value="WEB_INF_jsp_accountcreatedUIModel"/>
       </action>

7. In the Application Navigator, expand toystore.view and double-click WEB_INF_jsp_accountcreatedUIModel.xml to open the newly created UI model definition file and observe the Oracle ADF data control definitions.

   The `UIModel.xml` definition file is created in JDeveloper the first time you drop a databound control from the Data Control Palette into your open JSP page.

8. In the Application Navigator, select WEB_INF_jsp_accountcreatedUIModel.xml so that it appears highlighted, and open the Structure window. Observe the AccountIterator iterator and Firstname value binding. You may double-click these items to edit the contents of the UI model definition file.

9. Right-click the home.do action and choose Run to launch the application. Click any category in the home page. Select any product link and add it to your cart. Proceed to checkout. When asked to sign in, click the Register as a New User link instead. Complete the form and supply a fictitious customer name and account information (be sure to observe validation errors for the entered data). Then click Submit. The customer's first name that you just created should appear in the account created page.

The data page manages the model data binding for the page. Oracle ADF provides the data page (`oracle.adf.controller.struts.actions.DataForwardAction`) to prepare the binding context for databound web pages and to execute custom business service methods exposed through the model. In this case, no business methods are required, and the standard `DataForwardAction` class will suffice to prepare the binding context before posting back to the page to be displayed.

Note that the binding displays the name in all lowercase. It is possible to create a service method to convert the `username` attribute to initial caps and to execute that method in a custom `DataForwardAction` class, similar to the ones described in previous lessons.