In this tutorial, you create a page flow diagram, then you
create the web pages that display the business components created for you in
a prebuilt application. To understand how these business components were created,
you can refer to the Developing Business Services
with ADF Business Components OBE.
This tutorial also
covers linking up the pages to complete the page navigation and also includes
making enhancements to the user interface.
Place the cursor over this icon to load and view all
the screenshots for this tutorial. (Caution: Because this action loads all screenshots
simultaneously, response time may be slow depending on your Internet connection.)
Note: Alternatively, you can place the cursor
over each individual icon in the following steps to load and view only the screenshot
associated with that step.
Overview
Corresponding to what was built in the previous tutorial
(Developing Business Services with ADF Business
Components), where you built the business components model and implemented
validation and business rules, you now build the page flow of the application.
As you start building the pages, it is very likely that you need to adjust pieces
along the way. The tutorial guides you through the creation of the pages, and
then you run and test each page individually.
When you define the page flow, you define named navigation cases that specify what page or pages are accessible from a particular page. You implement the page flow by adding
actions to the pages that have the same names as the navigate cases in the page
flow. The navigation cases tell the application where to navigate when
an event by that name is raised on a page. You also add the functionality to
create and edit customers and to commit or rollback the customers data. You
also enhance the user interface by changing some of the text input fields
to check boxes, radio buttons and drop down lists.
Starting from a hand drawn diagram of your pages, you
create the page flow of your application. You know your client would like to
see a few pages, so you decide to build the pages that enable querying the customer's
table, editing customer details, and querying the orders for a customer.
After the basic functionality
of the pages that you have built is in place, you can concentrate your effort
on making the interfaces better for the users. You add some extra
functionality for committing and rolling back data. Also, adding some GUI controls
makes the data entry task easier. In addition you would like to make the
CustomerID field non-editable in all cases except when a new customer is being
added, because the CustomerID is the key for customer data and it should not be
changed for existing customers.
As you begin to develop the application, you probably have some sort of plan
in mind for the screens that the user needs to see and how
the user should navigate from one to another. Perhaps you draw a rough sketch
of these ideas similar to the following:
.
JDeveloper provides a visual tool to diagram the page
flow of the application. There is much more that occurs behind
the scenes of this visual tool, which provides far more functionality than simply
drawing a diagram. However, for now you use it to capture an overview of the
application that you plan to build.
To create a page flow diagram of the planned application,
perform the following steps:
1.
In the Applications
Navigator, right-click the ViewController project and select Open JSF Navigation from the context menu.This
opens the faces-config.xml file in the Web Content
| Web INF node.
The page flow diagram opens in the editor.
2.
In the Component Palette to the right of
the visual page flow editor, ensure that JSF Navigation Diagram
is selected from the dropdown list at the top. If the Component Palette is not visible, select View | Component Palette.
Click JSF Page, then click the diagram. Type over
the name of the new page: browseCustomers.
(You need only type browseCustomers; the
"/" and extension .jsp
are added for you.)
Note that the page icon for /browseCustomers shows a yellow alert because
there is no corresponding page built for it yet.
3.
Create two additional pages, /editCustomers
and /browseCustomerOrders, on the diagram:
You'll notice that the file extension for both these pages is .jsp
4.
Next you create JSF Navigation Cases between the pages.
The significance of these becomes clear later; for now you can think
of them as visual indicators of the flow of the application.
To add the navigation, click JSF Navigation Case in
the Component Palette, then click the source, browseCustomers,
and then the destination, browseCustomerOrders. You
can also click any intermediate points where you want the line to bend.
5.
To modify the navigation properties, select the JSF
Navigation Case you have just created and change the From Outcome
property to customerOrders using the Property Palette.
You'll notice that the navigation flow name changes on the diagram to customerOrders.
6.
Create a return navigation case from browseCustomerOrders
to browseCustomers. Again, change the name of the navigation
flow. This time edit it directly on the diagram by selecting
the flow name. Call the navigation case browseCustomers.
7.
Now create three JSF Navigation Cases between the pages
browseCustomers and editCustomers, the first from browseCustomers
to editCustomers, setting the From Outcome property
to editCustomers.
Create the next two from the editCustomers back to
the browseCustomers, setting the From Outcome property
to cancel and commit, respectively.
An alternative approach to setting this property is to double-click
the flow to invoke the dialog and edit the From Outcome property.
8.
Click Save All
or select File | Save All to save your work.
In this section of the tutorial, you define the various pages, binding them to the data as you go.
First you build a web page that is
used to query data from a database table. To build a databound web page for
browsing, perform the following steps:
1.
In the page flow diagram, double-click the /browseCustomers data page. (This page does not yet exist.)
2.
The Create JSF JSP wizard opens; if you are presented with the Welcome screen, click Next.
3.
On the JSP File page of the wizard, accept the proposed page name browseCustomers.jsp. Let the other options on that page default by clicking Next.
4.
On the Component Binding page of the wizard, accept the defaults by clicking Next.
5.
On the Tag Libraries page of the wizard, ensure that you have the ADF Faces libraries in the Selected Libraries list. If the ADF libraries are not in the Selected Libraries list, select them in the Available Libraries list and click Add to shuttle them to the Selected Libraries list.
Click Next.
6.
Accept the defaults on the HTML Options page, click Next.
7.
Click Finish to create the page and invoke a blank JSP in the visual editor.
8.
JDeveloper and Oracle ADF make it easy to add data-aware components to a page. Two tabs should appear to the right of the blank page. The Components tab shows all of the non-data bound components, while the Data Controls tab shows all of the ADFdata-bound components.
Switch to the Data Controls tab. (If this palette is not visible, select View | Data Control Palette from the main menu.)
You can see the application module displayed in the Data Control Palette. Expand the CustomerOrdersBusinessServicesDataControl. Expand the CustomersView1 node. Notice the items displayed are those selected when you built the view object.
9.
Select CustomersView1 and drag it onto the page. You will be presented with a menu of choices. Select Tables | ADF Read-only Table.
10.
On the Edit Table Columns dialog, check Enable Selection and Enable Sorting. (Do not close the editor yet)
11.
You are creating a browse and query page and so do not need to display all of the columns from the view object on the page, although you will need all of the columns for the edit page.
Shift-Click (or Ctrl-Click to select individual columns) to select all the columns except CustomerId, CustFirstName, CustLastName, and CustEmail and click Delete.
Click OK.
12.
To test the page that you have built, you can run it from the Applications Navigator or from the page itself. In this case go back to the page flow diagram. Notice the incomplete (exclamation) icon is no longer displayed on the /browseCustomers data page.
Right-click the /browseCustomers page on the diagram and select Run from the context menu to launch an internal server that runs your page.
13.
The read-only web page runs in a browser and queries the Customers table. Notice that the labels are those that you specified for the entity object and the view object in a previous tutorial, and that the sort order is according to the ORDER BY clause that you set for the view object in that tutorial.
14.
You can reorder the records by clicking on the column labels. An icon displays to indicate which column is driving the ordering and whether this is ascending or descending. Ensure you can navigate to the last record and back again. Close the browser when you are done.
15.
If you have time, take a look at what happened when you created the page. Go back to JDeveloper and in the Applications Navigator, expand ViewController | Application Sources. There are a number of packages available.
Expand view.pageDefs and select browseCustomersPageDef.xml.
In the Structure window below, select executables | CustomersView1Iterator. The row iterator sends the current row to individual control bindings to display current data. Iterator bindings can specify the number of rows to display in a web page. Notice that if you select CustomersView1Iterator, and look at the Property Inspector, you can see the number of records returned by the value set for the RangeSize.
Now expand bindings | CustomersView1. Here you'll see all the attribute names for the columns in the View Object you created. When you drag items from the Data Control Palette, the data bindings are added here.
Adding Delete,
Commit and Rollback Buttons to Your Page
Most applications require that the user be given the opportunity
to confirm a delete action before a row is permanently deleted. In this tutorial
you do not have time to create a separate page. All you will do is add a delete,
commit and rollback button to the page.
To add operations buttons to the page, perform the following
steps:
1.
Return to the visual editor for the browseCustomers
page. Expand the CustomersView1 node in the Data Control
Palette. Expand Operations directly below the OrdersView2.
2.
Find the Delete operation and drag it
onto the page next to the submit button. Select ADF Command
Button from the context menu that appears.
3.
In the Data Control Palette, collapse the CustomersView1
node. There is an Operations node at the same level as CustomersView1.
Expand this node to expose the Commit and Rollback operations.
Drag each operation onto the page, alongside the Delete button, creating an ADF Command Button in each case.
4.
Run the page, to test the changes, just as you did earlier.
Select a record and delete it. Rollback the change.
The page you have just built only allows you to browse
and delete customers. In this section you create a web page that allows you
to create new records or update existing records. To
build a web page for updating a customer, perform the following steps:
1.
Create a JSP that corresponds to the editCustomers
icon on the page flow diagram.
Do this just as you did for the browseCustomers page:
Invoke the page flow diagram (faces-config.xml) and double-click the
/editCustomers icon.
Accept editCustomer.jsp as the page name.
Accept all other defaults offered by the wizard.
2.
Click the Data
ControlPalette.
Expand CustomerOrdersBusinessServicesDataControl,
select CustomersView1 and drag it
onto the page. Select Forms | ADF Form... from the
context menu.
3.
Check the Include Submit Button and
Click OK to accept all the form fields.
4.
Notice how the layout for for this page is quite different
from the previous one you created. You can see that the same data control
can be displayed in a variety of ways.
5.
In the next section you add navigation and enhance the
page UI, so you'll test the page thoroughly then. In the meantime, just
run the page to ensure that it works.
To run the page, perform the steps you did when you tested the browseCustomers
page, by selecting the editCustomers page, right-click
and select Run from the context menu.
Because of the way you constructed the business model, the application module takes care of master-detail coordination.
You may remember that when you used the wizard to create
view objects, you included the foreign key associations that became the view
links between the view objects.
When you built the application module you brought each view object into the
data model via the view link as a child of the previous view object. In other
words, the Orders view object in the application module is a child of Customers.
This means that only the orders for a selected customer are shown. Similarly,
the OrderItems view object in the application module is a child of Orders, so
only the order items for a selected order are shown.
Because the application module performs the master-detail coordination, there is nothing special needed to construct a master-detail web page. To build a web page showing a customer with associated orders, perform the following steps:
1.
Create a JSP that corresponds to the browseCustomerOrders
icon on the page flow diagram.
Do this just as you did for the browseCustomers page:
Invoke the page flow diagram (faces-config.xml) and double-click the
/browseCustomerOrders icon.
Accept /browseCustomerOrders.jsp as the page name.
Accept all other defaults offered by the wizard.
2.
In the Data
ControlPalette, expand CustomerOrdersBusinessServicesDataControl, CustomersView1
and OrdersView2 .
Select OrderItemsView1 and drag it onto the page.
Select Master-Details | ADF Master Form, Detail Table
from the context menu.
3.
In this step you change the titles of each of the sections
to Orders and Order Items.
Using the Property Inspector, select the text property OrdersView2
and replace the text with Orders. Change the title
OrderItemsView1 to Order Items for
the detail records. Notice the text in the Visual Editor is updated.
Note: If you are unable to select the Property Inspector for the text
property easily, go to the Structure window and select the af:panelHeader for each of the headers. You can then select and change the text property in the Property Inspector.
4.
In the master, Orders, section, you do not need to display
all the columns.
Delete the SalesRepId.
Ensure you delete the label and the data from the page. As you select
the SalesRepId column, look at the link in the Structure window, you
should have af:inputText selected. You can delete items
from the editor or from the Structure window, whichever you find easier.
5.
There are some columns that you need not display in the
detail section of this page. They are still required for the join syntax,
so do not delete them.
In the Order Items details section, select the column OrderId
and, using the Property Inspector, set the Rendered property to False.
As earlier in the tutorial, be sure to select the full column and not just
the column header. You can verify this by noting the selection in the
Structure window.
6.
Repeat this step for both instances of ProductId in the
Orders Items, setting the property Rendered to False
in each case. Your page should now look like the screen shot below.
7.
If you have time, move the ProductName
column next to the LineItemId.
Select the ProductName column. Notice this highlights
the column in the Structure window. Using the Structure window drag
the ProductName column upwards to below the LineItemId column.
8.
Run the page to test it, just as you tested the other
pages earlier; right-click the browseCustomerOrders
page and select Run from the context menu.
If you see only the labels, it is because you are displaying a customer
who has no orders. If this happens you can run the page for
a specific CustomerId. To do this, return to the CustomersView
in the OrderEntry | Model project. Double-click CustomersView in the model.queries package
to invoke the Properties dialog. Add Customers.CUSTOMER_ID
= 102 to the Where Clause of the SQL Statement. This
will not be necessary when you call the browseCustomerOrders from the
browseCustomers page in the next tutorial. Be sure to remove the restriction
when you have finished testing your page.
In this application, the browseCustomers page serves
as the starting point for users, who select the row they want to edit from that
page. The editCustomers page is used both for editing and for inserting rows.
In this section of the tutorial, you add buttons to
the browseCustomers page that raise events corresponding to the navigation case
that you already created in the page flow diagram.
To add an edit action to the Edit button, perform the following
steps:
1.
Open browseCustomers in the visual editor, select the
Submit button.
Using the Property Inspector, enter Edit Customers
as the value for the Text property. Select the Action property and,and using the dropdown list, select editCustomers.
Note: You can just type the Action property value into the field, however
it is important to note that the text in the Action property must match
the text for the From Outcome property for the Navigation
Case in the faces-config.xml file.
2.
Test the page by selecting the browseCustomers,
right-click and select Run from the context menu.
3.
In the browser, use the radio group to select a customer,
and click Edit Customers.
4.
Notice the new page has returned the CustomerId that
you selected on the browseCustomers page.
Adding
Show Orders button to launch a master-detail page
Now you add a Show Orders button on the page to call the browseCustomerOrders
page, showing the orders for the selected customer. To add a button with navigation
properties, perform the following steps:
1.
Ensure you have browseCustomers page open in the visual
editor. Switch to the Component Palette tab and select
ADF Faces Core from the dropdown list. (If the Component
Palette is not visible select View | Component Palette.)
2.
Select and drag the CommandButton onto
the page immediately next to the Delete button.
3.
Select the button you have just created.
In the Property Inspector, set the Text property to Show Orders.
Select the Action property, and using the dropdown list, select customerOrders.
As before, the text for the Action property must match that which you
entered for the navigation control in the page flow diagram.
Click Save All
or select File | Save All to save your work.
4.
Run the browseCustomers
page to test the changes.
Find and select CustomerId 101 (remember you can
re-order the CustomerId by clicking on the column header)
A radio group restricts the user to a finite set of
values that can be entered into a field, preventing any data errors. The Gender
field in the editCustomers page accepts only the values M and F, so is an ideal
candidate to convert to a radio button group.
To change the Gender field to a radio button group,
perform the following steps:
1.
Open the editCustomers
page in the visual editor.
2.
Select the Gender field
in the visual editor. Right-click and select Delete.
This deletes the text field for Gender.
3.
A quick reminder that each item you select in the Visual
Page editor is also selected in the Structure window. Select DateOfBirth
in the visual page editor; this highlights it in the Structure window.
Return to the Data Control Palette and expand CustomersView1.
Select Gender, drag it onto the Structure window
and drop it below the DateOfBirth. Select Single Selections
| ADF Select One Radio from the context menu when prompted.
4.
This opens the List Binding Editor. Select the
Fixed List option.
5.
Select Gender as the Base Data Source
Attribute.
Input M and F on separate lines under
Set of Values. Select Selection Required from the "No
Selection" Item droplist.
Click OK.
6.
The editCustomers page now includes a single radio icon.
7.
Test the page by running the editCustomers page. You
should see Gender displayed as a radio button group.
A checkbox restricts a user to a simple boolean choice.
The MaritalStatus field in the editCustomers page indicates a boolean state
of married or not married (single), so is an ideal candidate to convert to a
check box.
To change the MaritalStatus field to a check box, perform
the following steps:
1.
Return to the editCustomers
page in the visual editor.
Select the MaritalStatus field in the visual editor.
Right-click and select Delete.
2.
From the Data Control Palette
expand CustomersView1. Select MaritalStatus, drag onto
the Structure window and drop it just below the Gender radio item. Select
Single Selections | ADF Select Boolean Checkbox
from the context menu when prompted.
3.
This opens the Boolean Binding Editor.
4.
For Data Collection ensure that CustomersView1
is selected and MaritalStatus is selected for Attribute.
For the selected State Value and Unselected State Value, add married
and single and respectively, then click OK.
Click Save All
or select File | Save All to save your work.
5.
Test the page by running the editCustomers page and
note the Marital Status of the selected customer.
A drop down list is useful when a user has a list of
possible values to select from. In the case of IncomeLevel, there is a defined
set of possible values. As the values are cumbersome to type, it would be ideal
to select or update from a drop down list of values. In this case you create
a list based on hard coded values.
To change the IncomeLevel field to a drop down list,
perform the following steps:
1.
Return to the editCustomers
page in the visual editor. Delete the IncomeLevel field
in the visual editor as you did for each of the previous two fields.
From the Data Control Palette selectand expand
CustomersView1, select IncomeLevel and drag
onto the Structure window. Drop it just after the MaritalStatus and
select Single Selections | ADF Select One Choice
when prompted.
2.
This invokes the List Binding Editor. Select
Fixed List.
3.
Select IncomeLevel as the Base Data
Source Attribute.
Select Selection Required from the "No Selection"
Item: droplist.
For Set of Values input the following on separate lines:
When you created the editCustomers page, you did not
create any of the default buttons. In this part of the exercise you will now
add further buttons to enhance the functionality of the page, in particular
a Create button. For completeness you add Commit and Rollback buttons as you
did in the previous section.
To add a Create button to the page, perform the following
steps:
1.
Return to the editCustomers
page in the visual editor.
From the Data Control Palette select andexpand
CustomersView1. Expand the Operations node
which appears as a child of CustomerView1. Select the Create operation.
2.
Drag the Create operation onto the page in front of the
Submit button. Select ADF Command Button from the context
menu when prompted.
3.
Return to the Data Control Palette collapse CustomersView1
and expand the Operations node which appears at the
same level as CustomersView1.
4.
Select and drag the Commit operation
onto the page, just after the Submit button. Select ADF Command
Button from the context menu when prompted.
5.
Repeat this step for the Rollback button placing it after
the Commit Button.
Click Save All
to save your work.
6.
Your users prefer "Apply Changes" to "Submit",
so change the text of the Submit button. To do this, select the Submit
button and change the Text property to Apply Changes
in the Property Inspector.
7.
Test the application by running the editCustomers page.
Change the name of an employee and click Rollback to
undo the change.
Create a new customer, click Apply Changes to submit
the change to the database. Click Commit to update
the record in the database.
You have now enhanced the editCustomers page by adding
new controls and buttons. Once the user has finished using this screen, you
want them to be able to navigate back to the browseCustomers page. This can
be done by adding a Cancel button and also by adding a navigation action to
the Commit button so that it commits and then navigates back.
To enable navigation back to the browseCustomers page,
perform the following steps:
1.
From earlier sections in this workshop, you may recall
that the value for the Action property for a button must match the text
in the Navigation Cases in the page flow.
Open up the faces-config.xml file, the page flow diagram. (Right-click
ViewController and select Open
JSF Navigation from the context menu. )
Verify you have cancel and commit
navigation flows from the editCustomer page back to the browseCustomers
page.
2.
Return to the editCustomers
page in the visual editor. Ensure that ADF Faces Core
is selected in the dropdown list of the Component Palette.
3.
Select and drag the Command Button
onto the page immediately next to the Rollback button.
4.
Ensure the new button is selected. In the Property Inspector,
enter Cancel as the value for the Text property.
Select the Action property and choose cancel from
the dropdown list.
5.
Select the Commit (Apply Changes) button
in the visual editor and verify that the value for the Action property
in the Property Inspector matches your navigation flow. The values in
the dropdown list is the value from the navigation flow. In order to
commit the data and return to the browseCustomers page, you must select
the flow value.
6.
Test the application by running the browseCustomers page from thepage flow diagram.
Select a customer and click Edit Customers. Change the name of an employee and click Cancel. Youreturn to the customers page and no changes have been made.
Edit a customer again, and this time click Apply Changes and then click Commit. The data is committed and control is returned to the customers page.
You may have noticed that when you edit a customer,
the CustomerID is editable. Generally speaking, you only want this field editable
for new records. This can be set within the model of our application and the
user interface will automatically reflect this.
To make CustomerID editable only for new records, perform
the following steps:
1.
In the OrderEntry application you have been
working on expand the Model project so you can see
the Entity Objects.
2.
Double-click on the Customers Entity
Object to display the Entity Object Editor.
3.
Expand the attributes tree and select CustomerId
4.
Set the Updatable field to While New,
click OK.
Click Save All
or select File | Save All to save your work.
5.
Test the application by running the browseCustomers
page.
Select a customer and then click Edit Customers.
In the editCustomers page, note that the CustomerID field is non editable.
6.
Click Create to add a new customer record.
Note that the CustomerID is editable for a new record.
In this tutorial, you have built some of the web pages in
the application and added data-aware components to them. Because of the data
model that you constructed in a previous tutorial, it was easy to build a master-detail
web page. However, the pages have limited functionality at this point.
Then, you enhanced the user interface. You
learned how to link up actions to navigation events as well as how to enhance
the user interface using controls such as check boxes, radio groups and drop
down lists.
You have now also completed building a small web application
that allows you to edit, update and commit changes to the database. You can
also navigate easily between pages, passing parameters for particular records
selected.
Bookmark
Place the cursor over this icon to load and view all
the screenshots for this tutorial. (Caution: Because this action loads all screenshots
simultaneously, response time may be slow depending on your Internet connection.)
or select File | Save All to save your work. 
to shuttle them to the Selected Libraries list.