<?xml version="1.0"?>

<document url="./actionForm.xml">

 <properties>
   <author>Craig R. McClanahan</author>
  <title>Building an ActionForm</title>
 </properties>

<body>
<chapter href="actionForm" name="How to Build an Action Form">
           
<section href="login" name="Creating a Login Form">

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

<hr/>

<pre><code><![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>
]]></code></pre>

<hr/>

    <p>
    The following items illustrate the key features of form handling in Struts,
    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 tag library.  
        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 Struts developer provides the Java implementation of the 
        ActionForm bean, subclassing the Struts class <code>ActionForm</code>
        (see <a href="../userGuide/building_controller.html#action_form_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#config">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>

    <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>

<hr/>

<pre><code><![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>
]]></code></pre>

<hr/>

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


<hr/>

<pre><code><![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;
    }

}
]]></code></pre>

<hr/>

    <p>
    Look at the Javadocs for 
    <code><a href="../api/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="../api/org/apache/struts/action/ActionServlet.html">
    ActionServlet</a> and
    <a href="../api/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>

</section>

  </chapter>
 </body>
</document>

