You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by st...@apache.org on 2005/09/01 01:09:20 UTC
svn commit: r265602 - in /beehive/trunk/docs: ./
forrest/release/src/documentation/content/xdocs/
forrest/release/src/documentation/content/xdocs/controls/
forrest/release/src/documentation/content/xdocs/netui/
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>
-@Jpf.Controller(
+ <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>
-
-@Jpf.Controller(
+ <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.
Re: "Web App" vs. "Web Project"
Posted by Steve Hanson <st...@gmail.com>.
To my ear, "Web Project" and "Webapp" don't sound like the same thing.
"Web Project" sounds like a nascent Webapp -- its some minimal set of
components that you fill out to make it into a full blown Webapp.
On 8/31/05, Daryl Olander <do...@gmail.com> wrote:
>
> I've been using WebApp, just to be an odd ball.....What do we call the
> thing
> that is a .war, I think of that as a webapp (expanded or in .war format).
> Matches the Tomcat webapps directory....
>
> On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
> >
> > Yeah, I could go either way, but I like Web Project as well when
> > referring to the project structure.
> >
> > Eddie
> >
> >
> >
> > On 8/31/05, Rich Feit <ri...@gmail.com> wrote:
> > > Another thing...
> > >
> > > I think we need to standardize on a term for this. I think it can be:
> > >
> > > - "Web Project", or
> > > - "Webapp"
> > >
> > > It should not be "Web App", though. Any thoughts on which one? I like
> > > "Web Project" better, especially because it dovetails with terminology
> > > in IDE land.
> > >
> > > Rich
> > >
> >
>
>
Re: "Web App" vs. "Web Project"
Posted by Daryl Olander <do...@gmail.com>.
I've been using WebApp, just to be an odd ball.....What do we call the thing
that is a .war, I think of that as a webapp (expanded or in .war format).
Matches the Tomcat webapps directory....
On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
>
> Yeah, I could go either way, but I like Web Project as well when
> referring to the project structure.
>
> Eddie
>
>
>
> On 8/31/05, Rich Feit <ri...@gmail.com> wrote:
> > Another thing...
> >
> > I think we need to standardize on a term for this. I think it can be:
> >
> > - "Web Project", or
> > - "Webapp"
> >
> > It should not be "Web App", though. Any thoughts on which one? I like
> > "Web Project" better, especially because it dovetails with terminology
> > in IDE land.
> >
> > Rich
> >
>
Re: "Web App" vs. "Web Project"
Posted by Eddie O'Neil <ek...@gmail.com>.
Yeah, I could go either way, but I like Web Project as well when
referring to the project structure.
Eddie
On 8/31/05, Rich Feit <ri...@gmail.com> wrote:
> Another thing...
>
> I think we need to standardize on a term for this. I think it can be:
>
> - "Web Project", or
> - "Webapp"
>
> It should not be "Web App", though. Any thoughts on which one? I like
> "Web Project" better, especially because it dovetails with terminology
> in IDE land.
>
> Rich
>
> steveh@apache.org wrote:
>
> >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>
> >-@Jpf.Controller(
> >+ <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>
> >-
> >-@Jpf.Controller(
> >+ <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.
> >
> >
> >
> >
> >
> >
>
>
>
"Web App" vs. "Web Project"
Posted by Rich Feit <ri...@gmail.com>.
Another thing...
I think we need to standardize on a term for this. I think it can be:
- "Web Project", or
- "Webapp"
It should not be "Web App", though. Any thoughts on which one? I like
"Web Project" better, especially because it dovetails with terminology
in IDE land.
Rich
steveh@apache.org wrote:
>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>
>-@Jpf.Controller(
>+ <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>
>-
>-@Jpf.Controller(
>+ <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.
>
>
>
>
>
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Daryl Olander <do...@gmail.com>.
I actually do this a lot. A lot of links inside of documents don't have
labels. I also have some top level things that are not part of the doc tree.
On 8/31/05, Rich Feit <ri...@gmail.com> wrote:
>
> Hey Steve,
>
> Just a minor point: there are a few nodes in site.xml that have no
> label. This is intentional; it allows linking to them using
> href="site:...", without having them appear in the tree. I'm going to
> revert a few changes to that file...
>
> Rich
>
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/
forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Rich Feit <ri...@gmail.com>.
Hey Steve,
Just a minor point: there are a few nodes in site.xml that have no
label. This is intentional; it allows linking to them using
href="site:...", without having them appear in the tree. I'm going to
revert a few changes to that file...
Rich
steveh@apache.org wrote:
>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>
>-@Jpf.Controller(
>+ <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>
>-
>-@Jpf.Controller(
>+ <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.
>
>
>
>
>
>
Re: Fwd: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Daryl Olander <do...@gmail.com>.
+1 to 100 to 120
On 8/31/05, Rich Feit <ri...@gmail.com> wrote:
>
> One other thing to add to this...
>
> Let's choose a target right-margin location for doc files. I personally
> think 80 characters is ridiculous and would advocate 100 or more... but
> would be most happy if we all agreed on a single value (even 80 if
> others want it), so that reformatting doesn't make diffing files
> impossible.
>
> Ideas on this one?
>
> Rich
>
> Eddie O'Neil wrote:
>
> >Steve--
> >
> > Great to have some "professional" edits to the documentation. :)
> >
> > A few comments on some of the changes made here which we might take
> >a closer look at:
> >
> >1) I think your editor is tab-ifying some of the documentation. We're
> >standardized on using four spaces rather than tabs for the doc. This
> >happened at least in xdocs/netui/overview.xml
> >
> >2) unless there is formatting (like <strong>) that is used inside of
> >JSP content, it's much easier to write documentation using "<"
> >characters than <. This makes copy/paste from samples simpler
> >
> >3) when referring to NetUI, we tend to use the term "NetUI" rather
> >than "Netui". This happened in the labels in site.xml. Also, in this
> >case, it seems like we can call the NetUI Overview section just
> >"Overview" since it's under the NetUI tab already. I've tried to
> >remove some of that reduncancy from the docs in recent weeks.
> >
> > Thoughts?
> >
> >Eddie
> >
> >On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
> >
> >
> >>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
> >>
> >>
> >
> >
> >
>
Re: Fwd: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/
forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Rich Feit <ri...@gmail.com>.
One other thing to add to this...
Let's choose a target right-margin location for doc files. I personally
think 80 characters is ridiculous and would advocate 100 or more... but
would be most happy if we all agreed on a single value (even 80 if
others want it), so that reformatting doesn't make diffing files impossible.
Ideas on this one?
Rich
Eddie O'Neil wrote:
>Steve--
>
> Great to have some "professional" edits to the documentation. :)
>
> A few comments on some of the changes made here which we might take
>a closer look at:
>
>1) I think your editor is tab-ifying some of the documentation. We're
>standardized on using four spaces rather than tabs for the doc. This
>happened at least in xdocs/netui/overview.xml
>
>2) unless there is formatting (like <strong>) that is used inside of
>JSP content, it's much easier to write documentation using "<"
>characters than <. This makes copy/paste from samples simpler
>
>3) when referring to NetUI, we tend to use the term "NetUI" rather
>than "Netui". This happened in the labels in site.xml. Also, in this
>case, it seems like we can call the NetUI Overview section just
>"Overview" since it's under the NetUI tab already. I've tried to
>remove some of that reduncancy from the docs in recent weeks.
>
> Thoughts?
>
>Eddie
>
>On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
>
>
>>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
>>
>>
>
>
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/
forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Rich Feit <ri...@gmail.com>.
Fine with me (+0). I was an original proponent of non-conflicting names
(*not* long names based on the hierarchy FTR), but this is OK. I'm an
ace at ed/sed for times where we change the structure. :) I've edited
the doc at http://wiki.apache.org/beehive/DocConventions .
Rich
Eddie O'Neil wrote:
> +1 from me. :)
>
> I might take a crack at fixing this before we branch, but it would
>be *just* before the branch. Just so it's taken care of in both a 1.0
>branch and trunk/. It's really an implementation detail (doesn't
>surface in the URLs on the public site), so it's not a big deal either
>way.
>
>Eddie
>
>
>
>On 9/1/05, Daryl Olander <do...@gmail.com> wrote:
>
>
>>I agree with Eddie on the "navigate the document top-down" philosophy. I've
>>confirmed that XPath does work correctly. So today, we have "site:datagrid"
>>and this should become"site:NetUI/tags/datagrid ". (I renamed the
>>pageflow_tags element to tags in this example. This "site:" example was
>>found in the tagOverview.xml).
>>
>>Having said this, I think this should be a long run goal and that we don't
>>change the site.xml and matching "site:xxx" hrefs until post 1.0. I'm going
>>to check in the one sample from above as proof that it works, but the rest
>>of the clean should wait.
>>
>>Thoughts?
>>
>>
>>On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
>>
>>
>>>I prefer using site.xml to navigate the document top-down instead of
>>>using unique names for each element. At some point, those unique
>>>names become hard to maintain unless they're fully-qualified names
>>>which is basically the XPath to the element through site.xml. So I
>>>prefer this:
>>>
>>><netui>
>>><databinding>
>>>
>>>refernced with "site:netui/databinding" to this:
>>>
>>><netui>
>>><netui_databinding>
>>>
>>>which can be referred to as "site:netui_databinding".
>>>
>>>But, I'm not religious about this -- just don't like having to repeat
>>>"netui" twice in the config file's structure and names.
>>>
>>>For line numbers, I'd prefer 120 but could live with 100. 80 is
>>>just way too 1980's. :)
>>>
>>>To Steve's questions, "PageFlow" seems right, though that is part of
>>>NetUI which includes Page Flow, the JSP tags, and other technologies
>>>that are surely yet to come. The use of "controller class" vs.
>>>"Controller class" seems like a it depends on context. But, I don't
>>>have strong feelings here either.
>>>
>>>My $0.02...
>>>
>>>Eddie
>>>
>>>
>>>
>>>
>>>On 8/31/05, Steve Hanson <st...@gmail.com> wrote:
>>>
>>>
>>>>As for the tabification, I hit Ctrl+F in Eclipse at one point by
>>>>
>>>>
>>>accident,
>>>
>>>
>>>>that is probably the culprit. I will check the indent style on my
>>>>
>>>>
>>>Eclipse
>>>
>>>
>>>>editor.
>>>>
>>>>I have endeavored to avoid < wherever I can -- but I see no way to
>>>>
>>>>
>>>avoid
>>>
>>>
>>>>it when you want to display angle brackets in bold font.
>>>>
>>>>I have some questions of my own:
>>>>Should it be "Page Flow" or "Page Flow"? I am neutral on this question.
>>>>Should it be "Controller class" or "controller class"? I have a slight
>>>>preference for "Controller class", since it suggests a reference to a
>>>>
>>>>
>>>Java
>>>
>>>
>>>>class.
>>>>
>>>>On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
>>>>
>>>>
>>>>>Steve--
>>>>>
>>>>>Great to have some "professional" edits to the documentation. :)
>>>>>
>>>>>A few comments on some of the changes made here which we might take
>>>>>a closer look at:
>>>>>
>>>>>1) I think your editor is tab-ifying some of the documentation. We're
>>>>>standardized on using four spaces rather than tabs for the doc. This
>>>>>happened at least in xdocs/netui/overview.xml
>>>>>
>>>>>2) unless there is formatting (like <strong>) that is used inside of
>>>>>JSP content, it's much easier to write documentation using "<"
>>>>>characters than <. This makes copy/paste from samples simpler
>>>>>
>>>>>3) when referring to NetUI, we tend to use the term "NetUI" rather
>>>>>than "Netui". This happened in the labels in site.xml. Also, in this
>>>>>case, it seems like we can call the NetUI Overview section just
>>>>>"Overview" since it's under the NetUI tab already. I've tried to
>>>>>remove some of that reduncancy from the docs in recent weeks.
>>>>>
>>>>>Thoughts?
>>>>>
>>>>>Eddie
>>>>>
>>>>>On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
>>>>>
>>>>>
>>>>>>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
>>>
>>>
>>>>
>>>>
>>
>>
>
>
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Eddie O'Neil <ek...@gmail.com>.
+1 from me. :)
I might take a crack at fixing this before we branch, but it would
be *just* before the branch. Just so it's taken care of in both a 1.0
branch and trunk/. It's really an implementation detail (doesn't
surface in the URLs on the public site), so it's not a big deal either
way.
Eddie
On 9/1/05, Daryl Olander <do...@gmail.com> wrote:
> I agree with Eddie on the "navigate the document top-down" philosophy. I've
> confirmed that XPath does work correctly. So today, we have "site:datagrid"
> and this should become"site:NetUI/tags/datagrid ". (I renamed the
> pageflow_tags element to tags in this example. This "site:" example was
> found in the tagOverview.xml).
>
> Having said this, I think this should be a long run goal and that we don't
> change the site.xml and matching "site:xxx" hrefs until post 1.0. I'm going
> to check in the one sample from above as proof that it works, but the rest
> of the clean should wait.
>
> Thoughts?
>
>
> On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
> >
> > I prefer using site.xml to navigate the document top-down instead of
> > using unique names for each element. At some point, those unique
> > names become hard to maintain unless they're fully-qualified names
> > which is basically the XPath to the element through site.xml. So I
> > prefer this:
> >
> > <netui>
> > <databinding>
> >
> > refernced with "site:netui/databinding" to this:
> >
> > <netui>
> > <netui_databinding>
> >
> > which can be referred to as "site:netui_databinding".
> >
> > But, I'm not religious about this -- just don't like having to repeat
> > "netui" twice in the config file's structure and names.
> >
> > For line numbers, I'd prefer 120 but could live with 100. 80 is
> > just way too 1980's. :)
> >
> > To Steve's questions, "PageFlow" seems right, though that is part of
> > NetUI which includes Page Flow, the JSP tags, and other technologies
> > that are surely yet to come. The use of "controller class" vs.
> > "Controller class" seems like a it depends on context. But, I don't
> > have strong feelings here either.
> >
> > My $0.02...
> >
> > Eddie
> >
> >
> >
> >
> > On 8/31/05, Steve Hanson <st...@gmail.com> wrote:
> > > As for the tabification, I hit Ctrl+F in Eclipse at one point by
> > accident,
> > > that is probably the culprit. I will check the indent style on my
> > Eclipse
> > > editor.
> > >
> > > I have endeavored to avoid < wherever I can -- but I see no way to
> > avoid
> > > it when you want to display angle brackets in bold font.
> > >
> > > I have some questions of my own:
> > > Should it be "Page Flow" or "Page Flow"? I am neutral on this question.
> > > Should it be "Controller class" or "controller class"? I have a slight
> > > preference for "Controller class", since it suggests a reference to a
> > Java
> > > class.
> > >
> > > On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
> > > >
> > > > Steve--
> > > >
> > > > Great to have some "professional" edits to the documentation. :)
> > > >
> > > > A few comments on some of the changes made here which we might take
> > > > a closer look at:
> > > >
> > > > 1) I think your editor is tab-ifying some of the documentation. We're
> > > > standardized on using four spaces rather than tabs for the doc. This
> > > > happened at least in xdocs/netui/overview.xml
> > > >
> > > > 2) unless there is formatting (like <strong>) that is used inside of
> > > > JSP content, it's much easier to write documentation using "<"
> > > > characters than <. This makes copy/paste from samples simpler
> > > >
> > > > 3) when referring to NetUI, we tend to use the term "NetUI" rather
> > > > than "Netui". This happened in the labels in site.xml. Also, in this
> > > > case, it seems like we can call the NetUI Overview section just
> > > > "Overview" since it's under the NetUI tab already. I've tried to
> > > > remove some of that reduncancy from the docs in recent weeks.
> > > >
> > > > Thoughts?
> > > >
> > > > Eddie
> > > >
> > > > On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
> > > > > 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
> > > >
> > >
> > >
> >
>
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Daryl Olander <do...@gmail.com>.
I agree with Eddie on the "navigate the document top-down" philosophy. I've
confirmed that XPath does work correctly. So today, we have "site:datagrid"
and this should become"site:NetUI/tags/datagrid ". (I renamed the
pageflow_tags element to tags in this example. This "site:" example was
found in the tagOverview.xml).
Having said this, I think this should be a long run goal and that we don't
change the site.xml and matching "site:xxx" hrefs until post 1.0. I'm going
to check in the one sample from above as proof that it works, but the rest
of the clean should wait.
Thoughts?
On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
>
> I prefer using site.xml to navigate the document top-down instead of
> using unique names for each element. At some point, those unique
> names become hard to maintain unless they're fully-qualified names
> which is basically the XPath to the element through site.xml. So I
> prefer this:
>
> <netui>
> <databinding>
>
> refernced with "site:netui/databinding" to this:
>
> <netui>
> <netui_databinding>
>
> which can be referred to as "site:netui_databinding".
>
> But, I'm not religious about this -- just don't like having to repeat
> "netui" twice in the config file's structure and names.
>
> For line numbers, I'd prefer 120 but could live with 100. 80 is
> just way too 1980's. :)
>
> To Steve's questions, "PageFlow" seems right, though that is part of
> NetUI which includes Page Flow, the JSP tags, and other technologies
> that are surely yet to come. The use of "controller class" vs.
> "Controller class" seems like a it depends on context. But, I don't
> have strong feelings here either.
>
> My $0.02...
>
> Eddie
>
>
>
>
> On 8/31/05, Steve Hanson <st...@gmail.com> wrote:
> > As for the tabification, I hit Ctrl+F in Eclipse at one point by
> accident,
> > that is probably the culprit. I will check the indent style on my
> Eclipse
> > editor.
> >
> > I have endeavored to avoid < wherever I can -- but I see no way to
> avoid
> > it when you want to display angle brackets in bold font.
> >
> > I have some questions of my own:
> > Should it be "Page Flow" or "Page Flow"? I am neutral on this question.
> > Should it be "Controller class" or "controller class"? I have a slight
> > preference for "Controller class", since it suggests a reference to a
> Java
> > class.
> >
> > On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
> > >
> > > Steve--
> > >
> > > Great to have some "professional" edits to the documentation. :)
> > >
> > > A few comments on some of the changes made here which we might take
> > > a closer look at:
> > >
> > > 1) I think your editor is tab-ifying some of the documentation. We're
> > > standardized on using four spaces rather than tabs for the doc. This
> > > happened at least in xdocs/netui/overview.xml
> > >
> > > 2) unless there is formatting (like <strong>) that is used inside of
> > > JSP content, it's much easier to write documentation using "<"
> > > characters than <. This makes copy/paste from samples simpler
> > >
> > > 3) when referring to NetUI, we tend to use the term "NetUI" rather
> > > than "Netui". This happened in the labels in site.xml. Also, in this
> > > case, it seems like we can call the NetUI Overview section just
> > > "Overview" since it's under the NetUI tab already. I've tried to
> > > remove some of that reduncancy from the docs in recent weeks.
> > >
> > > Thoughts?
> > >
> > > Eddie
> > >
> > > On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
> > > > 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
> > >
> >
> >
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Eddie O'Neil <ek...@gmail.com>.
I prefer using site.xml to navigate the document top-down instead of
using unique names for each element. At some point, those unique
names become hard to maintain unless they're fully-qualified names
which is basically the XPath to the element through site.xml. So I
prefer this:
<netui>
<databinding>
refernced with "site:netui/databinding" to this:
<netui>
<netui_databinding>
which can be referred to as "site:netui_databinding".
But, I'm not religious about this -- just don't like having to repeat
"netui" twice in the config file's structure and names.
For line numbers, I'd prefer 120 but could live with 100. 80 is
just way too 1980's. :)
To Steve's questions, "PageFlow" seems right, though that is part of
NetUI which includes Page Flow, the JSP tags, and other technologies
that are surely yet to come. The use of "controller class" vs.
"Controller class" seems like a it depends on context. But, I don't
have strong feelings here either.
My $0.02...
Eddie
On 8/31/05, Steve Hanson <st...@gmail.com> wrote:
> As for the tabification, I hit Ctrl+F in Eclipse at one point by accident,
> that is probably the culprit. I will check the indent style on my Eclipse
> editor.
>
> I have endeavored to avoid < wherever I can -- but I see no way to avoid
> it when you want to display angle brackets in bold font.
>
> I have some questions of my own:
> Should it be "Page Flow" or "Page Flow"? I am neutral on this question.
> Should it be "Controller class" or "controller class"? I have a slight
> preference for "Controller class", since it suggests a reference to a Java
> class.
>
> On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
> >
> > Steve--
> >
> > Great to have some "professional" edits to the documentation. :)
> >
> > A few comments on some of the changes made here which we might take
> > a closer look at:
> >
> > 1) I think your editor is tab-ifying some of the documentation. We're
> > standardized on using four spaces rather than tabs for the doc. This
> > happened at least in xdocs/netui/overview.xml
> >
> > 2) unless there is formatting (like <strong>) that is used inside of
> > JSP content, it's much easier to write documentation using "<"
> > characters than <. This makes copy/paste from samples simpler
> >
> > 3) when referring to NetUI, we tend to use the term "NetUI" rather
> > than "Netui". This happened in the labels in site.xml. Also, in this
> > case, it seems like we can call the NetUI Overview section just
> > "Overview" since it's under the NetUI tab already. I've tried to
> > remove some of that reduncancy from the docs in recent weeks.
> >
> > Thoughts?
> >
> > Eddie
> >
> > On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
> > > 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
> >
>
>
doc conventions on the wiki (was: Re: svn commit: r265602 ...)
Posted by Richard Feit <ri...@bea.com>.
I just added a Documentation Conventions page to the wiki. I feel like
the easiest thing to do is to put votes by each item on that page,
rather than have a separate mail thread for each one. Does this sound OK?
http://wiki.apache.org/beehive/DocConventions
Rich
Steve Hanson wrote:
>As for the tabification, I hit Ctrl+F in Eclipse at one point by accident,
>that is probably the culprit. I will check the indent style on my Eclipse
>editor.
>
>I have endeavored to avoid < wherever I can -- but I see no way to avoid
>it when you want to display angle brackets in bold font.
>
>I have some questions of my own:
>Should it be "Page Flow" or "Page Flow"? I am neutral on this question.
>Should it be "Controller class" or "controller class"? I have a slight
>preference for "Controller class", since it suggests a reference to a Java
>class.
>
>On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
>
>
>>Steve--
>>
>>Great to have some "professional" edits to the documentation. :)
>>
>>A few comments on some of the changes made here which we might take
>>a closer look at:
>>
>>1) I think your editor is tab-ifying some of the documentation. We're
>>standardized on using four spaces rather than tabs for the doc. This
>>happened at least in xdocs/netui/overview.xml
>>
>>2) unless there is formatting (like <strong>) that is used inside of
>>JSP content, it's much easier to write documentation using "<"
>>characters than <. This makes copy/paste from samples simpler
>>
>>3) when referring to NetUI, we tend to use the term "NetUI" rather
>>than "Netui". This happened in the labels in site.xml. Also, in this
>>case, it seems like we can call the NetUI Overview section just
>>"Overview" since it's under the NetUI tab already. I've tried to
>>remove some of that reduncancy from the docs in recent weeks.
>>
>>Thoughts?
>>
>>Eddie
>>
>>On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
>>
>>
>>>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
>>
>>
>>
>
>
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Steve Hanson <st...@gmail.com>.
As for the tabification, I hit Ctrl+F in Eclipse at one point by accident,
that is probably the culprit. I will check the indent style on my Eclipse
editor.
I have endeavored to avoid < wherever I can -- but I see no way to avoid
it when you want to display angle brackets in bold font.
I have some questions of my own:
Should it be "Page Flow" or "Page Flow"? I am neutral on this question.
Should it be "Controller class" or "controller class"? I have a slight
preference for "Controller class", since it suggests a reference to a Java
class.
On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
>
> Steve--
>
> Great to have some "professional" edits to the documentation. :)
>
> A few comments on some of the changes made here which we might take
> a closer look at:
>
> 1) I think your editor is tab-ifying some of the documentation. We're
> standardized on using four spaces rather than tabs for the doc. This
> happened at least in xdocs/netui/overview.xml
>
> 2) unless there is formatting (like <strong>) that is used inside of
> JSP content, it's much easier to write documentation using "<"
> characters than <. This makes copy/paste from samples simpler
>
> 3) when referring to NetUI, we tend to use the term "NetUI" rather
> than "Netui". This happened in the labels in site.xml. Also, in this
> case, it seems like we can call the NetUI Overview section just
> "Overview" since it's under the NetUI tab already. I've tried to
> remove some of that reduncancy from the docs in recent weeks.
>
> Thoughts?
>
> Eddie
>
> On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
> > 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
>
Re: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Daryl Olander <do...@gmail.com>.
I've been giving everything a unique name. I actually don't like the
"databinding" inside of "netui" in site.xml. I think we should try an make
these unique or use real xpath expressions in our hrefs. Things like
"databinding" and "overview" are pretty generic. I think if we go to the
generic terms we have to rework our "site:" expressions to put in the proper
xpath, but I'm not sure that Forrest supports real xpath expressions in the
"site:xxx", but I believe it does. I don't see something like
("site:/netui/databinding") instead we are using ("site:databinding") which
seems like it will break at some point.
On 8/31/05, Eddie O'Neil <ek...@gmail.com> wrote:
>
> Steve--
>
> Great to have some "professional" edits to the documentation. :)
>
> A few comments on some of the changes made here which we might take
> a closer look at:
>
> 1) I think your editor is tab-ifying some of the documentation. We're
> standardized on using four spaces rather than tabs for the doc. This
> happened at least in xdocs/netui/overview.xml
>
> 2) unless there is formatting (like <strong>) that is used inside of
> JSP content, it's much easier to write documentation using "<"
> characters than <. This makes copy/paste from samples simpler
>
> 3) when referring to NetUI, we tend to use the term "NetUI" rather
> than "Netui". This happened in the labels in site.xml. Also, in this
> case, it seems like we can call the NetUI Overview section just
> "Overview" since it's under the NetUI tab already. I've tried to
> remove some of that reduncancy from the docs in recent weeks.
>
> Thoughts?
>
> Eddie
>
> On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
> > 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
>
Fwd: svn commit: r265602 - in /beehive/trunk/docs: ./ forrest/release/src/documentation/content/xdocs/ forrest/release/src/documentation/content/xdocs/controls/ forrest/release/src/documentation/content/xdocs/netui/
Posted by Eddie O'Neil <ek...@gmail.com>.
Steve--
Great to have some "professional" edits to the documentation. :)
A few comments on some of the changes made here which we might take
a closer look at:
1) I think your editor is tab-ifying some of the documentation. We're
standardized on using four spaces rather than tabs for the doc. This
happened at least in xdocs/netui/overview.xml
2) unless there is formatting (like <strong>) that is used inside of
JSP content, it's much easier to write documentation using "<"
characters than <. This makes copy/paste from samples simpler
3) when referring to NetUI, we tend to use the term "NetUI" rather
than "Netui". This happened in the labels in site.xml. Also, in this
case, it seems like we can call the NetUI Overview section just
"Overview" since it's under the NetUI tab already. I've tried to
remove some of that reduncancy from the docs in recent weeks.
Thoughts?
Eddie
On 8/31/05, steveh@apache.org <st...@apache.org> wrote:
> 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