<?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>Nested Page Flows</title>
    </header>
    <body>
        <section id="intro">
            <title>Introduction</title>
            <p>
                By default, executing an action in a new page flow causes the current page flow to be discarded. This
                behavior allows you to create separate controllers for different sections of your project, and it
                minimizes the amount of data kept in the user session at one time. Each page flow manages its own state
                and logic. "Nested page flows" give you an even greater ability to break up your project into separate,
                self-contained bits of functionality. At its heart, "nesting" is a way of pushing aside the current
                page flow temporarily and transferring control to another page flow with the intention of coming back
                to the original one.
            </p>
            <p>
                So when would you use this? 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>
        </section>
        <section id="basics">
            <title>Basics</title>
            <p> 
                Let's start with a very simple example. You can find the code for this under <code>basicNesting</code>
                in the <a href="site:docs/samples/netui-samples">NetUI Samples</a> application. Here, we have a "main"
                page flow which forwards to a nested page flow, which later returns to the main page flow.  The flow
                looks like this:
            </p>
            <p>
                <img src="images/netui/nestedPageFlow/basicNestingMain.gif" alt="main page flow"/>
            </p>
            <p>
                Here is the code for the main page flow:
            </p>
            <source>
@Jpf.Controller(
    simpleActions={
        @Jpf.SimpleAction(name="begin", path="index.jsp"),
        @Jpf.SimpleAction(name="goNested", path="../nested/NestedFlow.jpf"),
        @Jpf.SimpleAction(name="nestedDone", path="success.jsp")
    }
)
public class MainFlow extends PageFlowController
{
}           </source>
            <p>
                As you can see, the <code>begin</code> action forwards to <code>index.jsp</code>, which allows you to
                raise the <code>goNested</code> action. This action enters the nested page flow <em>simply by
                forwarding to it</em>. Any time you hit the URL for a nested page flow (or any one of its actions or
                pages), you enter the nested page flow, and the current one is pushed aside.
            </p>
            <p>
                When the nested page flow returns, it causes the <code>nestedDone</code> action to run, and this action
                simply forwards to <code>success.jsp</code>
            </p>
            <p>
                So how does the nested page flow return to the current one, and raise the <code>nestedDone</code>
                action? Here is the code for the nested flow:
            </p>
            <source>
