| <?xml version="1.0"?> |
| |
| <document url="./actionForm.xml"> |
| |
| <properties> |
| <title>Building an ActionForm</title> |
| </properties> |
| |
| <body> |
| <section 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><form></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><input></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> |
| |
| </body> |
| </document> |
| |
