You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by ri...@apache.org on 2005/11/16 22:29:12 UTC
svn commit: r345129 -
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tutorial_pageflow.xml
Author: rich
Date: Wed Nov 16 13:29:09 2005
New Revision: 345129
URL: http://svn.apache.org/viewcvs?rev=345129&view=rev
Log:
Made a number of changes to the NetUI tutorial:
- Fix for http://issues.apache.org/jira/browse/BEEHIVE-963 : pageflow_tutorial, form validation, application bug
- In the Validation section, moved declarative validation annotations to the form bean, away from the action. This is the more important case, and it's simpler.
- Updated to reflect the new project model (web/src/build).
- Changed the webapp name from pageflow_tutorial to netui-tutorial.
- Made the initial page flow one you create, in a directory, rather than an edit of the default one at the root of the webapp.
- Removed Shared Flow from all but the Shared Flow section -- it doesn't need to exist everywhere.
- Changed to use action outputs instead of request attributes.
- Other minor fixes.
tests: build.release in docs/forrest (WinXP)
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tutorial_pageflow.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tutorial_pageflow.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tutorial_pageflow.xml?rev=345129&r1=345128&r2=345129&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tutorial_pageflow.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tutorial_pageflow.xml Wed Nov 16 13:29:09 2005
@@ -7,14 +7,23 @@
<body>
<section id="intro">
<title>Introduction</title>
- <p>The NetUI tutorial is provided as a way to become familiar with NetUI's Page Flow controllers and JSP tags. The tutorial
- walks through creating, building, and deploying a sample project page flow that uses JavaBeans to submit data from a browser
- to the server.</p>
+ <p>
+ The NetUI tutorial is provided as a way to become familiar with NetUI's Page Flow controllers and JSP
+ tags. The tutorial walks through creating, building, and deploying a sample project page flow that
+ submits data from a browser to the server.
+ </p>
<section id="goals">
<title>Tutorial Goals</title>
<ul>
<li>How to create a basic NetUI web application.</li>
<li>
+ How to perform simple user navigation with the
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">
+ <code>@Jpf.SimpleAction</code>
+ </a>
+ annotation.
+ </li>
+ <li>
How to coordinate user navigation with the
<a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
<code>@Jpf.Forward</code>
@@ -48,7 +57,7 @@
</section>
</section>
<section id="setup">
- <title>Step 1: Setup a Beehive-enabled Web Application</title>
+ <title>Step 1: Set up a Beehive-enabled Web Application</title>
<section id="setup_shell">
<title>Set Shell Variables</title>
<p>Complete all of the necessary and optional steps in the following topic: <a class="fork" href="site:setup">Beehive Installation and Setup</a></p>
@@ -65,13 +74,13 @@
<li>Create a directory <code>/beehive_projects</code> (on Windows, this would be <code>C:\beehive_projects</code>).</li>
<li>Run the Ant target to create a new NetUI project:
<code>ant -f <beehive-root>/beehive-imports.xml</code> and provide a fully-qualified web project root directory
- named <code>pageflow_tutorial</code>. Note, <code><beehive-root></code> is the directory that contains a
+ named <code>netui-tutorial</code>. Note, <code><beehive-root></code> is the directory that contains a
Beehive distribution; a typical value might be <code>/apache/apache-beehive-1.0</code>.</li>
<li>Before continuing, confirm that the following directory structure exists:</li>
</ol>
<source>
beehive_projects/
- pageflow_tutorial/
+ netui-tutorial/
web/
Controller.java
index.jsp
@@ -81,9 +90,9 @@
build.xml
</source>
<p>
- Note, this directory structure is just an example; you are free to put the <code>pageflow_tutorial</code>
- directory anywhere on disk. In the remainder of this tutorial, the directory <code>beehive_projects/pageflow_tutorial</code>
- will simply be referred to as <code>pageflow_tutorial</code>.
+ Note, this directory structure is just an example; you are free to put the <code>netui-tutorial</code>
+ directory anywhere on disk. In the remainder of this tutorial, the directory <code>beehive_projects/netui-tutorial</code>
+ will simply be referred to as <code>netui-tutorial</code>.
</p>
</section>
<section id="setup_configure_properties">
@@ -92,23 +101,23 @@
The <code>build.properties</code> file contains several project-related properties that must
be set in order to build the web application. Specifically, the paths to your Beehive distribution and
to the JSP / Servlet API JARs for your application container must be set. The following steps will set these properties
- for the <code>pageflow_tutorial</code> webapp.
+ for the <code>netui-tutorial</code> webapp.
</p>
<ol>
- <li>Open the file <code>pageflow_tutorial/build.properties</code> in a text editor.</li>
- <li>Edit the <code>beehive.home</code> property so it points to the top-level folder of your Beehive distribution.</li>
- <li>Edit the <code>context.path</code> to use the value <code>pageflow_tutorial</code>.</li>
+ <li>Open the file <code>netui-tutorial/build.properties</code> in a text editor.</li>
+ <li>Edit the <code>beehive.home</code> property so it points to the top-level directory of your Beehive distribution.</li>
+ <li>Edit the <code>context.path</code> to use the value <code>netui-tutorial</code>.</li>
</ol>
<note>
The <code>context.path</code> property determines both (1) the name of the application WAR file and (2) the application URL.
<br/><br/>
- If <code>context.path=pageflow_tutorial</code>, then the following WAR file will be produced:
+ If <code>context.path=netui-tutorial</code>, then the following WAR file will be produced:
<br/><br/>
- <strong><code>pageflow_tutorial</code></strong><code>.war</code>
+ <strong><code>netui-tutorial</code></strong><code>.war</code>
<br/><br/>
and the following URL will invoke the web application:
<br/><br/>
- <code>http://someapplicationserver/</code><strong><code>pageflow_tutorial</code></strong>
+ <code>http://<some server>/</code><strong><code>netui-tutorial</code></strong>
</note>
<p>For example, if your Beehive distribution is located in <code>/apache/apache-beehive-1.0</code>,
then your <code>build.properties</code> file would appear as follows.</p>
@@ -118,7 +127,7 @@
servlet-api.jar=${os.CATALINA_HOME}/common/lib/servlet-api.jar
jsp-api.jar=${os.CATALINA_HOME}/common/lib/jsp-api.jar
-context.path=<strong>pageflow_tutorial</strong></source>
+context.path=<strong>netui-tutorial</strong></source>
<note>Properties files should use the '/' character to separate drive, directory, and file names.</note>
<p>
If you are using an application container other than Tomcat, be sure to set the <code>servlet-api.jar</code> and
@@ -135,9 +144,9 @@
<section id="setup_urls">
<title>Using URLs in the Examples</title>
<p>
- In the Beehive tutorials, you will often encounter URLs like <code>http://localhost:8080/pageflow_tutorial/Controller.jpf</code>.
+ In the Beehive tutorials, you will often encounter URLs like <code>http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</code>.
When you see these URLs, they are meant to be accessed via your web browser to demonstrate functionality built in the
- tutorial. These URLs are setup to run on Tomcat, so if you are unable to run these URLs, be sure that they are appropriate
+ tutorial. These URLs are set up to run on Tomcat, so if you are unable to run these URLs, be sure that they are appropriate
for your application server. Specifically, check the port numbers to make sure that your server is running on the
referenced port.
</p>
@@ -148,113 +157,81 @@
<section id="create_overview">
<title>Overview</title>
<p>
- In this step you will create a controller class and a JSP. These are the basic files in
- a Beehive NetUI web application. Each page flow contains one controller class and any
- number of JSPs. A controller class is a Java class that
- controls how your web application functions and what it does. The methods in the
- Controller
- file determine all of the major features of a web application: how users navigate from page
- to page, how user requests are handled, and how the web application accesses back-end
- resources. The JSPs determine what a visitor to the web sees in the browser.
+ In this step you will create a controller class and a JSP. These are the basic files in
+ a Beehive NetUI web application. Each page flow contains one controller class and any
+ number of pages -- JSPs in this case. A controller class is a Java class that
+ controls how your web application functions and what it does. The methods and annotations in the
+ controller class determine how users navigate from page
+ to page, how user requests are handled, and how the web application accesses back-end
+ resources. The JSPs determine what a visitor to the web application sees in the browser.
</p>
<p>
- In terms of the Model-View-Controller paradigm for web applications, the Controller.java
- file is the Controller (naturally) and the JSPs are the View. The web application's
- Model in this tutorial is very simple: it consists of three fields that represent the
- user's name, age and selected sport activity.
- <!--[tbd: more, explain]-->
+ In terms of the Model-View-Controller paradigm for web applications, the Controller.java
+ file is the Controller (naturally) and the JSPs are the View. The web application's
+ Model in this tutorial is very simple: it consists of a JavaBean with three fields that represent the
+ user's name, age and selected sport activity.
+ <!--[tbd: more, explain]-->
</p>
<p>
- Controller classes contain Action methods. An Action method may do something simple, such
- as forward a user from one JSP to another; or it may do a complex set of tasks, such
- as receive user input from a JSP, calculate and/or retrieve other data based on the
- user input, and forward the user to a JSP where the results are displayed.
- <!--[tbd: diagram, etc.]-->
+ Controller classes contain <strong>actions</strong>, which are methods or annotations. An action may do
+ something simple, such as forward a user from one JSP to another; or it may do a complex set of tasks,
+ such as receive user input from a JSP, interact with back-end resources based on the
+ user input, and forward the user to a JSP where the results are displayed.
+ <!--[tbd: diagram, etc.]-->
</p>
<p>
- The controller class in this step contains one simple Action method. This
- simple navigational Action method forwards users to the <code>index.jsp</code> page. In the next
- step, you will create a more complex Action method.
+ The controller class in this step contains one action. This simple navigational action forwards users
+ to the <code>index.jsp</code> page. In the next step, you will create a more complex action.
</p>
</section>
<section id="create_examine">
- <title>Examine the Controller.java and index.jsp Files</title>
- <p>There are no edits to make in this step. The point of this step is
- to learn about the code you are about to run.</p>
- <p>Open the file <code>pageflow_tutorial/web/Controller.java</code>.
- </p>
- <p>The controller class is an ordinary Java class with methods and annotations.</p>
- <p>A Page Flow controller class must extend
- <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/PageFlowController.html">
- <code>PageFlowController</code>
- </a>
- and be decorated by the annotation
- <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
- <code>@Jpf.Controller</code></a>.
+ <title>Create the Page Flow Files</title>
+ <p>
+ You will create two files in a new page flow: <code>Controller.java</code> and <code>index.jsp</code>.
+ First, create a directory called <code>myFlow</code> under the <code>web</code> directory. Then add
+ the following page flow controller class:
</p>
- <p>The <code>onCreate()</code> method is executed whenever the Controller class is first
- instantiated. The <code>onDestroy()</code> method is executed when the Controller
- class is destroyed.</p>
- <p>After the <code>onCreate()</code> method is run, the NetUI runtime
- searches for (and runs) a method or action named <code>begin</code>.
- In this controller class, there is a simple action named <code>begin</code>:
- </p>
- <source>@Jpf.SimpleAction(name="begin", path="index.jsp")</source>
- <p>The begin action <em>could</em> have been expressed using method syntax: </p>
+ <p><strong><code>web/myFlow/Controller.java</code></strong></p>
<source>
-@Jpf.Action(
- forwards = {
- @Jpf.Forward(name="success", path="index.jsp")
- }
-)
-public Forward begin() {
- return new Forward("success");
-}
-</source>
- <p>We have used the Simple Action syntax for the sake of syntactical simplicity. The Simple Action will forward the user to the JSP, index.jsp.</p>
- <p>The Controller class is instantiated when a user calls it via the URL:</p>
- <source>http://localhost:8080/pageflow_tutorial/Controller.jpf</source>
- <p>The URL above means this: "Run the <code>begin</code> action of the <code>Controller.java</code> class
- in the directory <code>pageflow_tutorial</code>."</p>
- <p><strong><code>Controller.java</code></strong></p>
- <source>
-import javax.servlet.http.HttpSession;
+package myFlow;
-import org.apache.beehive.netui.pageflow.Forward;
-import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.PageFlowController;
@Jpf.Controller(
simpleActions={
@Jpf.SimpleAction(name="begin", path="index.jsp")
- },
- sharedFlowRefs={
- @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class)
}
)
public class Controller
extends PageFlowController
{
- @Jpf.SharedFlowField(name="shared")
- private shared.SharedFlow sharedFlow;
-
- /**
- * Callback that is invoked when this controller instance is created.
- */
- protected void onCreate()
- {
- }
-
- /**
- * Callback that is invoked when this controller instance is destroyed.
- */
- protected void onDestroy(HttpSession session)
- {
- }
}</source>
- <p>Open the file <code>pageflow_tutorial/web/index.jsp</code>.
- </p>
- <p><strong><code>index.jsp</code></strong></p>
+ <note>
+ Here we have put our controller class directly in the web content directory, alongside its pages.
+ If you would rather not do this (or if you can't because your IDE doesn't like it), you can put
+ the controller class in a <strong>parallel source directory</strong>. In this case, you would put
+ it in <code>src/myFlow</code>, and NetUI will assume it goes with pages that are in
+ <code>web/myFlow</code>.
+ </note>
+ <p>Every Page Flow controller class must extend
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/PageFlowController.html">
+ <code>PageFlowController</code>
+ </a>
+ and be decorated by the annotation
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
+ <code>@Jpf.Controller</code></a>.
+ The class you created is the simplest controller possible; it has a single <code>begin</code> action that
+ forwards to <code>index.jsp</code>.
+ </p>
+ <p>The controller class is activated when a user hits it via the URL:</p>
+ <source>http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</source>
+ <p>The URL above means this: "Run the <code>begin</code> action of the <code>Controller</code> class
+ in the <code>myFlow</code> directory of the <code>netui-tutorial</code> web application."</p>
+ <p>
+ Now, create the <code>index.jsp</code> that will be shown when you hit the page flow:
+ </p>
+ <p><strong><code>web/myFlow/index.jsp</code></strong></p>
<source><![CDATA[
<%@ page language="java" contentType="text/html;charset=UTF-8"%>
<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
@@ -278,7 +255,7 @@
<section id="create_build_deploy">
<title>Compile and Deploy the Web Application</title>
<p>You are now ready to compile the page flow and deploy it to Tomcat.</p>
- <p>The following Ant command assumes that you are in the <code>pageflow_tutorial/</code> directory. At the command prompt, enter:</p>
+ <p>The following Ant command assumes that you are in the <code>netui-tutorial/</code> directory. At the command prompt, enter:</p>
<source>
ant clean build war
</source>
@@ -288,7 +265,7 @@
directory.</p>
<p>On Windows:</p>
<source>
-copy pageflow_tutorial.war %CATALINA_HOME%\webapps /Y</source>
+copy netui-tutorial.war %CATALINA_HOME%\webapps /Y</source>
<note>
On Windows, there are file-locking issues that Tomcat versions 5.5.x and above are sensitive to.
In particular, any web application that uses Struts will <strong>fail to redeploy</strong> if you
@@ -298,7 +275,7 @@
you can work around it with the <code>antiResourceLocking</code> option in Tomcat. Just add a file
called <code>context.xml</code> in a directory called <code>META-INF</code> inside the
<code>web</code> directory before building (so it will end up as <code>META-INF/context.xml</code>
- in your <code>controls_tutorial.war</code>):
+ in your <code>netui-tutorial.war</code>):
<br/>
<br/>
<code> <?xml version="1.0" encoding="UTF-8"?></code><br/>
@@ -307,7 +284,7 @@
</note>
<p>Everywhere else:</p>
<source>
-cp pageflow_tutorial.war $CATALINA_HOME/webapps
+cp netui-tutorial.war $CATALINA_HOME/webapps
</source>
<p>If you are asked to overwrite the old WAR file, enter 'yes'. Note, when doing redeployment, you may have to wait a few seconds
for Tomcat to redeploy the WAR file. Once deployment or redeployment has completed, the webapp can be accessed through a browser.</p>
@@ -316,7 +293,7 @@
<section id="create_test">
<title>Test the NetUI Web Application</title>
<p>Visit the following address:</p>
- <p><a class="fork" href="http://localhost:8080/pageflow_tutorial/Controller.jpf">http://localhost:8080/pageflow_tutorial/Controller.jpf</a></p>
+ <p><a class="fork" href="http://localhost:8080/netui-tutorial/myFlow/Controller.jpf">http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</a></p>
<p>You will be directed to the <code>index.jsp</code> page.</p>
</section>
</section>
@@ -324,9 +301,8 @@
<title>Step 3: Navigation</title>
<section id="navigate_create_page">
<title>Create a Destination JSP</title>
- <p>In the directory <code>pageflow_tutorial/web</code>, create a file named <code>page2.jsp</code>.</p>
- <p>Edit page2.jsp so it appears as follows.</p>
- <p><strong><code>page2.jsp</code></strong></p>
+ <p>In the directory <code>web/myFlow</code>, create a file named <code>page2.jsp</code>:</p>
+ <p><strong><code>web/myFlow/page2.jsp</code></strong></p>
<source><![CDATA[
<%@ page language="java" contentType="text/html;charset=UTF-8"%>
<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
@@ -346,8 +322,11 @@
</section>
<section id="navigate_create_link">
<title>Create a Link to the Destination Page</title>
- <p>In this step you will create a link from the JSP, <code>index.jsp</code> to a new Simple Action that you will add to the controller class.</p>
- <p>Open the file <code>pageflow_tutorial/web/index.jsp</code>.</p>
+ <p>
+ In this step you will create a link from the JSP, <code>index.jsp</code> to a new Simple Action that
+ you will add to the controller class. The new action will forward to <code>page2.jsp</code>.
+ </p>
+ <p>Open the file <code>web/myFlow/index.jsp</code>.</p>
<p>Edit <code>index.jsp</code> so it appears as follows. The code to add appears in bold type.</p>
<p><strong><code>index.jsp</code></strong></p>
<source>
@@ -373,31 +352,24 @@
</section>
<section id="navigate_add_action">
<title>Add a Simple Action to Handle the Link</title>
- <p>Open the file <code>pageflow_tutorial/web/Controller.java</code>.</p>
+ <p>Open the file <code>web/myFlow/Controller.java</code>.</p>
<p>Edit <code>Controller.java</code> so it appears as follows. Don't forget the comma after the first <code>Jpf.SimpleAction(...)</code> element!</p>
<p><strong><code>Controller.java</code></strong></p>
<source>
-import javax.servlet.http.HttpSession;
+package myFlow;
-...
-
-import org.apache.beehive.netui.pageflow.Forward;
-import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.PageFlowController;
@Jpf.Controller(
simpleActions={
@Jpf.SimpleAction(name="begin", path="index.jsp")<strong>,
@Jpf.SimpleAction(name="toPage2", path="page2.jsp")</strong>
- },
- sharedFlowRefs={
- @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class)
}
)
public class Controller
extends PageFlowController
{
- ...
}</source>
<p>Save <code>Controller.java</code>.</p>
</section>
@@ -411,19 +383,20 @@
<title>Test the NetUI Web Application</title>
<p>Visit the following link:
</p>
- <p><a class="fork" href="http://localhost:8080/pageflow_tutorial/Controller.jpf">http://localhost:8080/pageflow_tutorial/Controller.jpf</a></p>
+ <p><a class="fork" href="http://localhost:8080/netui-tutorial/myFlow/Controller.jpf">http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</a></p>
<p>You will be directed to the <code>index.jsp</code> page.</p>
- <p>Click the link.</p>
- <p>You will be directed to page2.jsp.</p>
+ <p>Click the link. You will be directed to page2.jsp.</p>
</section>
</section>
<section id="forms">
<title>Step 4: Submitting Data</title>
<section id="forms_create">
<title>Create a Submission Form</title>
- <p>This step illustrates the use of custom tags to render an HTML form tag and link it to an Action.
- In a later step, the new Action will be added to the controller class to handle the data submission.</p>
- <p>Edit the file <code>pageflow_tutorial/web/page2.jsp</code> so it appears as follows.</p>
+ <p>
+ This step illustrates the use of NetUI tags to render an HTML form tag and link it to a Page Flow action.
+ In a later step, the new action (<code>processData</code>) will be added to the controller class to handle the data submission.
+ </p>
+ <p>Edit the file <code>web/myFlow/page2.jsp</code> so it appears as follows.</p>
<p><strong><code>page2.jsp</code></strong></p>
<source>
<%@ page language="java" contentType="text/html;charset=UTF-8"%>
@@ -452,10 +425,13 @@
</section>
<section id="forms_create_formbean">
<title>Create a Server Side Representation of the Submission Form (a.k.a. Create a Form Bean)</title>
- <p>In this step you will create a Java class that represents the submission form created in the previous task. When the form data is submitted, the Java class will be instantiated, and the form data will be loaded into the members of the Java class.</p>
- <p>In the directory <code>pageflow_tutorial/src</code> create a directory named <strong><code>forms</code></strong>.</p>
- <p>In the directory <code>pageflow_tutorial/src/forms</code> create a JAVA file named <strong><code>ProfileForm.java</code></strong>.</p>
- <p>Edit <code>pageflow_tutorial/src/forms/ProfileForm.java</code> so it appears as follows.</p>
+ <p>In this step you will create a Java class that accepts data from the JSP submission form created in the previous task. When the form data is submitted, the Java class will be instantiated, and the form data will be loaded into the JavaBean properties of the new instance.</p>
+ <p>In the directory <code>src</code> create a directory named <strong><code>forms</code></strong>.</p>
+ <p>In the directory <code>src/forms</code> create a JAVA file named <strong><code>ProfileForm.java</code></strong>.</p>
+ <p>
+ Edit <code>src/forms/ProfileForm.java</code> so it contains getters and setters for
+ two JavaBean properties (<code>name</code> and <code>age</code>), as follows.
+ </p>
<p><strong><code>ProfileForm.java</code></strong></p>
<source>
@@ -487,30 +463,25 @@
</section>
<section id="forms_edit_controller">
<title>Edit the Controller Class to Handle the Submitted Data</title>
- <p>Now you will add a new Action and use your new Form Bean to handle the data
+ <p>Now you will add a new action and use your new form bean to handle the data
submitted from the HTML form.</p>
- <p>Open the file <code>pageflow_tutorial/web/Controller.java</code>
+ <p>Open the file <code>web/myFlow/Controller.java</code>
</p>
<p>Edit <code>Controller.java</code> so it appears as follows. Code to add appears in bold type.</p>
<p><strong><code>Controller.java</code></strong></p>
<source>
-import javax.servlet.http.HttpSession;
+package myFlow;
-...
-
-import org.apache.beehive.netui.pageflow.Forward;
-import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.PageFlowController;
+<strong>import org.apache.beehive.netui.pageflow.Forward;</strong>
<strong>import forms.ProfileForm;</strong>
@Jpf.Controller(
simpleActions={
@Jpf.SimpleAction(name="begin", path="index.jsp"),
@Jpf.SimpleAction(name="toPage2", path="page2.jsp")
- },
- sharedFlowRefs={
- @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class)
}
)
public class Controller
@@ -527,9 +498,6 @@
System.out.println("Age: " + form.getAge());
return new Forward("success");
}</strong>
-
- ...
-
}
</source>
<p>Save <code>Controller.java</code>.</p>
@@ -542,12 +510,12 @@
<title>Test the NetUI Web Application</title>
<p>Visit the following link:
</p>
- <p><a class="fork" href="http://localhost:8080/pageflow_tutorial/Controller.jpf">http://localhost:8080/pageflow_tutorial/Controller.jpf</a></p>
+ <p><a class="fork" href="http://localhost:8080/netui-tutorial/myFlow/Controller.jpf">http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</a></p>
<p>You will be directed to the <code>index.jsp</code> page.</p>
<p>Click the link.</p>
<p>You will be directed to page2.jsp.</p>
<p>Enter values in the Name and Age fields, and click Submit.</p>
- <p>Notice the name and age values you entered are displayed in the Tomcat console shell.</p>
+ <p>Notice the name and age values you entered are displayed in the Tomcat console.</p>
</section>
</section>
<section id="forms_display_data">
@@ -555,9 +523,12 @@
<section id="create_jsp">
<title>Create a JSP to Display Submitted Data</title>
<p>In this step you will create a new JSP to present the results from processing the data submission.</p>
- <p>In the directory <code>pageflow_tutorial/web</code> create a file named
+ <p>In the directory <code>web/myFlow</code> create a file named
<strong><code>displayData.jsp</code></strong>. </p>
- <p>Edit <code>displayData.jsp</code> so it appears as follows.</p>
+ <p>
+ Edit <code>displayData.jsp</code> so it appears as follows. The "page inputs" that are being
+ displayed will come from the action in your page flow (next step).
+ </p>
<p><strong><code>displayData.jsp</code></strong></p>
<source><![CDATA[
@@ -573,9 +544,9 @@
You submitted the following information:
</p>
<p>
- Name: <netui:content value="${requestScope.data.name}"/>
+ Name: ${pageInput.name}
<br/>
- Age: <netui:content value="${requestScope.data.age}"/>
+ Age: ${pageInput.age}
</p>
</netui:body>
</netui:html>
@@ -584,7 +555,10 @@
</section>
<section id="forms_process_action">
<title>Process the Submitted Data</title>
- <p>Edit the <code>processData</code> method in the <code>Controller.java</code> file so it appears as follows. Code to add appears in bold.</p>
+ <p>
+ Edit the <code>processData</code> method in the <code>Controller.java</code> file so it appears as follows. Code to add appears in bold.
+ Note that the "action outputs" you are adding here will be read as "page inputs" on the page.
+ </p>
<p><strong><code>Controller.java</code></strong></p>
<source>
@@ -598,8 +572,11 @@
public Forward processData(ProfileForm form) {
System.out.println("Name: " + form.getName());
System.out.println("Age: " + form.getAge());
- <strong>getRequest().setAttribute("data", form);</strong>
- return new Forward("success");
+ <strong>
+ Forward fwd = new Forward("success");
+ fwd.addActionOutput("name", form.getName());
+ fwd.addActionOutput("age", form.getAge());
+ return fwd;</strong>
}
...
@@ -614,72 +591,157 @@
<title>Test the NetUI Web Application</title>
<p>Visit the following link:
</p>
- <p><a class="fork" href="http://localhost:8080/pageflow_tutorial/Controller.jpf">http://localhost:8080/pageflow_tutorial/Controller.jpf</a></p>
+ <p><a class="fork" href="http://localhost:8080/netui-tutorial/myFlow/Controller.jpf">http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</a></p>
<p>You will be directed to the <code>index.jsp</code> page.</p>
<p>Click the link.</p>
<p>You will be directed to page2.jsp.</p>
<p>Enter values in the Name and Age fields. Click the Submit button.</p>
<p>You will be forwarded to the <code>displayData.jsp</code> page. Notice the values you entered are displayed.</p>
+ <note>
+ In this step, you used "action outputs" and "page inputs" to get data from your page flow controller
+ to your JSP. You can get more formal about both by declaring expected types and whether the values
+ are required; to do this, you use annnotations and JSP tags as described
+ <a href="site:docs/pageflow/netuiBasic/databinding/pageInput">here</a>.
+ </note>
</section>
</section>
<section id="validation">
<title>Step 6: Input Validation</title>
<section id="validation_add">
- <title>Add Declarative Validation to the Page Flow</title>
+ <title>Add Declarative Validation to the Form Bean</title>
<p>In this step you will use declarative validation to define the set of rules for each
- field, to be applied during input validation. Add a <code>ValidatableProperty</code>
- for the name field of the form so that it will (1) be a required field and
- (2) have a maximum length of 30 characters. The age field will also be required and must have a value
- in the range 0 to 130.</p>
- <p>Open the file <code>pageflow_tutorial/web/Controller.java</code></p>
+ field, to be applied during input validation. You will add a
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.ValidatableProperty.html">
+ <code>ValidatableProperty</code>
+ </a>
+ annotation for the <code>name</code> property of the form so that it will (1) be required, and
+ (2) have a maximum length of 30 characters. The <code>age</code> property will also be required
+ and must have a value in the range 1 to 130.</p>
+ <p>Open the file <code>src/forms/ProfileForm.java</code></p>
<p>
- Edit the
- <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Action.html">
- <code>@Jpf.Action</code>
+ Add validation annotations. Code to add appears in bold (notice the additional <code>import</code> statment for the annotations).
+ </p>
+ <p><strong><code>src/forms/ProfileForm.java</code></strong></p>
+ <source>package forms;
+
+<strong>import org.apache.beehive.netui.pageflow.annotations.Jpf;</strong>
+
+public class ProfileForm
+ implements java.io.Serializable {
+
+ private int age;
+ private String name;
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ <strong>@Jpf.ValidatableProperty(
+ displayName = "Name",
+ validateRequired = @Jpf.ValidateRequired(),
+ validateMaxLength = @Jpf.ValidateMaxLength(chars = 30)</strong>
+ )
+ public String getName() {
+ return this.name;
+ }
+
+ public void setAge(int age) {
+ this.age = age;
+ }
+
+ <strong>@Jpf.ValidatableProperty(
+ displayName = "Age",
+ validateRequired = @Jpf.ValidateRequired(),
+ validateRange = @Jpf.ValidateRange(minInt = 1, maxInt = 130)</strong>
+ )
+ public int getAge() {
+ return this.age;
+ }
+}</source>
+ <p>Save and close <code>ProfileForm.java</code>.</p>
+ <note>
+ The validation annotations above do <strong>not</strong> produce localized messages. If you want
+ your messages to be localizable, you would do two things: (1) add a
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.FormBean.html">
+ <code>@Jpf.FormBean</code>
</a>
- annotation for the <code>processData</code> method in the
- <code>Controller.java</code> file so it appears as follows. Code to add appears in bold.
- Don't forget the comma after the <code>forwards={...}</code> element!</p>
- <p><strong><code>Controller.java</code></strong></p>
- <source>
+ annotation on the <code>ProfileForm</code> class, with its
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.FormBean.html#messageBundle()">
+ <code>messageBundle</code>
+ </a>
+ attribute set to a valid message bundle, and (2) use the
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.ValidatableProperty.html#displayNameKey()">
+ <code>displayNameKey</code>
+ </a>
+ attribute instead of
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.ValidatableProperty.html#displayName()">
+ <code>displayName</code>
+ </a>
+ on your validation annotations.
+ <br/>
+ <br/>
+ If you don't want to use the default validation messages provided by NetUI, you can use the
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.ValidateRequired.html#message()">
+ <code>message</code>
+ </a>
+ or
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.ValidateRequired.html#messageKey()">
+ <code>messageKey</code>
+ </a>
+ attributes on any of the validation annotations.
+ </note>
-...
+ <p>
+ Next, add a
+ <a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Action.html#validationErrorForward()">
+ <code>validationErrorForward</code>
+ </a>
+ to the <code>processData</code> action in <code>web/myFlow/Controller.java</code>:
+ </p>
+ <p><strong><code>web/myFlow/Controller.java</code></strong></p>
+ <source>package myFlow;
+
+import org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.PageFlowController;
+import org.apache.beehive.netui.pageflow.Forward;
+import forms.ProfileForm;
+@Jpf.Controller(
+ simpleActions={
+ @Jpf.SimpleAction(name="begin", path="index.jsp"),
+ @Jpf.SimpleAction(name="toPage2", path="page2.jsp")
+ }
+)
+public class Controller
+ extends PageFlowController
+{
@Jpf.Action(
forwards = {
@Jpf.Forward(name="success", path="displayData.jsp")
}<strong>,
- validatableProperties = {
- @Jpf.ValidatableProperty(
- propertyName = "name",
- displayName = "Name",
- validateRequired = @Jpf.ValidateRequired(),
- validateMaxLength = @Jpf.ValidateMaxLength(chars = 30)),
- @Jpf.ValidatableProperty(
- propertyName = "age",
- displayName = "Age",
- validateRequired = @Jpf.ValidateRequired(),
- validateRange = @Jpf.ValidateRange(minInt = 0, maxInt = 130))
- },
- validationErrorForward =
- @Jpf.Forward(name="fail", navigateTo=Jpf.NavigateTo.currentPage)</strong>
+ validationErrorForward=@Jpf.Forward(name="fail", path="page2.jsp")</strong>
)
public Forward processData(ProfileForm form) {
System.out.println("Name: " + form.getName());
System.out.println("Age: " + form.getAge());
- getRequest().setAttribute("data", form);
- return new Forward("success");
- }
- ...
-</source>
+ Forward fwd = new Forward("success");
+ fwd.addActionOutput("name", form.getName());
+ fwd.addActionOutput("age", form.getAge());
+ return fwd;
+ }
+}</source>
<p>Save <code>Controller.java</code>.</p>
+ <p>
+ The annotation you just added causes navigation to flow back to <code>page2.jsp</code> if any
+ validation error occurs in the form bean for action <code>processData</code>.
+ </p>
</section>
<section id="validation_display_errors">
<title>Modify the JSP to Display Validation Errors</title>
<p>Add the <code><netui:error></code> tag to display validation error messages on the page.</p>
- <p>Edit the file <code>pageflow_tutorial/web/page2.jsp</code> so it appears as follows.</p>
- <p><strong><code>page2.jsp</code></strong></p>
+ <p>Edit the file <code>web/myFlow/page2.jsp</code> so it appears as follows.</p>
+ <p><strong><code>web/myFlow/page2.jsp</code></strong></p>
<source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
<netui:html>
@@ -705,6 +767,10 @@
</netui:body>
</netui:html></source>
<p>Save and close <code>page2.jsp</code>.</p>
+ <p>
+ Now, any validation error that happens for the <code>name</code> property will appear next to the
+ "Name:" input field. Likewise for the <code>age</code> property.
+ </p>
</section>
<section id="validation_build_deploy">
<title>Recompile and Redeploy the Web Application</title>
@@ -713,7 +779,7 @@
<section id="validation_run">
<title>Test the NetUI Web Application</title>
<p>Visit the following link:</p>
- <p><a class="fork" href="http://localhost:8080/pageflow_tutorial/Controller.jpf">http://localhost:8080/pageflow_tutorial/Controller.jpf</a></p>
+ <p><a class="fork" href="http://localhost:8080/netui-tutorial/myFlow/Controller.jpf">http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</a></p>
<p>You will be directed to the <code>index.jsp</code> page.</p>
<p>Click the link.</p>
<p>You will be directed to page2.jsp.</p>
@@ -723,13 +789,22 @@
</section>
<section id="nested">
<title>Step 7: Collect Data from a Nested Page Flow</title>
+ <p>
+ <a href="site:docs/pageflow/netuiBasic/nestedPageFlow">Nested page flows</a> allow you to insert
+ <em>entire flows</em> in the middle of the current flow. One use for this is to collect data in another
+ flow, but still come back to the current flow to use the data.
+ </p>
<section id="nested_link">
<title>Link to the Nested Page Flow</title>
<p>
- In this task you will modify the HTML form tag to (1) add a new data field and (2) add a button linking to
- an Action in a nested page flow. (Later you will create the nested controller class to handle the data collection.)</p>
- <p>Edit the file <code>pageflow_tutorial/web/page2.jsp</code> so it appears as follows. Code to add appears in bold.</p>
- <p><strong><code>page2.jsp</code></strong></p>
+ In this task you will modify the HTML form tag to (1) add a new data field and (2) add a button that
+ launches a nested page flow. (Later you will create the nested page flow to handle the data
+ collection.)
+ </p>
+ <p>
+ Edit the file <code>web/myFlow/page2.jsp</code> so it appears as follows. Code to add appears in bold.
+ </p>
+ <p><strong><code>web/myflow/page2.jsp</code></strong></p>
<source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
<netui:html>
@@ -767,7 +842,7 @@
the new member of the Form Bean class instance can be loaded with the value collected.
</p>
<p>
- Edit <code>pageflow_tutorial/src/forms/ProfileForm.java</code> and add the following member variable and methods.
+ Edit <code>src/forms/ProfileForm.java</code> and add the following member variable and methods.
</p>
<p><strong><code>ProfileForm.java</code></strong></p>
<source>
@@ -791,7 +866,7 @@
<title>To Launch and Return from the Nested Page Flow</title>
<p>In this task you will add Action methods: one to handle forwarding to the nested page flow and another to
implement the return Action when the nested page flow completes.</p>
- <p>Open the file <code>pageflow_tutorial/web/Controller.java</code></p>
+ <p>Open the file <code>web/myFlow/Controller.java</code></p>
<p>Edit <code>Controller.java</code> so it appears as follows. Code to add appears
in bold type. Don't forget to add the <code>useFormBean</code> property to the
<a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Action.html">
@@ -802,20 +877,17 @@
instance in multiple Action methods.</p>
<p><strong><code>Controller.java</code></strong></p>
<source>
-import javax.servlet.http.HttpSession;
+package myFlow;
-import org.apache.beehive.netui.pageflow.Forward;
-import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.PageFlowController;
+import org.apache.beehive.netui.pageflow.Forward;
import forms.ProfileForm;
@Jpf.Controller(
simpleActions={
@Jpf.SimpleAction(name="begin", path="index.jsp"),
@Jpf.SimpleAction(name="toPage2", path="page2.jsp")
- },
- sharedFlowRefs={
- @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class)
}
)
public class Controller
@@ -872,10 +944,9 @@
propertyName = "age",
displayName = "Age",
validateRequired = @Jpf.ValidateRequired(),
- validateRange = @Jpf.ValidateRange(minInt = 0, maxInt = 130))
+ validateRange = @Jpf.ValidateRange(minInt = 1, maxInt = 130))
},
- validationErrorForward =
- @Jpf.Forward(name="fail", navigateTo=Jpf.NavigateTo.currentPage)
+ validationErrorForward = @Jpf.Forward(name="fail", path="page2.jsp")
)
public Forward processData(ProfileForm form) {
System.out.println("Name: " + form.getName());
@@ -883,9 +954,6 @@
getRequest().setAttribute("data", form);
return new Forward("success");
}
-
- ...
-
}
</source>
<p>Save <code>Controller.java</code>.</p>
@@ -899,22 +967,21 @@
declared as member data of this nested page flow. After the user confirms the
data, the nested page flow returns a <code>String</code> to the main page flow.</p>
<p>
- In the directory <code>pageflow_tutorial/web</code> create a directory named <strong><code>sports</code></strong>.
+ In the directory <code>web/myFlow</code> create a directory named <strong><code>sports</code></strong>.
</p>
<p>
- In the directory <code>pageflow_tutorial/web/sports</code> create a Java file named
+ In the directory <code>web/myFlow/sports</code> create a Java file named
<strong><code>SportsController.java</code></strong>.
</p>
- <p>Edit <code>pageflow_tutorial/web/sports/SportsController.java</code> so it appears as follows.</p>
+ <p>Edit <code>web/myFlow/sports/SportsController.java</code> so it appears as follows.</p>
<p><strong><code>SportsController.java</code></strong></p>
<source>
package sports;
-import org.apache.beehive.netui.pageflow.FormData;
-import org.apache.beehive.netui.pageflow.Forward;
-import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
+import org.apache.beehive.netui.pageflow.PageFlowController;
+import org.apache.beehive.netui.pageflow.Forward;
@Jpf.Controller(
nested = true,
@@ -959,7 +1026,7 @@
}
public static class SportForm
- extends FormData {
+ implements java.io.Serializable {
private String sport;
@@ -979,7 +1046,7 @@
<title>To Present and Collect Data using a Form</title>
<p>This task illustrates the use of custom tags to render a radio button group in an HTML form and
link it to the nested page flow <code>selectSport</code> Action method.</p>
- <p>In the directory <code>pageflow_tutorial/web/sports</code>, create a file named <code>index.jsp</code>.</p>
+ <p>In the directory <code>web/myFlow/sports</code>, create a file named <code>index.jsp</code>.</p>
<p>Edit index.jsp so it appears as follows.</p>
<p><strong><code>index.jsp</code></strong></p>
<source><![CDATA[
@@ -1015,7 +1082,7 @@
</section>
<section id="nested_confirm_data">
<title>Confirm the Selected Data</title>
- <p>In the directory <code>pageflow_tutorial/web/sports</code>, create a file named <code>confirm.jsp</code>.</p>
+ <p>In the directory <code>web/myFlow/sports</code>, create a file named <code>confirm.jsp</code>.</p>
<p>Edit confirm.jsp so it appears as follows.</p>
<p><strong><code>confirm.jsp</code></strong></p>
<source><![CDATA[
@@ -1031,7 +1098,7 @@
Confirm Sport Activity
</p>
<p>
- Sport: <netui:content value="${pageFlow.selectedSport}"/>
+ Sport: ${pageFlow.selectedSport}
</p>
<netui:form action="confirm">
<netui:button type="submit" value="Confirm"/>
@@ -1044,7 +1111,7 @@
<section id="nested_display_data">
<title>Update the JSP to Display Submitted Data</title>
<p>In this step you will update the JSP to present the results from processing the data submission.</p>
- <p>In the directory <code>pageflow_tutorial/web</code> update the file named
+ <p>In the directory <code>web/myFlow</code> update the file named
<strong><code>displayData.jsp</code></strong> and add code to display the additional data.
The code to add appears in bold type.</p>
<p>Edit <code>displayData.jsp</code> so it appears as follows.</p>
@@ -1062,11 +1129,11 @@
You submitted the following information:
</p>
<p>
- Name: <netui:content value="${requestScope.data.name}"/>
+ Name: ${pageInput.name}
<br/>
- Age: <netui:content value="${requestScope.data.age}"/>
+ Age: ${pageInput.age}
<strong><br/>
- Sport: <netui:content value="${requestScope.data.sport}"/></strong>
+ Sport: ${pageInput.sport}</strong>
</p>
</netui:body>
</netui:html></source>
@@ -1079,7 +1146,7 @@
<section id="nested_run_again">
<title>To Test the NetUI Web Application</title>
<p>Visit the following link:</p>
- <p><a class="fork" href="http://localhost:8080/pageflow_tutorial/Controller.jpf">http://localhost:8080/pageflow_tutorial/Controller.jpf</a></p>
+ <p><a class="fork" href="http://localhost:8080/netui-tutorial/myFlow/Controller.jpf">http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</a></p>
<p>You will be directed to the <code>index.jsp</code> page.</p>
<p>Click the link.</p>
<p>You will be directed to page2.jsp.</p>
@@ -1096,7 +1163,7 @@
<title>Step 8: Adding Actions to a Shared Flow</title>
<section id="sharedflow_page">
<title>To Create a Common Destination JSP</title>
- <p>In the directory <code>pageflow_tutorial/web</code>, create a file named <code>help.jsp</code>.</p>
+ <p>In the directory <code>web/myFlow</code>, create a file named <code>help.jsp</code>.</p>
<p>Edit help.jsp so it appears as follows.</p>
<p><strong><code>help.jsp</code></strong></p>
<source><![CDATA[
@@ -1120,7 +1187,7 @@
<title>To Make an Action available to multiple Page Flows</title>
<p>In this task you will add a Simple Action to the existing Shared Flow. The Action forwards to the
help page created in the previous task and will be available to multiple page flows in the application.</p>
- <p>Open the existing Shared Flow file <code>pageflow_tutorial/src/shared/SharedFlow.java</code></p>
+ <p>Open the existing Shared Flow file <code>src/shared/SharedFlow.java</code></p>
<p>
Edit the
<a href="../apidocs/classref_netui/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
@@ -1151,7 +1218,7 @@
<title>To Link a Page to the Shared Flow Action</title>
<p>In this task you will create a link from the JSP, <code>index.jsp</code> to the
Shared Flow Action.</p>
- <p>Open the file <code>pageflow_tutorial/web/index.jsp</code>.</p>
+ <p>Open the file <code>web/myFlow/index.jsp</code>.</p>
<p>Edit <code>index.jsp</code> so it appears as follows. The code to add appears in bold type.</p>
<p><strong><code>index.jsp</code></strong></p>
<source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
@@ -1185,7 +1252,7 @@
<section id="sharedflow_run">
<title>Test the NetUI Web Application</title>
<p>Visit the following link:</p>
- <p><a class="fork" href="http://localhost:8080/pageflow_tutorial/Controller.jpf">http://localhost:8080/pageflow_tutorial/Controller.jpf</a></p>
+ <p><a class="fork" href="http://localhost:8080/netui-tutorial/myFlow/Controller.jpf">http://localhost:8080/netui-tutorial/myFlow/Controller.jpf</a></p>
<p>You will be directed to the <code>index.jsp</code> page.</p>
<p>Click the help link.</p>
<p>A popup window with the <code>help.jsp</code> page will be displayed.</p>