@Jpf.Controller(
    <strong>nested=true</strong>,
    simpleActions={
        @Jpf.SimpleAction(name="begin", path="index.jsp"),
        @Jpf.SimpleAction(name="done", <strong>returnAction="nestedDone"</strong>)
    }
)
public class NestedFlow extends PageFlowController
{
}           </source>
            <p>
                Note the
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html#nested()">
                    <code>nested</code>
                </a>=<code>true</code>,
                which defines this as a nested page flow. Also note the
                <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html#returnAction()">
                    <code>returnAction</code>
                </a>
                attribute on the simple action <code>done</code>.  When this action is executed, it returns to the
                original page flow (<code>MainFlow</code>) and raises its <code>nestedDone</code> action.  This is
                called an <strong>exit point</strong> of the nested page flow.
            </p>
            <p>
                The nested flow looks like this:
            </p>
            <p>
                <img src="images/netui/nestedPageFlow/basicNestingNested.gif" alt="nested page flow"/>
            </p>
        </section>
        <section id="moreFeatures">
            <title>More Nested Page Flow Features</title>
            <p>
                Often, you want to do more than simply invoke and return from a nested page flow.  For instance, you may
                want to gather data from a nested page flow, for use in the current page flow. In the example below
                (found under <code>nesting</code> in the <a href="site:docs/samples/netui-samples">NetUI Samples</a>
                project), the user is forwarded to a nested page flow
                (<code>/nesting/chooseAirport/chooseAirport.jpf</code>),
                which is a wizard that helps the user find an airport. The nested page flow returns the chosen airport
                to the original page flow, which continues with its sequence. First, here is a diagram of the main page
                flow:
            </p>
            <p>
                <img src="images/netui/nestedPageFlow/nestingMain.gif" alt="main page flow"/>
            </p>
            <p>
                This page flow demonstrates two new features related to nesting:
            </p>
            <ul>
                <li>
                    The nested page flow returns a form bean (<code>ChooseAirport.Results</code>) when it raises the 
                    <code>chooseAirportDone</code> action. 
                </li>
                <li>
                    If the nested page flow raises a <code>chooseAirportCancelled</code> action, the page flow will go
                    back to <em>the most recent page shown to the user.</em>, whatever that page is.
                </li>
            </ul>
            <section id="returningData">
                <title>Returning data from a nested page flow</title>
                <p>
                    Here is a diagram of the nested page flow <code>ChooseAirport.jpf</code>, with the "happy path" to
                    the <code>chooseAirportDone</code> return-action hightlighted in red:
                </p>
                <p>
                    <img src="images/netui/nestedPageFlow/nestingChooseAirport.gif" alt="Choose Airport nested page flow"/>
                </p>
                <p>
                    During the course of this page flow, a member variable called <code>_currentResults</code>, of type
                    <code>ChooseAirport.Results</code> is kept. As the user moves through the page flow, possibly re-trying
                    and changing the desired result, this member variable is kept up-to-date. In the end, it is
                    <em>returned</em> as an "output form bean" along with the <code>chooseAirportDone</code> return-action,
                    using the
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html#outputFormBean()">
                        <code>outputFormBean</code>
                    </a>
                    attribute. This is what it looks like in the annotations:
                </p>
                <source>
    @Jpf.SimpleAction(name="confirmResults", returnAction="chooseAirportDone", outputFormBean="_currentResults")</source>
                <p>
                    This annotation simply specifies that the value of <code>_currentResults</code> will be sent along with
                    the return-action <code>chooseAirportDone</code>.
                </p>
                <note>
                    You do not have to return a member variable as an output form bean.  If you just want to return a
                    local variable, you would use the 
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#outputFormBeanType()">
                        <code>outputFormBeanType</code>
                    </a>
                    attribute instead, and you would pass the bean on the
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/Forward.html">
                        <code>Forward</code>
                    </a>
                    object returned from an action method, like this:
                        <br/>
                        <br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;@Jpf.Action(</code><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;forwards={</code><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;
                            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@Jpf.Forward(name="done",
                            returnAction="chooseAirportDone", outputFormBeanType=Results.class)
                        </code>
                        <br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}</code><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;)</code><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;public Forward confirmResults()</code><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;{</code><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Results results = </code><em>initialize a Results object</em><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return new Forward("done", results);</code><br/>
                        <code>&nbsp;&nbsp;&nbsp;&nbsp;}</code>
                </note>
                <p>
                    In the original page flow, there is a
                    <code>chooseAirportDone</code> method that accepts this form bean as an argument, like this:
                </p>
                <source>
@Jpf.Action(
    ...
)
protected Forward chooseAirportDone(ChooseAirport.Results results)
{
    ...
}               </source>
                <p>
                    As you can see, the page flow handles this returned form bean just like it would handle a form
                    bean posted from a page.
                </p>
            </section>
            <section id="navigateTo">
                <title>Navigating back to the original page of the main flow</title>
                <p>
                    The the current example, the main page flow goes back to the most recent page whenever the nested
                    page flow raises the <code>chooseAirportCancelled</code> action. We are referring to this section
                    of the diagram of the main page flow:
                </p>
                <p>
                    <img src="images/netui/nestedPageFlow/nestingChooseAirportCancelled.gif" alt="chooseAirportCancelled"/>
                </p>
                <p>
                    To navigate to the most recent page, the page flow uses the 
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html#navigateTo()">
                        <code>navigateTo</code>
                    </a>
                    attribute on a 
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">
                        <code>@Jpf.SimpleAction</code>
                    </a>
                    (or a
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
                        <code>@Jpf.Forward</code>
                    </a>), like this:
                </p>
                <source>
@Jpf.SimpleAction(name="chooseAirportCancelled", navigateTo=Jpf.NavigateTo.currentPage)</source>
                <p>
                    Or could also go back to the <em>previous</em> page:
                </p>
                <source>
@Jpf.SimpleAction(name="chooseAirportCancelled", navigateTo=Jpf.NavigateTo.previousPage)</source>
                <p>Or it could re-run the most recent action in
                    the current page flow:</p>
                <source>
