-C H A P T E R

C H A P T E R 9

Tutorial--Section 2.3
Create Customer Page

This chapter describes how to create a page in the Sun ONE Application Framework that displays data from a model that accesses a relational database.

Task 3: Create the Customer Page

You will now create the second page of the application. However, this page will be bound to a model. This binding process automatically creates display fields on the page that display the data that is stored in the model's fields.

Add a ViewBean

1. Select the main module.

2. Click the Add Page button on the Sun ONE Application Framework toolbar.

This figure shows the Add Page selection on the Sun ONE Application Framework toolbar.

The Select View Type panel displays.

This figure shows the Select View Type panel.

3. Enter CustomerPage in the Name field (to replace <default>).

4. Select Basic ViewBean to create a ViewBean type Page component.

5. Click Next.

The Associate JSP panel displays.

This figure shows the Associate JSP panel.

6. Click the Use formatting to beautify fields on JSP check box to apply some basic formatting.

7. Click Next.

The Model Associations panel displays.

This figure shows the Model Associations panel.

8. Expand Current Application Components to expose jatotutorial -> main.

9. Select Customer model.

10. Click Add.

11. Click Next.

The Bind Display Fields panel displays.

This figure shows the Bind Display Fields panel.

You only need to add three fields.

12. Add the first field.

a. Select the CUSTOMER_TBL_CUSTOMER_NUM field.

Accept the Static text default.

b. Click Add field(s).

The CUSTOMER_TBL_CUSTOMER_NUM field is added to the Bound fields list box.

13. Add the second and third fields simultaneously.

a. Select the CUSTOMER_TBL_EMAIL and CUSTOMER_TBL_NAME fields (hold down the Ctrl key to select multiple non-sequential fields).

b. Select Text field.

c. Click Add field(s).

The CUSTOMER_TBL_EMAIL and CUSTOMER_TBL_NAME fields are added to the Bound fields list box.

14. Click Finish.

You have created the ViewBean.

The figure on the left shows the CustomerPage object in the main module. The figure on the right shows the code that was created.

15. Double-click CustomerPage.

The code displays in the right-hand panel.

Expand all the subnodes of the CustomerPage to see the JSP Page, Visual Components, and Non-Visual Components that were automatically generated by the wizard.

Note - Like the LoginPage, a JSP for the CustomerPage was added to the Documents folder (/jatotutorial/main), and there is a link to that JSP under this ViewBean's JSPs folder.

You see three visual components that were created because you indicated that you wanted to bind to the CustomerModel's fields. This allows data to automatically be displayed on the Customer page and changes to those fields to be automatically mapped back into the model, at which point you can execute the model to perform an update to the database. All of the SQL generation and connection creation are handled for you by the Sun ONE Application Framework.

If you really want or need to work with the JDBC API directly, the Application Framework does not require that you use all of the features it provides, and you are free to handle all of the JDBC responsibilities on your own. In other words, you can pick and choose what you need to use in the Sun ONE Application Framework, but it is most likely that the Sun ONE Application Framework's implementation is exactly what you need.

You also see an entry under the Non-Visual Components node which is a reference to the CustomerModel class.

Add a Button Component

1. Add a button to the CustomerPage.

The following table contains the specifications for adding a button to the CustomerPage. Use the Component Palette to add the button, just like you added the fields for the Login Page.

2. If the Component Palette is not visible, select menu option:

View -> Sun ONE Application Framework -> Component Palette.

The table shown below lists the specifications for adding a button to the CustomerPage. The left column shows the button type, the middle column shows the name, and the right column shows the initial value.

Type	Name	Initial Value
Button	update	Update

3. Enable the button to update the customer record.

a. Select the update button field.

b. In the property sheet of the button, click the value area of the RequestHandler property.

The ellipsis button displays.

c. Click the ellipsis button.

The Command Descriptor editor launches.

This figure shows the Command Descriptor editor.

4. Select Create new shared instance.

5. Select WebAction Command from the list.

6. In the Properties tab, change the name to updateWebAction.

7. Select the Component Properties tab at the bottom of the editor.

8. Select ACTION_UPDATE for the Operation Name property.

Accept the defaults for the other two properties.

9. Click OK.

You have finished setting this property.

Note - A new entry is added under the Non-Visual Components node, and the Command Descriptor property is set.

This figure shows the Non-Visual Components node with the Command Descriptor property that has been set.

Making a Model Auto Update

You now need to add the customerModel reference as an Auto Updating Model on the CustomerPage.

