If you want to jump right in and build a page flow now, see the introductory tutorial Getting Started: Web Applications or the more advanced tutorial Tutorial: Page Flow. If you want to see samples that demonstrate common page flow and JSP features, see Page Flow and JSP Samples.
Why Use Page Flows?
By using page flows, you can avoid making the typical mistakes that often happen during web application development, by separating presentation, business logic implementation, and navigational control. In many web applications, web developers using JSP (or any of the other dynamic web languages such as ASP or CFM) combine presentation and business logic in their web pages.
As these applications grow in complexity and are subject to continual change, this practice leads to expensive, time-consuming maintenance problems, caused by:
Page flows allow you to separate the user interface code from navigational control and other business logic. User interface code can be placed where it belongs, in the JSP files. Navigational control can be implemented easily in a page flow's single controller file, which is the nerve center of your web application. A controller file is a special Java file that uses a JPF file extension. Business logic can be implemented in the page controller file, or in Java controls that you call from JPF files.
The separation of presentation and business logic offers a big advantage to development teams. For example, you can make site navigation updates in a single JPF file, instead of having to search through many JSP files and make multiple updates. In WebLogic Workshop you can as easily navigate between page flows as between individual JSP pages. This allows you to group related web pages under one page flow, and create functionally modular web components. This approach to organizing the entities that comprise web applications makes it much easier to maintain and enhance web applications by minimizing the number of files that have to be updated to implement changes, and lowers the cost of maintaining and enhancing applications.
Another advantage of page flows is that an instance of the page flow controller class is kept alive on a per-user-session basis while the user is navigating within the scope of the page flow. This instance ends when the user exits from the page flow. You can use instance member variables in page flow classes to hold user session state.
For more information about the advantages of page flows, especially in comparison to "pure Struts" applications, see Advantages of Using Page Flows.
How Does a Page Flow Work?
A page flow is a Java class, called the "controller" class, that controls the behavior of a web application through the use of specially designed annotations and methods. The directory that contains the controller class also includes the JavaServer Pages (JSPs) used in the page flow. For a JSP to be considered part of a page flow, it must reside within the page flow directory. The JSP files use special tags which help bind to data and business logic actions. The action methods in the controller file implement code that can result in site navigation, passing data, or invoking back-end business logic via controls. Significantly, the business logic in the controller class is separate from the presentation code defined in the JSP files.
The overall purpose of a page flow is to provide you with an easy-to-use framework for building dynamic, sophisticated web applications. WebLogic Workshop provides graphical and code-level tools to simplify the development cycle. While page flows give you access to advanced features of J2EE, you do not have to be a J2EE expert to quickly develop and deploy Java-based applications built on page flows. Wizards can be used to create different types of page flows, generating the Java and JSP files that serve as a starting point for your work. Graphical tools let you draw the relationships between web components in a controller's Flow View. In Source View, syntax completion, validation, and other programmer's aids reduce the amount of work required to get your application running.
Note: WebLogic Workshop's web application functionality is built on Struts, which is an open-source framework for building web applications in a J2EE environment.
Components of the Page Flow Programming Model
Page flows implement user interface control logic, and contain:
-
Action Methods
-
Form Beans
-
Forward Objects
- The <netui...> Tag Library
Action Methods
In the controller class, action methods are methods that are annotated with a @jpf:action tag.
/**
* @jpf:action
* @jpf:forward name="success" path="page_A.jsp"
*/
protected Forward begin()
{
return new Forward( "success" );
}
Action methods can perform several functions. They can (1) implement navigation decisions, (2) move data into and out of JSP pages, and (3) invoke back-end business logic via calls to controls.
Form Beans are Java data structures that correspond to HTML forms. When a user submits data from an HTML form, the data is stored in a Form Bean instance. Once the data is stored in a Form Bean instance, the data is available for processing by the action methods in the controller file. Form Bean instances (containing submitted data) are typically passed as parameters to action methods.
Form Beans are simple Java classes contained within the controller file. They consist of some number of fields with setter and getter methods associated with those fields. Below is a Form Bean with one field, the String name, and setter and getter methods for that field. Form Bean must extend the class com.bea.wlw.netui.pageflow.FormData.
Forward objects are returned by action methods. They can be used to control navigation and pass data throughout the application.
The <netui> tag library contains JSP tags specifically designed to work with the controller class. Tags in the library all begin with the prefixes "netui", "netui-databinding", and "netui-template". Some of these tags perform much like familiar HTML tags, while others perform function particular to page flow web applications. The most important feature of the tag library is its ability to "data bind" to data in the controller file. Data binding allows the JSP pages to both read from and write to Java code in the controller class. This is accomplished without placing any Java code on the JSP pages, greatly enhancing the separation of data presentation and data processing.
Flow, Action, and Source Views
In the WebLogic Workshop IDE, you can switch between the Flow View, Action View, and Source View to create, modify, and view page flow components. Let's start with a simple page flow to understand the basic icons you will encounter in the Flow View, and to find out how the Flow View relates to methods and object in the Source View. In the example, navigation control is forwarded from one JSP to another. You can find this example in WebLogic Workshop at:
<BEA_HOME>\weblogic81\samples\workshop\SamplesApp\WebApp\navigation\simpleNavigation\
Here is the Flow View diagram that we created for this page flow in WebLogic Workshop:
All page flow controller classes have a begin action method to define what happens each time this page flow is first navigated to. For this page flow, page_A.jsp is the first page that the user will see when the page flow's URL is accessed. The begin action is shown with a blue and green circular icon:
All other actions are represented by a blue circular icon in the Flow View:
Each JSP file that resides in a page flow's directory is shown on the Flow View, and is represented by a rectangular icon with a folded upper-right corner:
An arrow from a JSP page icon to an action icon indicates that the action can be invoked from the JSP page. For example, if there is a link on the JSP that calls the action method, this is depicted in Flow View by the following arrow.
An arrow from an action to a JSP page indicates that the execution of the action will load the target JSP page into the browser. For example:
The name of each action and JSP page is shown below the icon. The name on the arrow next to the action's circular icon corresponds to the logical name of the Forward object that is returned by the action method. The Forward object's role will be clearer when we look at the source code below.
In the WebLogic Workshop IDE, use the tabs at the bottom of the main window to switch between the graphical views and source view. When a page flow is open, its graphical representation is displayed in the Flow View window. You can switch to the page flow's graphical Action View or to its code-level Source View:
The Action View allows you to focus on a smaller portion of the page flow, for instance to examine a particular action and its form bean. The Source View is where you can customize the generated code and add business logic, or call controls that implement business logic.
Let's turn to a few examples that demonstrate some of the key features of navigational control and data processing.
Navigation: a Simple Example
As shown in the Flow View diagram, the page flow class defines an action method named toPageB. This action can be invoked by a link on the JSP page page_A.jsp.
page_A.jsp
<%@ taglib uri="netui-tags-html.tld" prefix="netui"%>
...
<netui:anchor action="toPageB">Link to page_B.jsp</netui:anchor>
A special JSP tag library named netui-tags-html.tld is referenced. WebLogic Workshop provides this tag library and several others to help you develop dynamic web applications. The <netui:anchor...> tag used here is simply invoking an action (toPageB) with a hyperlink. (For more information about the page flow tag library, see Designing User Interfaces in JSPs.)
In the controller file SimpleNavigationController.jpf, the toPageB action method is defined as follows:
SimpleNavigationController.jpf
import com.bea.wlw.netui.pageflow.Forward;
...
/**
* @jpf:action
* @jpf:forward name="success" path="page_B.jsp"
*/
public Forward toPageB()
{
return new Forward( "success" );
}
When the link on page_A.jsp is clicked, the page flow runtime detects the action and runs the toPageB action method. This action method is coded to return a Forward object which passes the parameter "success". (Notice that this name "success" matches the name on the corresponding action arrow in Flow View.)
Look at the two @jpf annotations that appear on the lines above this action method. These annotations are enclosed in Javadoc comments. The @jpf:action tag indicates that the toPageB method is an action method. The @jpf:forward tag describes the behavior of that method.
Putting it all together, a Forward object is returned by an action method. The Forward object passes the string "success", indicating that it should behave according to the directions encoded in the annotation @jpf:forward name="success". That annotation's path attribute has the value "page_B.jsp", which causes the page flow controller to load page_B.jsp into the browser.
The following diagram summarizes the flow in the example:
To change the navigation target of this action method, simply change the value of the path attribute. For example, if you want this action method to navigate to page_C.jsp, you would make the following change to the controller file (no change to the JSP page is necessary).
/**
* @jpf:action
* @jpf:forward name="success" path="page_C.jsp"
*/
public Forward toPageB()
{
return new Forward( "success" );
}
As you will see in later sections, the WebLogic Workshop IDE generates this code for you when you create a new page flow or JSP file from the graphical view. This code generation and subsequent validation of your changes saves you considerable time.
Submitting Data: A Simple Example
Suppose you want to your web application to collect data from users and then process that data in some way. The following example demonstrates how to set up a data submission process using page flows. The sample code referred to in this example can be found at:
<BEA_HOME>\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\
Submitting data is a two step process: (1) the data submitted from a JSP page is loaded into a Form Bean instance and (2) the Form Bean instance is passed to an action method for processing.
Form Beans are simple Java classes with fields and setter and getter methods for accessing those fields. Form Beans classes are contained within the controller file. In most cases, Form Beans are designed to accept data submitted from JSP forms. For example, if a JSP page has input elements for name, eye_color, and height, then the Form Bean will have corresponding fields for name, eye_color, and height. The following example Form Bean can be found in the controller file SimpleSubmitController.jpf. It contains one field, name, and setter and getter methods for that field.
SimpleSubmitController.jpf
public class SimpleSubmitController extends PageFlowController
{
...
public static class SubmitNameForm extends FormData
{
private String name;
public void setName(String name)
{
this.name = name;
}
public String getName()
{
return this.name;
}
}
}
The input elements on the JSP page are said to be "data bound" to the fields in the Form Bean. Data binding allows the the data submitted from the JSP page to be loaded into the Form Bean instance. For example, the input element on index.jsp contains a data binding expression that refers to the name field of the Form Bean: {actionForm.name}. The expression "actionForm" refers to the Form Bean SubmitNameForm, the property ".name" refers to the name field of the Form Bean. For detailed information about data binding see Using Data Binding in Page Flows.
index.jsp
<netui:form action="SubmitName">
Name: <netui:textBox dataSource="{actionForm.name}"/>
....
</netui:form>
Finally the Form Bean instance (carrying the submitted data) is passed to the action method for processing.
/**
* @jpf:action
* @jpf:forward name="success" path="showName.jsp"
*/
protected Forward SubmitName(SubmitNameForm form)
{
//
// The data is processed here
//
return new Forward("success");
}
The submitted data can be accessed by calling the getter methods on the Form Bean.
/**
* @jpf:action
* @jpf:forward name="success" path="showName.jsp"
*/
protected Forward SubmitName(SubmitNameForm form)
{
if( form.getName() != null )
// do something here
else
// do something else here
return new Forward("success");
}
By default the Form Bean instance that is passed to the action method exists only as long as the HTTP request. This is called a "request-scoped Form Bean". When the HTTP request is destroyed, the Form Bean instance, along with the user submitted data, is destroyed. As an alternative, you can use a Page Flow-scoped Form Bean, which has a longer life cycle. For details see Form Bean Scopings.
Displaying Data: A Simple Example
Suppose that once you have collected data, you want to display it back to the user. The following example shows how to use data binding to display data to the user. The sample code referred to can be found at:
<BEA_HOME>\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\
Displaying data using data binding requires that (1) the data is located somewhere where it can accessed by the JSP page and (2) the JSP page uses a data binding expression to retrieve the data from that location.
Notice the syntax of data binding expression on the JSP page. (1) It is framed by curley braces, (2) it begins with a data binding context, in this case the request context, and (3) the context is followed by an attribute, in this case "name".
In the following example, an action method places data on the name attribute of the request object.
SimpleSubmitController.jpf
/**
* @jpf:action
* @jpf:forward name="success" path="showName.jsp"
*/
protected Forward SubmitName(SubmitNameForm form)
{
getRequest().setAttribute("name", form.getName());
return new Forward("success");
}
After the data has been located on the name attribute of the request object, it is displayed on a JSP page using a data binding expression.
showName.jsp
Here is the data you submitted: <netui:label value="{request.name}" />
Note that the request object has a relatively short life-cycle. When the user makes a new request, by navigating to a new JSP page or invoking another action method, the current request object is destroyed along with the data it contains. If your application requires the data to be more persistent, then you could use a different data binding context, for example the session object or a Page Flow-scoped Form Bean, which both have longer life-cycles. For detailed information about the different data binding contexts available, see Using Data Binding in Page Flows.