Author: steveh
Date: Wed Aug 31 16:09:14 2005
New Revision: 265602
URL: http://svn.apache.org/viewcvs?rev=265602&view=rev
Log:
Editing run-through.
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/getting_started.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/jspOverview.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowControllers.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
beehive/trunk/docs/how_to_contribute_docs.txt
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial_controls.xml
Wed Aug 31 16:09:14 2005
@@ -10,7 +10,7 @@
<section>
<title>Tutorial Goals</title>
<p>The Controls tutorial is provided as a way to become
familiar with the concepts of Controls in Beehive. The tutorial
- walks through creating, building, and deploying a sample
project that uses a Control from a page flow. Note, NetUI Page Flow isn't
+ walks through creating, building, and deploying a sample project that
uses a Control from a page flow. <strong>Note:</strong> NetUI Page Flow isn't
required to use Controls; they just provide a convenient way to demonstrate running a Control. In this tutorial,
you will learn:</p>
<ul>
@@ -35,7 +35,7 @@
In order to follow the steps in this tutorial, it's necessary
to create a Beehive-enabled web application. Beehive-enabled web applications
are described <a href="site:setup">here</a>. A skeleton Beehive-enabled web project is provided in the samples/ directory as
<a href="site:netui-blank">netui-blank</a>. This contains a basic Ant build file and an example page flow controller. To create the
- tutorial's project, we'll copy and then rename the <a
href="site:netui-blank">netui-blank</a> project using these steps:
+ web project, copy and then rename the <a
href="site:netui-blank">netui-blank</a> project using these steps:
</p>
<ol>
<li>Create a directory <code>/beehive_projects</code> (on Windows, this would be
<code>C:\beehive_projects</code>).</li>
@@ -104,18 +104,17 @@
<title>Add Sample Control Interface and Implementation Source
Files</title>
<p>
This tutorial uses a sample Hello World control that is contained in
- <strong><code><BeehiveRoot>/samples/controls-blank/src/pkg</code></strong>. Copy the <code>pkg</code>
+ <strong><code><BeehiveDistribution>/samples/controls-blank/src/pkg</code></strong>. Copy the <code>pkg</code>
sub-directory from this path into the directory <strong><code>control_tutorial/WEB-INF/src</code></strong>.
</p>
<p>Now, confirm that the following directories and files
exist:</p>
<source>
- control_tutorial/
- WEB-INF/
- src/
- pkg/
- Hello.java
- HelloImpl.java
- </source>
+control_tutorial/
+ WEB-INF/
+ src/
+ pkg/
+ Hello.java
+ HelloImpl.java</source>
</section>
<section id="setup_start_server">
<title>Start the Server</title>
@@ -252,21 +251,18 @@
<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>controls_tutorial/WEB-INF/src</code> directory. At the command prompt,
enter:</p>
<source>
- ant clean build war
- </source>
+ ant clean build war</source>
<p>
This will build the webapp by running the Beehive annotation processors and will produce class files in <code>WEB-INF/classes</code>.
Now, the application is ready to deploy to your server. On Tomcat, copy the WAR file into Tomcat's <code>$CATALINA_HOME/webapps</code>
directory.</p>
<p>On Windows:</p>
<source>
- copy controls_tutorial.war %CATALINA_HOME%\webapps /Y
- </source>
+ copy controls_tutorial.war %CATALINA_HOME%\webapps /Y</source>
<p>Everywhere else:</p>
<source>
- cp controls_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
+ cp controls_tutorial.war $CATALINA_HOME/webapps</source>
+ <p>If you are asked to overwrite the old WAR file, enter 'yes'. Note, during 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>
<p>If you are not using Tomcat, follow your server's web application
deployment instructions to deploy the webapp.</p>
</section>
@@ -350,31 +346,29 @@
<section id="add_method_edit_page">
<title>Edit a Test JSP</title>
<p>Edit <code>index.jsp</code> so it appears as follows. Code to add appears in
bold.</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"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0"; prefix="netui"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0";
prefix="netui-template"%>
-<netui:html>
- <head>
- <title>Control Tutorial Test Page</title>
- <netui:base/>
- </head>
- <netui:body>
- <jsp:useBean class="pkg.HelloBean" id="helloBean" scope="session"/>
- <h3>Control Tutorial Test Page</h3>
- <p>
+ <source>
+<%@ page language="java" contentType="text/html;charset=UTF-8"%>
+<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0";
prefix="netui-data"%>
+<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0";
prefix="netui"%>
+<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0";
prefix="netui-template"%>
+<netui:html>
+ <head>
+ <title>Control Tutorial Test Page</title>
+ <netui:base/>
+ </head>
+ <netui:body>
+ <jsp:useBean class="pkg.HelloBean" id="helloBean" scope="session"/>
+ <h3>Control Tutorial Test Page</h3>
+ <p>
Response from the hello() method on the Hello Control:
- <netui:span style="color:#FF0000" value="${pageInput.helloMessage}"/>
- </p>
- <strong><p>Response from the helloParam() method on the Hello Control:
- <netui:span style="color:#FF0000" value="${pageInput.helloParamMessage}"/>
- </p>
- </strong>
- </netui:body>
-</netui:html>
-]]>
-</source>
+ <netui:span style="color:#FF0000"
value="${pageInput.helloMessage}"/>
+ </p>
+ <strong><p>
+ Response from the helloParam() method on the Hello Control:
+ <netui:span style="color:#FF0000" value="${pageInput.helloParamMessage}"/>
+ </p></strong>
+ </netui:body>
+</netui:html></source>
</section>
<section id="add_method_build_deploy">
<title>Compile and Redeploy the Web Application</title>
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/getting_started.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/getting_started.xml?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/getting_started.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/getting_started.xml
Wed Aug 31 16:09:14 2005
@@ -8,6 +8,7 @@
<p>For an introduction to the basic concepts of NetUI (Page Flow and the JSP tags), see
the <strong>users guide</strong> topics:</p>
<ul>
<li><a href="site:pageflow_overview">NetUI Overview</a></li>
+ <li><a href="site:pageflow_controllers">Controller Classes</a></li>
<li><a href="site:pageflow_jsp">JSP Files</a></li>
</ul>
<p>The following <strong>tutorial</strong> will familiarize with the basic
development cycle NetUI web applications:</p>
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/jspOverview.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/jspOverview.xml?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/jspOverview.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/jspOverview.xml
Wed Aug 31 16:09:14 2005
@@ -7,14 +7,14 @@
<body>
<section id="introduction">
<title>Introduction</title>
- <p> NetUI adds a handful of tag libraries to normal JSP usage to
assist with the
+ <p> NetUI adds three tag libraries to normal JSP usage to assist with
the
binding of the JSPs to the controller class. These tag libraries
add a number of features such
as HTML form controls, data grids, and trees. For a detailed
overview of the tag libraries
and their usage see the <a href="site:pageflow_tag_overview">NetUI Tag
Library Overview</a>. The
<a href="../apidocs/taglib/taglib-overview-summary.html">tag library API
documentation</a>
describes all of the details.
</p>
- <p> There are three tag libraries provided by NetUI.
+ <p> There tag libraries provided by NetUI are:
</p>
<ul>
<li><a
href="../apidocs/taglib/taglib-overview-summary.html#netui"><code><netui:xxx></code></a>
--
@@ -195,7 +195,7 @@
</p>
<ul>
- <li><a href="site:netuiProjects">Building a NetUI Web Project</a></li>
+ <li><a href="site:netuiProjects">NetUI Web App Project Model</a></li>
</ul>
</section>
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/overview.xml
Wed Aug 31 16:09:14 2005
@@ -1,346 +1,583 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
"http://forrest.apache.org/dtd/document-v20.dtd";>
<document>
- <header>
- <title>NetUI Overview</title>
- </header>
- <body>
- <section id="introduction">
- <title>Introduction</title>
- <p>
- NetUI is the piece of Beehive used to build the front-end of a
web application. It contains
- two pieces: Page Flow and a powerful set of JSP tags.
- </p>
- </section>
- <section id="why">
- <title>Why Use NetUI?</title>
- <p>
- Simply put, NetUI (Page Flow and a powerful set of JSP tags)
helps you build a
- well-structured web application using a simple programming
model.
- </p>
- <p>
- First, because NetUI is an MVC framework (built on
- <a href="http://struts.apache.org";>Apache Struts</a>), it
separates navigational
- control from presentation. This avoids:
- </p>
- <ul>
- <li>Limited reuse of navigational/flow logic.</li>
- <li>Cluttered, hard-to-maintain JSP source code.</li>
- <li>Difficulty in understanding the flow of an
application.</li>
- <li>
- Unintended exposure of controller-logic code to team members who focus
- on other aspects of web development, such as content writers and visual
- designers.
- </li>
- </ul>
- <p>
- Next, NetUI provides the Page Flow programming model which
allows you to create
- <em>modular</em> "page flows" that can be inserted (and
reused) inside of other
- flows. At its heart, it unifies the controller logic, state,
and metadata for a
- piece of your application into a single class. On the View
side, it offers a rich
- set of tags, such as the <a
href="site:pageflow_tag_tree">Tree</a> and the
- <a href="site:datagrid">Datagrid</a>.
- </p>
- </section>
- <section id="Page_Flow_Features">
- <title>NetUI Features</title>
- <p>
- NetUI makes building Java web applications easy and intuitive.
- When building applications with NetUI, the developer writes Java classes and pages --that's it.
- There is very little occasion to work with configuration files, or other components.
- NetUI also excels at separating presentation logic from data processing
- logic, resulting in uncluttered JSP code which is easy to understand and edit.
- Data processing and the web application configurables are handled in a single Java
- class using a simple declarative programming model.
- </p>
- <p><strong>Declarative Programming</strong></p>
- <p>
- Many common web app programming tasks are accomplished through a declarative programming model using
- "annotations", a new feature in Java 5. Annotations put configuration configuration information (in
- general, "metadata") right alongside your code, alleviating the need for independent
- configuration files. Navigation, exception handling, validation, and other tasks are all defined
- in a single Java class: the Page Flow "controller" class that
drives a piece of your web application.
- </p>
- <p><strong>Stateful Page Flows</strong></p>
- <p>
- When a user enters a page flow (by hitting an URL in the page flow's URL space), an instance of the
- page flow's controller class is created. While the user is in the page flow, the controller instance
- simply stores the flow-related state in member variables. Methods within the class -- particularly
- action methods and exception handlers -- have access to the
member state. By default, the state is
- <em>automatically cleaned up</em> when the user leaves the
page flow to enter another one. This
- behavior can be configured per-page flow, but auto-cleanup
helps keep your session small, and focused
- on the task at hand.
- </p>
- <p><strong>Modular Page Flows</strong></p>
- <p>
- A single web application can have multiple page flows within
it, allowing you to break up the
- application into separate, self-contained chunks of functionality. For an example, see the
- <a class="fork" href="site:samples/petstore">Petstore Sample</a>, which has different page flows
- for browsing the Petstore, buying products, and handling user accounts.
- </p>
- <p><strong>Inheritance and Shared Flow</strong></p>
- <p>
- [TODO]
- </p>
- <p><strong>Nested Page Flows</strong></p>
- <p>
- An entire page flow can be inserted, or "nested", inside of
another page flow. At its heart,
- nesting is a way of pushing aside the current page flow
temporarily and transferring control to
- another (nested) page flow with the intention of coming back
to the original one. Nesting is
- useful when you want to do one of the following tasks:
- </p>
- <ul>
- <li>gather data from the user, for use in the current page
flow;</li>
- <li>allow the user to correct errors or supply additional information en route to executing a desired
- action; </li>
- <li>show an alternate view of data represented in the current page
flow;</li>
- <li>bring the user through a "wizard";</li>
- <li>
- show the user information that will be useful in the current page flow (e.g., help screens can be
- easily implemented as nested page flows); and
- </li>
- <li>
- in general, to further break up your application into
separate (and in many cases reusable) pieces.
- </li>
- </ul>
- <p>
- NetUI also offers special integration between nested page
flows and
- <a href="site:pageflow_popups">popup windows</a>.
- </p>
- <p><strong>Declarative Exception Handling and
Validation</strong></p>
- <p>[TODO]</p>
- <p><strong>Powerful JSP Tags</strong></p>
- <p>[TODO]</p>
- <p><strong>First-class Integration with JavaServer
Faces</strong></p>
- <p>[TODO]</p>
- <p><strong>Struts Integration</strong></p>
- <p>Page Flow is built on top of Apache Struts 1.1. Each Page Flow controller is compiled into a Struts module.
- As a result, NetUI and Struts applications can work closely together.</p>
- <p>Struts modules and page flows can co-habitate and interact with one another inside a web app. To forward
- from a page flow to a (pure) Struts module, simply reference the desired action within the Struts module.
- The same goes for the reverse direction: from a Struts module, simply configure an action to point to
- the desired method in the page flow.
- <!--[todo: detailed doc based on R. Feit's: http://dev2dev.bea.com/products/wlworkshop81/articles/Feit.jsp]--></p>
- <p>You can also use the Struts merge feature to read configuration data from a pure Struts app into your
- Page Flow app's configuration files. Ordinarily, your Page Flow's configuration files are generated
- entirely from your application's
- JAVA source files (specifically from the <em>metadata annotations</em> that decorate the controller classs).
- But, in cases where you want to integrate a Struts module into your application,
- you can specify that the configuration files be generated from <em>both</em> the JAVA source files <em>and</em> the
- Struts module's configuration files, allowing you to change or add <em>any tag</em> in the generated
- configuration file. For example, suppose you want to override an action form's default scoping from
- request-scoping to session-scoping. To do this, you simply create a Struts configuration file
- that overrides the appropriate parts of the Page Flow's configuration file, and then refer to this
- override file from within the Page Flow's JAVA source file (= the controller class)
- using a special annotation. In particular,
- you would specify the override file to state that such-and-such an
action form should have session-scope
- rather then request-scope (so that the action form can now be shared with
the Struts app). </p>
- </section>
- <section id="logical_flow">
- <title>The Logical Flow</title>
-
- <p>
- Writing traditional web applications without a Page Flow controller class requires a fair amount of
- logic to be applied within the application's pages. For example, a site
- that provides a "My Page" functionality for logged in users would have
- to include logic on the home page to determine if the "My Page" link
- should take the user to the login form or directly to their
customized
- page.
- </p>
-
- <p>
- Using a page flow, the home page of the application would not link
directly to
- either the login page <strong>or</strong> the user's "My Page"
location, but rather
- would point back into Java code that makes the decision.
- </p>
-
- <p>
- For the rest of this overview, the following <strong>logical page
flow</strong> will
- be used:
- </p>
-
- <p>
- <img src="images/logical-flow-1.png" alt="logical page flow" />
- </p>
-
- <p>
- This flow supports several routes from the home page of the application
- to the user's "My Page":
- </p>
-
- <ol>
- <li>
- <p>
- The user may directly navigate from <code>index.jsp</code> to <code>mypage.jsp</code>
- (by clicking a link), if the user is already logged in.
- </p>
- </li>
- <li>
- <p>
- If the user is not already logged in, attempts to navigate from
- <code>index.jsp</code> to <code>mypage.jsp</code>
- will be intercepted and the user will be taken to the <code>login.jsp</code> instead.
- After successfully logging in, the user will be automatically taken to
<code>mypage.jsp</code>
- </p>
- </li>
- <li>
- <p>
- The user may directly navigate from <code>index.jsp</code> to
<code>login.jsp</code> (by clicking a link).
- After logging in, the user will be automatically taken to
<code>mypage.jsp</code>.
- </p>
-
- <p>
- In the event of a login failure, <code>login.jsp</code> will
be redisplayed to give them
- another opportunity to authenticate themselves.
- </p>
- </li>
- <li>
- <p>
- If the user desires to register with the site, he can click a
link that will
- take him to <code>signup.jsp</code>. One signed up, the
<code>thanks.jsp</code>
- will be displayed which offers a link to the
<code>login.jsp</code> page.
- </p>
- </li>
- </ol>
-
- </section>
-
- <section id="implementation_of_flow">
- <title>The Implementation of the Flow: Controllers and
Actions</title>
-
- <p>
- In the above <strong>logical flow</strong> there are several
<em>if</em> statements
- that cause the user flow to vary depending on their previous
actions and other state.
- </p>
-
- <ul>
- <li>
- <em>If the user is not logged in...</em>
- </li>
- <li>
- <em>If the user is logged in...</em>
- </li>
- <li>
- <em>If the user's login attempt fails...</em>
- </li>
- </ul>
-
- <p>
- NetUI moves this condition logic out of the JSPs and into a Java
class that controls
- the movement through the application. This Java class
- is the <strong>controller</strong> portion of the
<strong>Model-View-Controller</strong>
- (MVC) pattern. This allows a page to be written, for example,
that appears
- to link directly from the home page of the application to the user's
"My Page".
- The controller is given the opportunity to intercept the navigation
- between the two and redirect the user to the login page, if
required.
- </p>
-
- <p>
- Each of the interception points is an <strong>action</strong> of
the
- particular controller class. Actions
- perform common application tasks. Here are some of the things that an action can do:
- </p>
-
- <ul>
- <li>navigate the user to a specified JSP</li>
- <li>perform conditional logic</li>
- <li>handle submitted data</li>
- <li>validate submitted data</li>
- <li>handle exceptions that arise in the application</li>
- </ul>
-
- <p>Note that controller classes, and the actions they contain, are <strong>URL addressable</strong>.
- Hitting the following URL creates an instance of the controller class
<code>foo.MyControllerClass</code>
- and runs its <code>begin</code> action. (When no other action is specified,
the <code>begin</code>
- method is run by default.) </p>
-
- <source>http://some.domain.com/foo/MyControllerClass.java </source>
-
- <p>Hitting the following URL creates an instance of <code>foo.MyControllerClass</code> (if it doesn't already
- exist) and invokes the <code>someAction</code> action. Note that
the controller class isn't mentioned
- by name: it's assumed that only one controller class exists in the directory, so there is only one
- candidate controller class to instantiate.</p>
-
- <source>http://some.domain.com/foo/someAction.do</source>
- <note>
- To make a Page Flow controller handle a default directory URL,
e.g.,
- <br/><br/>
- http://some.domain.com/myApp/myPageFlow
- <br/><br/>
- you will need to add the page flow's URL to the
<code>welcome-file-list</code> in
- <code>/WEB-INF/web.xml</code>:
- <br/><br/>
- <welcome-file-list>
-
<br/> <welcome-file>Controller.jpf</welcome-file>
-
<br/> <welcome-file>index.jsp</welcome-file>
- <br/> </welcome-file-list>
- <br/><br/>
- This would cause the following URL to be hit for the above
example:
- <br/><br/>
-
http://some.domain.com/myApp/myPageFlow/Controller.jpf
- <br/><br/>
- On some servers (like Tomcat), you would also need to make sure that a
<em>file</em> called
- <code>Controller.jpf</code> also exists in the web content under
<code>/myPageFlow</code>, even
- though the class <code>myPageFlow.Controller</code> actually
handles the request. (The file can
- be blank.)
- </note>
-
- <p>Actions may perform any required
- complex logic. For example, if a user clicks on the "My Page"
link, the action may check if
- the user is logged in, and if so, navigate the user to the
<code>mypage.jsp</code>
- page; otherwise it will navigate the user to the
- <code>login.jsp</code> page.
- </p>
-
- <p>
- With normal HTML pages, each page is linked directly to other
pages.
- </p>
-
- <ul>
- <li><strong>page > page > page > page</strong></li>
- </ul>
-
- <p>
- When using page flows, pages and actions are interwoven,
transparently.
- </p>
-
- <ul>
- <li><strong>page > action > page > action > page > action
> page</strong></li>
- </ul>
-
- <p>
- The above <strong>logical page flow</strong> can be redrawn with
Page Flow controller actions
- in mind, as:
- </p>
-
- <p>
- <img src="images/impl-flow-1.png" alt="implementation page
flow"/>
- </p>
-
- <p>
- Now it is apparent that to navigate from <code>index.jsp</code> to
<code>mypage.jsp</code>,
- the user traverses across the <code>myPage</code> action. This
action performs the necessary
- check to determine if the user has already been authenticated. If
the user has logged in already,
- it will direct the user straight to <code>mypage.jsp</code>; otherwise it will direct the user
- to <code>login.jsp</code>.
- </p>
- </section>
- <section id="next">
- <title>Next...</title>
-
- <p>
- Next, learn about writing a <strong>controller</strong> class with
actions.
- </p>
-
- <ul>
- <li><a class="jump" href="site:pageflow_controllers">Page Flow
Controller</a></li>
- </ul>
- </section>
- </body>
- <footer>
- <legal>
- Java, J2EE, and JCP are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries.<br/>
- © 2004, Apache Software Foundation
- </legal>
- </footer>
+ <header>
+ <title>NetUI Overview</title>
+ </header>
+ <body>
+ <section id="introduction">
+ <title>Introduction</title>
+ <p>
+ NetUI is the piece of Beehive used to build the
+ front-end of a web application. It contains two
pieces:
+ Page Flow and a powerful set of JSP tags.
+ </p>
+ </section>
+ <section id="why">
+ <title>Why Use NetUI?</title>
+ <p>
+ Simply put, NetUI (Page Flow and a powerful set
of JSP
+ tags) helps you build a well-structured web
application
+ using a simple programming model.
+ </p>
+ <p>
+ First, because NetUI is an MVC framework (built
on
+ <a href="http://struts.apache.org";>Apache
Struts</a>
+ ), it separates navigational control from
presentation.
+ This avoids:
+ </p>
+ <ul>
+ <li>Limited reuse of navigational/flow
logic.</li>
+ <li>Cluttered, hard-to-maintain JSP source
code.</li>
+ <li>
+ Difficulty in understanding the flow of
an
+ application.
+ </li>
+ <li>
+ Unintended exposure of controller-logic
code to team
+ members who focus on other aspects of
web
+ development, such as content writers
and visual
+ designers.
+ </li>
+ </ul>
+ <p>
+ Second, NetUI provides the Page Flow
programming model
+ which allows you to create
+ <em>modular</em>
+ "page flows" that can be inserted (and reused)
inside of
+ other flows. At its heart, it unifies the
controller
+ logic, state, and metadata for a piece of your
+ application into a single class. On the View
side, it
+ offers a rich set of tags, such as the
+ <a href="site:pageflow_tag_tree">Tree</a>
+ and the
+ <a href="site:datagrid">Datagrid</a>
+ .
+ </p>
+ </section>
+ <section id="Page_Flow_Features">
+ <title>NetUI Features</title>
+ <p>
+ NetUI makes building Java web applications easy
and
+ intuitive. When building applications with
NetUI, the
+ developer writes Java classes and pages
--that's it.
+ There is very little occasion to work with
configuration
+ files, or other components. NetUI also excels at
+ separating presentation logic from data
processing
+ logic, resulting in uncluttered JSP code which
is easy
+ to understand and edit. Data processing and the
web
+ application configurables are handled in a
single Java
+ class using a simple declarative programming
model.
+ </p>
+ <p>
+ <strong>Declarative Programming</strong>
+ </p>
+ <p>
+ Many common web app programming tasks are
accomplished
+ through a declarative programming model using
+ "annotations", a new feature in Java 5.
Annotations put
+ configuration information (in general,
"metadata") right
+ alongside your code, alleviating the need for
+ independent configuration files. Navigation,
exception
+ handling, validation, and other tasks are all
defined in
+ a single Java class: the Page Flow "controller"
class
+ that drives a piece of your web application.
+ </p>
+ <p>
+ <strong>Stateful Page Flows</strong>
+ </p>
+ <p>
+ When a user enters a page flow (by hitting an
URL in the
+ page flow's URL space), an instance of the page
flow's
+ controller class is created. While the user is
in the
+ page flow, the controller instance simply
stores the
+ flow-related state in member variables. Methods
within
+ the class -- particularly action methods and
exception
+ handlers -- have access to the member state. By
default,
+ the state is
+ <em>automatically cleaned up</em>
+ when the user leaves the page flow to enter
another one.
+ This behavior can be configured per-page flow,
but
+ auto-cleanup helps keep your session small, and
focused
+ on the task at hand.
+ </p>
+ <p>
+ <strong>Modular Page Flows</strong>
+ </p>
+ <p>
+ A single web application can have multiple page
flows
+ within it, allowing you to break up the
application into
+ separate, self-contained chunks of
functionality. For an
+ example, see the
+ <a class="fork" href="site:samples/petstore">
+ Petstore Sample
+ </a>
+ , which has different page flows for browsing
the
+ Petstore, buying products, and handling user
accounts.
+ </p>
+ <p>
+ <strong>Inheritance and Shared Flow</strong>
+ </p>
+ <p>
+ <a href="site:pageflow_inheritance">Page Flow
inheritance</a> provides a way to share actions,
+ exception handlers, state, etc. among controller
+ classes. This is just normal Java inheritance
used to
+ share pieces of controller classes.
+ </p>
+ <p>
+ <a href="site:pageflow_sharedFlow">Shared
Flow</a> provides an alternative way to make actions
+ and exception handlers available to multiple
page flows.
+ </p>
+ <p>
+ <strong>Nested Page Flows</strong>
+ </p>
+ <p>
+ An entire page flow can be inserted, or
"nested", inside
+ of another page flow. At its heart, nesting is
a way of
+ pushing aside the current page flow temporarily
and
+ transferring control to another (nested) page
flow with
+ the intention of coming back to the original
one.
+ Nesting is useful when you want to do one of the
+ following tasks:
+ </p>
+ <ul>
+ <li>
+ gather data from the user, for use in
the current
+ page flow;
+ </li>
+ <li>
+ allow the user to correct errors or
supply
+ additional information en route to
executing a
+ desired action;
+ </li>
+ <li>
+ show an alternate view of data
represented in the
+ current page flow;
+ </li>
+ <li>bring the user through a "wizard";</li>
+ <li>
+ show the user information that will be
useful in the
+ current page flow (e.g., help screens
can be easily
+ implemented as nested page flows); and
+ </li>
+ <li>
+ in general, to further break up your
application
+ into separate (and in many cases
reusable) pieces.
+ </li>
+ </ul>
+ <p>
+ NetUI also offers special integration between
nested
+ page flows and
+ <a href="site:pageflow_popups">popup
windows</a>.
+ </p>
+ <p>
+ <strong>
+ Declarative Exception Handling and
Validation
+ </strong>
+ </p>
+ <p>
+ Exception handling [TODO: link to topic] and
+ <a href="site:pageflow_valid">data
validation</a>
+ are accomplished through a declarative
programming
+ model. The desired exception handling and
validation
+ behaviors are declared in the "controller" class
+ alongside your Java code in the form of metadata
+ annotations. This allows for single file
editing and
+ eliminates the need for separate configuration
files.
+ </p>
+ <p>
+ <strong>Powerful JSP Tags</strong>
+ </p>
+ <p>
+ NetUI provides three <a
href="site:pageflow_tag_overview">tag libraries</a>: (1) one library
+ represents the core HTML tags, (2) another
renders data
+ grids and complex data sets as HTML, and (3) a
third
+ library provides page templating functionality.
+ </p>
+ <p>
+ The NetUI tags also support <a
href="site:databinding">data binding</a> (1) to JSP
+ implicit objects (through the JSP 2.0 Expression
+ Language) and (2) to other NetUI implicit
objects. Note
+ that many tags possess read-write access to
these
+ implicit objects.
+ </p>
+ <p>
+ <strong>
+ First-class Integration with JavaServer
Faces
+ </strong>
+ </p>
+ <p>
+ NetUI can co-exist with all <a href="site:pageflow_jsf">JavaServer
+ Faces</a> tags and features.
+ And NetUI and JSF are deeply integrated. For
example, JSF pages can raise NetUI actions
+ directly, JSF pages can databind to NetUI implicit objects, etc.
+ </p>
+ <p>
+ <strong>Struts Integration</strong>
+ </p>
+ <p>
+ Page Flow is built on top of Apache Struts 1.1.
Each
+ Page Flow controller is compiled into a Struts
module.
+ As a result, NetUI and Struts applications can
work
+ closely together.
+ </p>
+ <p>
+ Struts modules and page flows can co-habitate
and
+ interact with one another inside a web app. To
forward
+ from a page flow to a (pure) Struts module,
simply
+ reference the desired action within the Struts
module.
+ The same goes for the reverse direction: from a
Struts
+ module, simply configure an action to point to
the
+ desired method in the page flow.
+ <!--[todo: detailed doc based on R. Feit's:
http://dev2dev.bea.com/products/wlworkshop81/articles/Feit.jsp]-->
+ </p>
+ <p>
+ You can also use the Struts merge feature to
read
+ configuration data from a pure Struts app into
your Page
+ Flow app's configuration files. Ordinarily,
your Page
+ Flow's configuration files are generated
entirely from
+ your application's JAVA source files
(specifically from
+ the
+ <em>metadata annotations</em>
+ that decorate the controller classs). But, in
cases
+ where you want to integrate a Struts module
into your
+ application, you can specify that the
configuration
+ files be generated from
+ <em>both</em>
+ the JAVA source files
+ <em>and</em>
+ the Struts module's configuration files,
allowing you to
+ change or add
+ <em>any tag</em>
+ in the generated configuration file. For
example,
+ suppose you want to override an action form's
default
+ scoping from request-scoping to
session-scoping. To do
+ this, you simply create a Struts configuration
file that
+ overrides the appropriate parts of the Page
Flow's
+ configuration file, and then refer to this
override file
+ from within the Page Flow's JAVA source file (=
the
+ controller class) using a special annotation. In
+ particular, you would specify the override file
to state
+ that such-and-such an action form should have
+ session-scope rather then request-scope (so
that the
+ action form can now be shared with the Struts
app).
+ </p>
+ </section>
+ <section id="logical_flow">
+ <title>The Logical Flow</title>
+
+ <p>
+ Writing traditional web applications without a
Page Flow
+ controller class requires a fair amount of
logic to be
+ applied within the application's pages. For
example, a
+ site that provides a "My Page" functionality
for logged
+ in users would have to include logic on the
home page to
+ determine if the "My Page" link should take the
user to
+ the login form or directly to their customized
page.
+ </p>
+
+ <p>
+ Using a page flow, the home page of the
application
+ would not link directly to either the login page
+ <strong>or</strong>
+ the user's "My Page" location, but rather would
point
+ back into Java code that makes the decision.
+ </p>
+
+ <p>
+ For the rest of this overview, the following
+ <strong>logical page flow</strong>
+ will be used:
+ </p>
+
+ <p>
+ <img src="images/logical-flow-1.png"
+ alt="logical page flow" />
+ </p>
+
+ <p>
+ This flow supports several routes from the home
page of
+ the application to the user's "My Page":
+ </p>
+
+ <ol>
+ <li>
+ <p>
+ The user may directly navigate
from
+ <code>index.jsp</code>
+ to
+ <code>mypage.jsp</code>
+ (by clicking a link), if the
user is already
+ logged in.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the user is not already
logged in, attempts
+ to navigate from
+ <code>index.jsp</code>
+ to
+ <code>mypage.jsp</code>
+ will be intercepted and the
user will be taken
+ to the
+ <code>login.jsp</code>
+ instead. After successfully
logging in, the user
+ will be automatically taken to
+ <code>mypage.jsp</code>
+ </p>
+ </li>
+ <li>
+ <p>
+ The user may directly navigate
from
+ <code>index.jsp</code>
+ to
+ <code>login.jsp</code>
+ (by clicking a link). After
logging in, the user
+ will be automatically taken to
+ <code>mypage.jsp</code>
+ .
+ </p>
+
+ <p>
+ In the event of a login failure,
+ <code>login.jsp</code>
+ will be redisplayed to give
them another
+ opportunity to authenticate
themselves.
+ </p>
+ </li>
+ <li>
+ <p>
+ If the user desires to register
with the site,
+ he can click a link that will
take him to
+ <code>signup.jsp</code>
+ . One signed up, the
+ <code>thanks.jsp</code>
+ will be displayed which offers
a link to the
+ <code>login.jsp</code>
+ page.
+ </p>
+ </li>
+ </ol>
+
+ </section>
+
+ <section id="implementation_of_flow">
+ <title>
+ The Implementation of the Flow: Controllers and
Actions
+ </title>
+
+ <p>
+ In the above
+ <strong>logical flow</strong>
+ there are several
+ <em>if</em>
+ statements that cause the user flow to vary
depending on
+ their previous actions and other state.
+ </p>
+
+ <ul>
+ <li>
+ <em>If the user is not logged in...</em>
+ </li>
+ <li>
+ <em>If the user is logged in...</em>
+ </li>
+ <li>
+ <em>If the user's login attempt
fails...</em>
+ </li>
+ </ul>
+
+ <p>
+ NetUI moves this condition logic out of the
JSPs and
+ into a Java class that controls the movement
through the
+ application. This Java class is the
+ <strong>controller</strong>
+ portion of the
+ <strong>Model-View-Controller</strong>
+ (MVC) pattern. This allows a page to be
written, for
+ example, that appears to link directly from the
home
+ page of the application to the user's "My
Page". The
+ controller is given the opportunity to
intercept the
+ navigation between the two and redirect the
user to the
+ login page, if required.
+ </p>
+
+ <p>
+ Each of the interception points is an
+ <strong>action</strong>
+ of the particular controller class. Actions
perform
+ common application tasks. Here are some of the
things
+ that an action can do:
+ </p>
+
+ <ul>
+ <li>navigate the user to a specified JSP</li>
+ <li>perform conditional logic</li>
+ <li>handle submitted data</li>
+ <li>validate submitted data</li>
+ <li>handle exceptions that arise in the
application</li>
+ </ul>
+
+ <p>
+ Note that controller classes, and the actions
they
+ contain, are
+ <strong>URL addressable</strong>
+ . Hitting the following URL creates an instance
of the
+ controller class
+ <code>foo.MyControllerClass</code>
+ and runs its
+ <code>begin</code>
+ action. (When no other action is specified, the
+ <code>begin</code>
+ method is run by default.)
+ </p>
+
+
<source>http://some.domain.com/foo/MyControllerClass.java</source>
+
+ <p>
+ Hitting the following URL creates an instance of
+ <code>foo.MyControllerClass</code>
+ (if it doesn't already exist) and invokes the
+ <code>someAction</code>
+ action. Note that the controller class isn't
mentioned
+ by name: it's assumed that only one controller
class
+ exists in the directory, so there is only one
candidate
+ controller class to instantiate.
+ </p>
+
+
<source>http://some.domain.com/foo/someAction.do</source>
+ <note>
+ To make a Page Flow controller handle a default
+ directory URL, e.g.,
+ <br />
+ <br />
+
http://some.domain.com/myApp/myPageFlow
+ <br />
+ <br />
+ you will need to add the page flow's URL to the
+ <code>welcome-file-list</code>
+ in
+ <code>/WEB-INF/web.xml</code>
+ :
+ <br />
+ <br />
+ <welcome-file-list>
+ <br />
+
<welcome-file>Controller.jpf</welcome-file>
+ <br />
+
<welcome-file>index.jsp</welcome-file>
+ <br />
+ </welcome-file-list>
+ <br />
+ <br />
+ This would cause the following URL to be hit
for the
+ above example:
+ <br />
+ <br />
+
http://some.domain.com/myApp/myPageFlow/Controller.jpf
+ <br />
+ <br />
+ On some servers (like Tomcat), you would also
need to
+ make sure that a
+ <em>file</em>
+ called
+ <code>Controller.jpf</code>
+ also exists in the web content under
+ <code>/myPageFlow</code>
+ , even though the class
+ <code>myPageFlow.Controller</code>
+ actually handles the request. (The file can be
blank.)
+ </note>
+
+ <p>
+ Actions may perform any required complex logic.
For
+ example, if a user clicks on the "My Page"
link, the
+ action may check if the user is logged in, and
if so,
+ navigate the user to the
+ <code>mypage.jsp</code>
+ page; otherwise it will navigate the user to the
+ <code>login.jsp</code>
+ page.
+ </p>
+
+ <p>
+ With normal HTML pages, each page is linked
directly to
+ other pages.
+ </p>
+
+ <ul>
+ <li>
+ <strong>page > page > page >
page</strong>
+ </li>
+ </ul>
+
+ <p>
+ When using page flows, pages and actions are
interwoven,
+ transparently.
+ </p>
+
+ <ul>
+ <li>
+ <strong>
+ page > action > page >
action > page
+ > action > page
+ </strong>
+ </li>
+ </ul>
+
+ <p>
+ The above
+ <strong>logical page flow</strong>
+ can be redrawn with Page Flow controller
actions in
+ mind, as:
+ </p>
+
+ <p>
+ <img src="images/impl-flow-1.png"
+ alt="implementation page flow" />
+ </p>
+
+ <p>
+ Now it is apparent that to navigate from
+ <code>index.jsp</code>
+ to
+ <code>mypage.jsp</code>
+ , the user traverses across the
+ <code>myPage</code>
+ action. This action performs the necessary
check to
+ determine if the user has already been
authenticated. If
+ the user has logged in already, it will direct
the user
+ straight to
+ <code>mypage.jsp</code>
+ ; otherwise it will direct the user to
+ <code>login.jsp</code>
+ .
+ </p>
+ </section>
+ <section id="next">
+ <title>Next...</title>
+
+ <p>
+ Next, learn about writing a
+ <strong>controller</strong>
+ class with actions.
+ </p>
+
+ <ul>
+ <li>
+ <a class="jump"
href="site:pageflow_controllers">
+ Controller Classes</a>
+ </li>
+ </ul>
+ </section>
+ </body>
+ <footer>
+ <legal>
+ Java, J2EE, and JCP are trademarks or registered
trademarks
+ of Sun Microsystems, Inc. in the United States and other
+ countries.
+ <br />
+ © 2004, Apache Software Foundation
+ </legal>
+ </footer>
</document>
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowControllers.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowControllers.xml?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowControllers.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/pageFlowControllers.xml
Wed Aug 31 16:09:14 2005
@@ -13,7 +13,7 @@
This topic explains the basics behind implementing <strong>controller</strong> files and
<strong>actions</strong>.
As introduced in the previous topic (<a href="site:pageflow_overview">NetUI
Overview</a>) the
- following model will be used.
+ following web application schematic will be used.
</p>
<p>
@@ -29,27 +29,23 @@
named <code>Controller.java</code>.
</p>
-<source>
-<strong>public class Controller
+<source><strong>public class Controller
{
-}</strong>
-</source>
+}</strong></source>
-<source>
-<strong>import org.apache.beehive.netui.pageflow.PageFlowController;</strong>
+<source><strong>import
org.apache.beehive.netui.pageflow.PageFlowController;</strong>
public class Controller
<strong>extends PageFlowController</strong>
{
-}
-</source>
+}</source>
<p>
- Additionally, Beehive weaves magic into controller classes using
annotations.
- The <code>Jpf.Controller</code> annotation is a required marker on your
- own controller class. The <code>jpf</code> annotation alerts the
- build that this class is a special Page Flow controller class, instead of
a typical
+ Additionally, Beehive weaves magic into controller classes using metadata
annotations.
+ The <code>Jpf.Controller</code> annotation is a required marker on any NetUI
+ controller class. The <code>@Jpf</code> annotation alerts the
+ compiler that this class is a special Page Flow controller class, instead
of a typical
Java class.
</p>
@@ -136,7 +132,7 @@
</a>
annotation:
</p>
- <source> <strong>@Jpf.Action</strong>(
+ <source><strong>@Jpf.Action</strong>(
forwards = {
<strong>@Jpf.Forward( name="someName", path="somePath.jsp", <em>[...other
properties...]</em> )</strong>
}
@@ -175,8 +171,8 @@
@Jpf.SimpleAction(name="begin", path="index.jsp"),
@Jpf.SimpleAction(name="login", path="login.jsp"),
@Jpf.SimpleAction(name="signUp", path="signup.jsp"),
- }
-)</strong>
+ }</strong>
+)
public class Controller
extends PageFlowController
{
@@ -231,8 +227,7 @@
display to the user.
</p>
-<source>
-<strong>import org.apache.beehive.netui.pageflow.Forward;</strong>
+<source><strong>import org.apache.beehive.netui.pageflow.Forward;</strong>
import org.apache.beehive.netui.pageflow.PageFlowController;
import org.apache.beehive.netui.pageflow.annotations.Jpf;
@@ -632,8 +627,7 @@
<code>@Jpf.ExceptionHandler</code>
</a>
annotation is used to define a dedicated method for handling the
exception.</p>
- <source>
[EMAIL PROTECTED](
+ <source>@Jpf.Controller(
<strong>catches={
@Jpf.Catch(type=AccountAlreadyExistsException.class,
method="handleAccountAlreadyExistsException")
}</strong>,
@@ -662,9 +656,7 @@
<p>To protect a method with this error handling system, you only need to specify that the method throws the
appropriate sort of exception, in this case, <code>AccountAlreadyExistsException</code>.</p>
- <source>
-
[EMAIL PROTECTED](
+ <source>@Jpf.Controller(
catches={
@Jpf.Catch(method="handleAccountAlreadyExistsException",
type=AccountAlreadyExistsException.class)
},
@@ -711,7 +703,7 @@
</p>
<ul>
- <li><a href="site:pageflow_jsp">Page Flow JSP</a></li>
+ <li><a href="site:pageflow_jsp">JSP Files</a></li>
</ul>
</section>
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
Wed Aug 31 16:09:14 2005
@@ -2,7 +2,7 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
"http://forrest.apache.org/dtd/document-v20.dtd";>
<document>
<header>
- <title>Building a NetUI Web Project</title>
+ <title>NetUI Web App Project Model</title>
</header>
<body>
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
(original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
Wed Aug 31 16:09:14 2005
@@ -15,7 +15,7 @@
<pageflow label="NetUI">
<netuiIntro label="Introduction">
<pageflow_getting_started label="Getting Started"
href="netui/getting_started.html"/>
- <pageflow_overview label="Overview"
href="netui/overview.html"/>
+ <pageflow_overview label="Netui Overview"
href="netui/overview.html"/>
<pageflow_controllers label="Controller Classes"
href="netui/pageFlowControllers.html"/>
<pageflow_jsp label="JSP Files" href="netui/jspOverview.html">
<pageflow_jspOverview_SimpleLinking href="#SimpleLinking" />
@@ -73,7 +73,7 @@
<pageflow_advanced label="Advanced Topics">
<pageflow_inheritance label="Inheritance"
href="netui/pageFlowInheritance.html"/>
<pageflow_sharedFlow label="Shared Flow"
href="netui/sharedFlow.html"/>
- <pageflow_sharedFlowVsInheritance
href="netui/sharedFlow_vs_inheritance.html"/>
+ <pageflow_sharedFlowVsInheritance label="Shared Flow vs. Inheritance"
href="netui/sharedFlow_vs_inheritance.html"/>
<pageflow_popups label="Popup Windows"
href="netui/popupWindows.html"/>
<pageflow_servlet_adapter label="Servlet Container Adapters"
href="netui/servlet_container_adapters.html"/>
<devmode label="Development Mode" href="netui/dev_mode.html"/>
Modified: beehive/trunk/docs/how_to_contribute_docs.txt
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/how_to_contribute_docs.txt?rev=265602&r1=265601&r2=265602&view=diff
==============================================================================
--- beehive/trunk/docs/how_to_contribute_docs.txt (original)
+++ beehive/trunk/docs/how_to_contribute_docs.txt Wed Aug 31 16:09:14 2005
@@ -100,11 +100,11 @@
release / site documentation builds succeed successfully. To ensure that the
release build succeeds, run:
- docs/forrest/release> ant build.release
+ docs/forrest> ant build.release
To ensure that the website build succeeds, run:
- docs/forrest/site> ant build.site
+ docs/forrest> ant build.site
Additional instructions for editing the website are included below.