You accomplish this by populating the Page's Auto Updating Models property with the appropriate model reference--in this case, the customerModel reference that was created for you by the wizard as a result of the model association or field binding you specified.

1. Select the CustomerPage node.

2. Click the value area for the Auto Updating Models property.

The ellipsis button ("...") displays.

This figure shows the ellipses button ("...") in the Auto Retrieving Models property.

3. Click the ellipsis button.

The Auto Updating Models custom editor launches.

Note that the Properties area is blank when this editor first displays.

4. Click New.

This adds an entry.

This figure shows the Auto Retrieving Models custom editor.

5. Select customerModel from the Auto Updating Models combo box.

6. Click OK.

The property should now have the [customerModel] entry.

This figure shows the Auto Updating Models [customerModel] property.

Note - The combination of the button's update Web action command descriptor and the auto retrieving or updating models configuration causes the CustomerModel to be executed when the Customer page is displayed or when the CustomerPage's Update button is clicked.

As an alternative to the declarative auto execution of this model, you can also write some code to perform the same purpose. Commonly, this code would be implemented in the Update button's handleUpdateRequest event (similar to how the code was implemented for the Login button on the Login page).

Add a Hidden Field to the Customer Page

1. Expand the CustomerPage node.

2. Expand the Visual Components node.

3. Select the Visual Components node.

4. Select add a Hidden Field component using the Component Palette.

A hidden field is added to the CustomerPage's Visual Components node.

5. Rename the hidden field as hiddenKey.

6. Bind the hiddenKey field to the same model field that the customerTblCustomerNum static text field is bound.

7. Select the hiddenKey field.

8. On the property sheet, set the Model Reference property to customerModel by selecting from the drop down box.

This figure shows the Model Reference property option.

9. Set the Model Field Binding property.

a. Click in the value area of the Model Field Binding property.

b. Click the ellipsis button to launch the Model Field Binding property editor.

This figure shows the Model Field Binding property editor.

10. Click the ellipsis button of the Read field name property to launch the Model Field Chooser editor.

This figure shows the Model Field Chooser editor.

11. Select CUSTOMER_TBL_CUSTOMER_NUM.

12. Click OK.

The read and write fields are populated with the CUSTOMER_TBL_CUSTOMER_NUM model field.

13. Click OK.

This completes setting the Model Field Binding property for the hiddenKey display field.

This figure shows the hiddenKey display field.

Because the static text field is not an HTML input field, it's value will not be submitted back to the server when the update button is clicked. And because the customer number is the key field in the database table, the update logic needs this key value in order to limit the update to a single database row. This value must be posted back along with the other input field values so that you can perform an update on the proper customer record rather than updating every record in the table. To achieve this, you will preserve the customer number field value in a hidden field, which will be posted back on form submit and mapped back into the CUSTOMER_TBL_CUSTOMER_NUM model field.

Caution - If you neglect this step, no key field value is submitted with the form. The resulting JDBC update statement would lack a WHERE clause, and therefore result in the unintentional modification of the entire table.

This is not exactly the way you would implement this in the real world. For security reasons, you would not want to expose the key field in the HTML as an input field that hackers could modify.

Note - This is not an issue specific to the Sun ONE Application Framework, but rather one that must be addressed by any Web application, no matter which framework (or no framework) is used to implement Web applications

The Sun ONE Application Framework provides a value add feature called Page Session that provides a technique to implement this solution more securely, but is outside the scope of this tutorial. Refer to the JatoSample application and the Sun ONE Application Framework Developer's Guide for more details.

Format the JSP

1. Expand the JSPs node under CustomerPage node.

2. Double-click the CustomerPage JSP to open it in the editor window.

3. Provide propercase labels for the fields.

Following is an example of minimal JSP formatting (only pertinent code is shown here). Some of the HTML source code is shown in bold for clarity.

<jato:form name="CustomerPage" method="post">

<table border=0 cellspacing=2 cellpadding=2 width="100%">

<tr>

  <td align=right valign=middle width="20%"><b>Customer #:</b></td>

  <td align=left valign=middle><jato:text name="customerTblCustomerNum"/></td>

</tr>

<tr>

  <td align=right valign=middle width="20%"><b>Email:</b></td>

  <td align=left valign=middle><jato:textField name="customerTblEmail"/></td>

</tr>

<tr>

  <td align=right valign=middle width="20%"><b>Name:</b></td>

  <td align=left valign=middle><jato:textField name="customerTblName"/></td>

</tr>

</table>

<jato:button name="update"/>

<jato:hidden name="hiddenKey"/>

</jato:form>