<?xml version="1.0"?>
<!--
    $Id: actionForm.xml 562110 2007-08-02 13:45:57Z 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 an Action Form</title>
    </properties>

    <body>
        <section name="How to Build an Action Form">

                <p>
                    This is a simple example of a login form to illustrate how
                    Struts
                    Action Framework makes dealing with forms much less
                    painful than using straight HTML
                    and standard JSP facilities.
                    Consider the following page (based on the Struts
                    MailReader example) named
                    <code>logon.jsp:</code>
                </p>

                <hr/>

                <source><![CDATA[
<%@ page language="java" %>
<%@ taglib  uri="/WEB-INF/struts-html.tld" prefix="html" %>
<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>

<html:html>
<head>
<title>
    <bean:message key="logon.title"/>
</title>
</head>

<body bgcolor="white">

<html:errors/>

<html:form action="/logon" focus="username">
<table border="0" width="100%">
    <tr>
        <th class="right">
            <bean:message key="prompt.username"/>
        </th>
        <td class="left">
            <html:text  property="username" size="16"/>
        </td>
    </tr>
    <tr>
        <th class="right">
            <bean:message key="prompt.password"/>
        </th>
        <td class="left">
            <html:password property="password" size="16"/>
        </td>
    </tr>
    <tr>
        <td class="right">
            <html:submit>
                <bean:message key="button.submit"/>
            </html:submit>
        </td>
        <td class="right">
            <html:reset>
                <bean:message key="button.reset"/>
            </html:reset>
        </td>
    </tr>
</table>

</html:form>
</body>
</html:html>
]]></source>

                <hr/>

                <p>
                    The following items illustrate the key features of form
                    handling,
                    based on this example:
                </p>

                <ul>

                    <li>
                        The
                        <code>taglib</code>
                        directive tells the JSP page compiler where to
                        find the
                        <em>tag library descriptor</em>
                        for the Struts JSP tags.
                        In this case, we are using
                        <code>bean</code>
                        as the prefix that
                        identifies tags from the struts-bean library, and
                        "html" as the prefix
                        that identifies tags from the struts-html library.
                        Any desired prefix can be used.
                    </li>

                    <li>
                        This page uses several occurrences of the
                        <strong>message</strong>
                        tag to look up internationalized
                        message strings from a
                        <code>MessageResources</code>
                        object containing
                        all the resources for this application.
                        For this page to work, the following message keys must
                        be defined in
                        these resources:

                        <ul>

                            <li>
                                <strong>logon.title</strong>
                                - Title of the logon page
                            </li>

                            <li>
                                <strong>prompt.username</strong>
                                - A "Username:" prompt string
                            </li>

                            <li>
                                <strong>prompt.password</strong>
                                - A "Password:" prompt string
                            </li>

                            <li>
                                <strong>button.submit</strong>
                                - "Submit" for the button label
                            </li>

                            <li>
                                <strong>button.reset</strong>
                                - "Reset" for the button label
                            </li>

                        </ul>

                        When the user logs on, the application can store a
                        <code>Locale</code>
                        object in the user's session.
                        This
                        <code>Locale</code>
                        will be used to select messages in the
                        appropriate language.
                        This makes it easy to implement giving the user an
                        option to switch
                        languages -- simply change the stored
                        <code>Locale</code>
                        object, and
                        all messages are switched automatically.
                    </li>

                    <li>
                        The
                        <strong>errors</strong>
                        tag displays any error messages that have been
                        stored by a business logic component, or nothing if no
                        errors have been
                        stored.
                        This tag will be described further below.
                    </li>

                    <li>
                        The
                        <strong>form</strong>
                        tag renders an HTML
                        <code>&lt;form&gt;</code>
                        element,
                        based on the specified attributes.
                        It also associates all of the fields within this form
                        with a
                        <code>ActionForm</code>
                        bean
                        <code>[org.apache.struts.action.ActionForm].</code>
                        The tag looks up the
                        <code>/logon</code>
                        action mapping in the Struts
                        configuration.
                        The
                        <code>logon</code>
                        mapping tells the tag that the form bean is
                        stored in the session context under the key
                        <code>logonForm.</code>
                        The developer provides the Java implementation of the
                        ActionForm bean, subclassing the Struts class
                        <code>ActionForm</code>
                        (see
                        <a href="../userGuide/building_controller.html#4_3_ActionForm_Classes">
                            Building
                            Controller</a>
                        components).
                        This bean is used to provide initial values for all of
                        the input
                        fields that have names matching the property names of
                        the bean.
                        If an appropriate bean is not found, a new one will be
                        created
                        automatically, using the Java class name specified
                        through the
                        action mapping.
                    </li>

                    <li>
                        The form bean can also be specified in the tag by
                        providing
                        <code>name</code>
                        and
                        <code>type</code>
                        attributes. But most often,
                        everything is specified in the
                        <a href="../userGuide/building_controller.html#4_8_Writing_Action_Mappings">
                            Struts Configuration
                            File.</a>
                    </li>

                    <li>
                        The
                        <strong>text</strong>
                        tag renders an HTML
                        <code>&lt;input&gt;</code>
                        element of type "text".
                        In this case, the number of character positions to
                        occupy on the
                        browser's screen has been specified as well.
                        When this page is executed, the current value of the
                        <code>username</code>
                        property of the corresponding bean (that is,
                        the value returned by
                        <code>getUsername</code>
                        ).
                    </li>

                    <li>
                        The
                        <strong>password</strong>
                        tag is used similarly.
                        The difference is that the browser will echo asterisk
                        characters,
                        instead of the input value, as the user types their
                        password.
                    </li>

                    <li>
                        The
                        <strong>submit</strong>
                        and
                        <strong>reset</strong>
                        tags generate the corresponding
                        buttons at the bottom of the form.
                        The text labels for each button are created using
                        message tags,
                        as with the prompts, so that these values are
                        internationalized.
                    </li>

                </ul>

            <subsection name="Transferring Data">

                <p>
                    To transfer data between ActionForms and business objects,
                    many developers use the Commons BeanUtil methods.
                    To transfer data from an ActionForm to a business object,
                    you can use a statement like:
                </p>

                <source><![CDATA[
            PropertyUtils.copyProperties(actionForm, businessObject);

]]></source>

                <p>
                    To transfer data from a business object to an ActionForm,
                    you can reverse the parameters


                    <source><![CDATA[
            PropertyUtils.copyProperties(businessObject, actionForm);
]]></source>
                </p>

                <p>
                    For more about using this technique, see the
                    <a href="http://commons.apache.org/beanutils/">
                        Commons BeanUtils documentation,</a>
                    and the Struts MailReader example application.
                </p>

                <p>
                    Aside from BeanUtils,
                    there are other tools available that make it easier to use
                    business objects
                    and ActionForms together.
                    For more about POJO ActionForms, see the
                    <a href="https://formdef.dev.java.net/">FormDef</a>
                    extension
                    and the
                    <a href="https://strutslive.dev.java.net/">Struts Live</a>
                    toolkit.
                </p>
            </subsection>

            <subsection name="Multipart Forms">

                <p>
                    Handling multipart forms is also easy.
                    Obviously when you create a multipart form you're creating
                    a form that
                    has at least one input of type "file".
                    The first step to creating a multipart form is to utilize
                    the struts-html
                    taglib to create the presentation page:
                </p>

                <source><![CDATA[
<%@page language="java">
<%@taglib
    uri="/WEB-INF/struts-html.tld"
   prefix="html">

<html:form action="uploadAction.do" enctype="multipart/form-data">

    Please Input Text: <html:text property="myText">
    Please Input The File You Wish to Upload: <html:file property="myFile">

   <html:submit />

</html:form>
]]></source>

                <hr/>

                <p>
                    The next step is to create your ActionForm bean:
                </p>


                <hr/>

                <source><![CDATA[
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.struts.action.ActionForm;
import org.apache.struts.action.ActionMapping;
import org.apache.struts.upload.FormFile;

public class UploadForm extends ActionForm {

    protected String myText;
    protected FormFile myFile;

    public void setMyText(String text) {
        myText = text;
    }

    public String getMyText() {
        return myText;
    }

    public void setMyFile(FormFile file) {
        myFile = file;
    }

    public FormFile getMyFile() {
        return myFile;
    }

}
]]></source>

                <hr/>

                <p>
                    Look at the Javadocs for
                    <code>
                        <a href="../apidocs/org/apache/struts/upload/FormFile.html">
                            FormFile</a>
                    </code>
                    to see the methods it exposes to manipulate files in
                    file uploading.
                    Also look at the Javadocs for
                    <a href="../apidocs/org/apache/struts/action/ActionServlet.html">
                        ActionServlet</a>
                    and
                    <a href="../apidocs/org/apache/struts/action/ActionMapping.html">
                        ActionMapping</a>
                    for the various parameters you can specify to change
                    how files are uploaded.
                    Basically in your
                    <code>execute</code>
                    method in your action class you
                    would call
                    <code>((UploadForm) form).getMyFile()</code>
                    to retrieve the
                    FormFile and do what you want with it.
                </p>

            </subsection>

        </section>
    </body>
</document>