@Jpf.SimpleAction(name="chooseAirportCancelled", navigateTo=Jpf.NavigateTo.previousAction)</source>
                <note>
                    The
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#navigateTo()">
                        <code>navigateTo</code>
                    </a>
                    feature is not only used with nested page flows. You can use it on any
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.SimpleAction.html">
                        <code>@Jpf.SimpleAction</code>
                    </a>
                    or
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html">
                        <code>@Jpf.Forward</code>
                    </a>
                    annotation in your page flow. It just happens to be a very valuable feature when used in conjunction
                    with nested page flows.
                </note>
            </section>
            <section id="passingData">
                <title>Passing Data to a Nested Page Flow</title>
                <p>
                    Sometimes you will want to pass data into a nested page flow. While this may be less common than
                    returning data from a nested page flow, it is useful for initializing data in the flow. To do this,
                    you will add a form bean to the <code>begin</code> action of the nested page flow, and in the
                    calling page flow you will pass an instance of this bean on the
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/Forward.html">
                        <code>Forward</code>
                    </a>
                    object that is sent to the nested page flow.
                </p>
                <section id="beginActionFormBean">
                    <title>Add a form bean to the nested page flow's <code>begin</code> action</title>
                    <p>
                        To add a form bean, simply add a single argument to a <code>begin</code> action method:
                    </p>
                    <source>
@Jpf.Action(
    forwards={
        @Jpf.Forward(name="index", path="index.jsp")
    }
)
public Forward begin(<strong>InitBean initBean</strong>)
{
    ...
}                   </source>
                    <p>
                        The bean type can be any class of your choosing; for instance, you can make it a
                        <code>String</code>, which means that the nested page flow requires a <code>String</code> to
                        be initialized:
                    </p>
                    <source>
@Jpf.Action(
    forwards={
        @Jpf.Forward(name="index", path="index.jsp")
    }
)
public Forward begin(<strong>String initString</strong>)
{
    ...
}                   </source>
                </section>
                <section id="passingFormBean">
                    <title>Pass the form bean from the calling page flow to the nested page flow</title>
                    <p>
                        You can pass the initialization bean to the nested page flow by adding it to the
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/Forward.html">
                            <code>Forward</code>
                        </a>
                        object that is sent to the nested page flow:
                    </p>
                    <source>
@Jpf.Action(
    forwards={
        @Jpf.Forward(name="nestedFlow", path="/nested/NestedFlow.jpf", outputFormBeanType=InitBean.class)
    }
)
public Forward goNested()
{
    InitBean initBean = <em>initialize the bean</em>
    return new Forward("nestedFlow", initBean);
}                   </source>
                    <p>
                        Note that the
                        <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#outputFormBeanType()">
                            <code>outputFormBeanType</code>
                        </a>
                        annotation attribute is optional; it mainly helps tools understand the output of the action, and
                        it ensures that an incompatible type will not be passed.
                    </p>
                </section>
            </section>
        </section>
        <section id="otherNotes">
            <title>Other Notes</title>
            <p>
                Here are some other notes about using nested page flows:
            </p>
            <ul>
                <li>
                    Aside from the 
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html#nested()">
                        <code>nested=true</code>
                    </a>
                    on the
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Controller.html">
                        <code>@Jpf.Controller</code>
                    </a>
                    annotation, and defining exit points through
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#returnAction()">
                        <code>returnAction</code></a>,
                    nested page flows are built just like other non-nested page flows.
                </li>
                <li>
                    You enter a nested page flow by hitting its URL, by hitting the URL for any of its actions, or by
                    hitting the URL for any of its pages (pages in the same directory path). When nesting occurs, the
                    original page flow is pushed onto the "nesting stack", and is popped off the stack when the nested
                    page flow hits an exit point (through a
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.Forward.html#returnAction()">
                        <code>returnAction</code>
                    </a>
                    attribute).
                </li>
                <li>
                    Nested page flows can nest themselves.
                </li>
                <li>
                    
                    While in a nested page flow, you can get a reference to the calling page flow through
                    <a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/PageFlowUtils.html#getNestingPageFlow(javax.servlet.http.HttpServletRequest, javax.servlet.ServletContext)">
                        <code>PageFlowUtils.getNestingPageFlow()</code></a>.
                </li>
            </ul>
        </section>
    </body>

</document>
