<?xml version="1.0"?>
<!--
    $Id: apps.xml 481833 2006-12-03 17:32:52Z niallp $

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<!--
// ======================================================================== 78
-->
<document>

    <properties>
        <title>How to Build Applications</title>
    </properties>
    <body>
        <section name="How to Build Applications">
                <p>
                    This document outlines one possible sequence of
                    development steps that can be followed to create a
                    Struts application. It is not intended as
                    a complete description of each
                    referenced development activity. More detailed
                    documentation is available
                    elsewhere and is referenced by "(more...)" links where
                    possible.
                </p>
                
                <p>
                	 For those who are short on time and/or patience, 
                	 you can get a Struts application up and running
                	 in a matter of minutes thanks to Maven's archetype
                	 feature.
                </p>
                <p>
                  NOTE - as of the time of this writing (10/16/2006), the
                  specified version in this example has not been released.
                  Once this has been released, this note can be removed and
                  the archetype will work fine.
                  <code>
                    <pre>
                	   $ cd ~/projects
                	   
					   $ mvn archetype:create                                \
					         -DarchetypeGroupId=org.apache.struts            \
					         -DarchetypeArtifactId=struts-archetype-blank    \
					         -DarchetypeVersion=1.3.5                        \
					         -DgroupId=com.example                           \
					         -DpackageName=com.example.projectname           \
					         -DartifactId=my-webapp
					         
                	   $ cd my-webapp
                	   
                	   $ mvn install
                	   
                	   $ mvn jetty:run
                    </pre>
                  </code>
                </p>

            <subsection name="Caveats">
                <ol>
                    <li>Requirements development and design are outside of the
                        scope of this document.</li>
                    <li>For help installing the framework, see the
                        <a href="../userGuide/installation.html">Getting
                            Started</a>
                        chapter.
                    </li>
                    <li>There are many other ways to approach development with
                        the framework and there are many
                        other features available besides the ones discussed
                        below. This document
                        outlines only one way to get started.</li>
                    <li>This document focuses on form/data centric
                        applications, but may also work with
                        other types of applications.</li>
                    <li>This material was originally written for Struts 1.1 (beta 2), 
                        and reviewed for the 1.3.5 distribution.</li>
                </ol>
            </subsection>

            <subsection name="Overview">
                <ol>
                    <li>Implement data entry forms as JSP files.</li>
                    <li>Implement one or more
                        <code>ActionForm</code>
                        descendents to buffer data
                        between JSPs and Actions.
                    </li>
                    <li>Create an XML document that defines the validation
                        rules for your
                        application.</li>
                    <li>Implement one or more
                        <code>Action</code>
                        descendents to respond form
                        submissions.
                    </li>
                    <li>Create
                        <code>struts-config.xml</code>
                        to associate forms with
                        actions.
                    </li>
                    <li>Create or update
                        <code>web.xml</code>
                        to reference
                        <code>ActionServlet.</code>
                    </li>
                    <li>Parallel Tasks
                        <ol>
                            <li>Building</li>
                            <li>Unit Testing</li>
                            <li>Deployment</li>
                        </ol>
                    </li>
                </ol>
            </subsection>

            <subsection name="Details">
                <ol>
                    <li>Implement data entry forms as JSP files.
                        <ol>
                            <li>Use elements from the
                                <code>html</code>
                                taglib
                                to define the form elements.
                                <a href="../struts-taglib/tagreference.html#struts-html.tld">
                                    (more...)</a>
                            </li>
                            <li>Use
                                <code>message</code>
                                and other elements from the
                                <code>bean</code>
                                taglib to define the labels and other static
                                text of the form.
                                <a href="../struts-taglib/tagreference.html#struts-bean.tld">
                                    (more...)</a>
                                <ol>
                                    <li>Create and maintain a properties file
                                        of the text elements
                                        to be displayed.
                                        <a href="../userGuide/preface.html#0_6_Properties_Files_and_ResourceBundles">
                                            (more...)
                                        </a>
                                    </li>
                                </ol>
                            </li>
                            <li>Use
                                <code>property</code>
                                attributes to link form fields to
                                <code>ActionForm</code>
                                instance variables.
                            </li>
                        </ol>
                    </li>
                    <li>Implement one or more
                        <code>ActionForm</code>
                        descendents
                        to buffer data between JSPs and Actions.
                        <ol>
                            <li>Create get/set pairs that correspond to the
                                property names
                                in your related JSP form. Example:
                                <pre>&lt;html:text property="city" /&gt;</pre>
                                needs:
                                <pre>getCity() and setCity(String c)</pre>
                            </li>
                            <li>When needed, create a
                                <code>reset</code>
                                method
                                that sets the fields of the
                                <code>ActionForm</code>
                                to their default values. Most ActionForms do
                                not need to do this.
                            </li>
                        </ol>
                    </li>
                    <li>Create an XML document that defines the validation
                        rules for your
                        application.</li>
                    <li>Implement one or more
                        <code>Action</code>
                        descendents
                        to respond to form submissions.
                        <ol>
                            <li>Descend from DispatchAction or
                                LookupDispatchAction if you
                                want one class to handle more than one kind of
                                event (example: one Action
                                to handle 'insert', 'update' and 'delete'
                                events, using a different "surrogate" execute
                                method for each).
                                <a href="http://husted.com/struts/tips/002.html">
                                    (more...)</a>
                            </li>
                            <li>Use the
                                <code>execute</code>
                                method
                                (or its surrogates) of your Action class to
                                interface with objects in your
                                application responsible for database
                                interaction, such as EJBs, etc.
                                <!-- [:TODO: find good doc to link to] -->
                            </li>
                            <li>Use the return value of the
                                <code>execute</code>
                                method
                                (or its surrogates) direct the user interface
                                to the appropriate next page.
                                <!-- [:TODO: find good doc to link to] -->
                            </li>
                        </ol>
                    </li>
                    <li>Create
                        <code>struts-config.xml</code>
                        to
                        associate forms with actions. The file minimally
                        needs:
                    </li>
                    <li>Create or update
                        <code>web.xml</code>
                        to
                        reference
                        <code>ActionServlet</code>
                        <a href="../userGuide/configuration.html#5_4_The_Web_Application_Deployment_Descriptor">
                            (more...)</a>
                    </li>
                    <li>Parallel Tasks
                        <ol>
                            <li>Building
                                <ol>
                                    <li>Use Ant. It can compile, create WAR
                                        file, perform XSLT
                                        transformations, run unit tests,
                                        interact with version control systems,
                                        clean up, etc.
                                        <a href="http://ant.apache.org">
                                            (more...)</a>
                                    </li>
                                    <li>Create and use build script
                                        incrementally, as you create
                                        files that need to be copied,
                                        compiled, etc.</li>
                                </ol>
                            </li>
                            <li>Unit Testing
                                <ol>
                                    <li>Unit test normal JavaBeans with
                                        JUnit.
                                        <a href="http://www.junit.org">
                                            (more...)</a>
                                    </li>
                                    <li>Unit test JSP, taglibs, and
                                        conventional servlet components
                                        with Cactus.
                                        <a href="http://jakarta.apache.org/cactus">
                                            (more...)</a>
                                    </li>
                                    <li>Unit test Action servlets with
                                        StrutsTestCase.
                                        <a href="http://strutstestcase.sourceforge.net">
                                            (more...)</a>
                                    </li>
                                    <li>Add all unit tests to the build script
                                        as a separate
                                        target. This target should use the
                                        <code>junit</code>
                                        tag to launch each TestCase
                                        descendent.
                                        <a href="http://ant.apache.org/manual/OptionalTasks/junit.html">
                                            (more...)</a>
                                    </li>
                                </ol>
                            </li>
                            <li>Deployment
                                <ol>
                                    <li>Build script should create a WAR file
                                        containing the
                                        files developed above, along with
                                        files that make up the 
                                        framework.
                                        <!-- [:TODO: describe this further, look for doc to link to] -->
                                    </li>
                                </ol>
                            </li>
                        </ol>
                    </li>
                </ol>
            </subsection>
        </section>
    </body>
</document>
