Repository: struts-site Updated Branches: refs/heads/master 5a7ec7cde -> 6ff7bb27a
Breaks long lines Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/6ff7bb27 Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/6ff7bb27 Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/6ff7bb27 Branch: refs/heads/master Commit: 6ff7bb27adad4558b99895af3295b82c34e6b2ef Parents: 5a7ec7c Author: Lukasz Lenart <lukaszlen...@apache.org> Authored: Sun Jul 30 12:25:12 2017 +0200 Committer: Lukasz Lenart <lukaszlen...@apache.org> Committed: Sun Jul 30 12:25:12 2017 +0200 ---------------------------------------------------------------------- source/getting-started/processing-forms.md | 89 +++++++++++++++++++------ 1 file changed, 67 insertions(+), 22 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/struts-site/blob/6ff7bb27/source/getting-started/processing-forms.md ---------------------------------------------------------------------- diff --git a/source/getting-started/processing-forms.md b/source/getting-started/processing-forms.md index 0f6a7ba..0ff1bc4 100644 --- a/source/getting-started/processing-forms.md +++ b/source/getting-started/processing-forms.md @@ -4,21 +4,30 @@ title: Processing forms --- ## Processing Forms -This tutorial assumes you've completed the [Coding Struts 2 Actions](coding-actions.html) tutorial and have a working coding-actions project. The example code for this tutorial, form-processing, is available for checkout from the Struts 2 GitHub subversion repository: [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples). +This tutorial assumes you've completed the [Coding Struts 2 Actions](coding-actions.html) tutorial and have a working +coding-actions project. The example code for this tutorial, form-processing, is available for checkout from +the Struts 2 GitHub subversion repository: [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples). ### Introduction -In this tutorial we'll explore using Struts 2 to do more involved processing of a form submission. We'll cover how to use a Java model class to store the form input and how to create the Struts 2 form to match up with that model class. +In this tutorial we'll explore using Struts 2 to do more involved processing of a form submission. We'll cover how to +use a Java model class to store the form input and how to create the Struts 2 form to match up with that model class. -The code provided in this tutorial may be added to the [Coding Struts 2 Actions](coding-actions.html) example or you can download this complete example from the github respository - [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples). +The code provided in this tutorial may be added to the [Coding Struts 2 Actions](coding-actions.html) example or you +can download this complete example from the github respository - [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples). -The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list. +The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are +having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find +an answer to your problem, post a question on the mailing list. ### Forms and a Java model class -For this tutorial let's say we need to provide a form that a user may submit to register for a prize drawing. Our business rules state the user must provide his/her first name, last name, email address, and age. +For this tutorial let's say we need to provide a form that a user may submit to register for a prize drawing. Our +business rules state the user must provide his/her first name, last name, email address, and age. -To encapsulate this data, we'll use a simple Java class that follows the basic Java Bean specifications (public set/get methods for each instance field). If you're following along add this class to the package `org.apache.struts.register.model` in the [Coding Struts 2 Actions](coding-actions.html) example. +To encapsulate this data, we'll use a simple Java class that follows the basic Java Bean specifications (public set/get +methods for each instance field). If you're following along add this class to the package `org.apache.struts.register.model` +in the [Coding Struts 2 Actions](coding-actions.html) example. **Person.java** @@ -68,11 +77,16 @@ public class Person { } ``` -Note a few points about the above class. There is a public set/get method for each instance field. The age attribute is of type integer. We've defined a public `toString` method that returns a String representing the state of the object. Since we haven't specified a constructor, Java will provide a default constructor that will set all instance fields to their null values. +Note a few points about the above class. There is a public set/get method for each instance field. The age attribute +is of type integer. We've defined a public `toString` method that returns a String representing the state of the object. +Since we haven't specified a constructor, Java will provide a default constructor that will set all instance fields to +their null values. ### Form structure -To collect the above information we'll use a Struts 2 form. When creating this form the key concept we need to employ is to tie each form field to a specific instance field of an object of type Person. Let's look over the form first and then discuss some key points. Create a view page named `register.jsp` (in `src/main/webapp`) +To collect the above information we'll use a Struts 2 form. When creating this form the key concept we need to employ +is to tie each form field to a specific instance field of an object of type Person. Let's look over the form first and +then discuss some key points. Create a view page named `register.jsp` (in `src/main/webapp`) **register.jsp** @@ -103,15 +117,24 @@ Since we are using Struts 2 tags, at the top of the page we need the Struts tag The Struts 2 form will submit to an action named register. We'll need to define that action in our `struts.xml` file. -Note the four Struts 2 textfield tags. Each tag has a name value that includes an attribute of the `Person` class (e.g. `firstName`). The name attribute's value also has a reference to an object called `personBean`. This object is of type `Person`. When we create the Action class that handles this form submission, we'll have to specify that object in that Action class (see below). +Note the four Struts 2 textfield tags. Each tag has a name value that includes an attribute of the `Person` class +(e.g. `firstName`). The name attribute's value also has a reference to an object called `personBean`. This object is +of type `Person`. When we create the Action class that handles this form submission, we'll have to specify that object +in that Action class (see below). -The complete name value, `personBean.firstName`, instructs Struts 2 to use the input value for that textfield as the argument to the personBean object's `setFirstName` method. So if the user types "Bruce" in the textfield that has the label "First name", the personBean's `firstName` instance field will have a value of "Bruce". +The complete name value, `personBean.firstName`, instructs Struts 2 to use the input value for that textfield as +the argument to the personBean object's `setFirstName` method. So if the user types "Bruce" in the textfield that has +the label "First name", the personBean's `firstName` instance field will have a value of "Bruce". -Note that we have a Struts 2 textfield for each instance field of the class Person. Remember that Person class's age attribute is of type integer. All form field input values are Strings. Struts 2 will automatically convert the String value ("25") the user entered for the age form field to 25 when calling the `setAge` method of object `personBean`. +Note that we have a Struts 2 textfield for each instance field of the class Person. Remember that Person class's age +attribute is of type integer. All form field input values are Strings. Struts 2 will automatically convert the String +value ("25") the user entered for the age form field to 25 when calling the `setAge` method of object `personBean`. ### Creating the Action class to handle the form submission -When the user clicks on the submit button of the above form, the action "register" and the form data will be sent to the Struts 2 framework. We need an Action class to process this form. If you recall from the tutorial [Coding Struts 2 Actions](coding-actions.html) our Action class should extend the Struts 2 ActionSupport class. +When the user clicks on the submit button of the above form, the action "register" and the form data will be sent to +the Struts 2 framework. We need an Action class to process this form. If you recall from the tutorial +[Coding Struts 2 Actions](coding-actions.html) our Action class should extend the Struts 2 ActionSupport class. Here is the Action class used for this example. Place it in package org.apache.struts.register.action. @@ -147,19 +170,32 @@ public class Register extends ActionSupport { } ``` -In the `Register` class note that we've declared an attribute named `personBean` of type `Person` and there is a public get and set method for this object. +In the `Register` class note that we've declared an attribute named `personBean` of type `Person` and there is a public +get and set method for this object. -The `Register` class also overrides the `execute` method. The `execute` method is the one we will specify in the `struts.xml` to be called in response to the register action. In this example, the `execute` method just returns the String constant `SUCCESS` (inherited from the `ActionSupport` class). But in a real application, within the `execute` method we would call upon other classes (Service objects) to perform the business processing of the form, such as storing the user's input into a data repository. +The `Register` class also overrides the `execute` method. The `execute` method is the one we will specify in the +`struts.xml` to be called in response to the register action. In this example, the `execute` method just returns +the String constant `SUCCESS` (inherited from the `ActionSupport` class). But in a real application, within the `execute` +method we would call upon other classes (Service objects) to perform the business processing of the form, such as storing +the user's input into a data repository. -The `personBean` object of type `Person` declared in the Register Action class matches the `personBean` name we used in the form's textfields. When the form is submitted, the Struts 2 framework will inspect the Action class and look for an object named `personBean`. It will create that object using the `Person` class's default constructor. Then for each form field that has a name value of personBean.someAttribute (e.g `personBean.firstName`) it will call the personBean's public set method for that attribute and pass it the form field's value (the user input). This all happens before the execute method occurs. +The `personBean` object of type `Person` declared in the Register Action class matches the `personBean` name we used in +the form's textfields. When the form is submitted, the Struts 2 framework will inspect the Action class and look for +an object named `personBean`. It will create that object using the `Person` class's default constructor. Then for each +form field that has a name value of personBean.someAttribute (e.g `personBean.firstName`) it will call the personBean's +public set method for that attribute and pass it the form field's value (the user input). This all happens before +the execute method occurs. -When Struts 2 runs the `execute` method of class `Register`, the `personBean` object in class `Register` now has values for its instance fields that are equal to the values the user entered into the corresponding form fields. +When Struts 2 runs the `execute` method of class `Register`, the `personBean` object in class `Register` now has values +for its instance fields that are equal to the values the user entered into the corresponding form fields. -By using a Java model class to encapsulate the data provided by the form we don't have to have a separate attribute (with public set/get methods) in the Action class (Register) for each form field. +By using a Java model class to encapsulate the data provided by the form we don't have to have a separate attribute +(with public set/get methods) in the Action class (Register) for each form field. ### Adding the view for the result -When `SUCCESS` is returned by the `execute` method we want to display a simple thank you page that shows the user's registration. Add the `thankyou.jsp` below to `src/main/webapp`. +When `SUCCESS` is returned by the `execute` method we want to display a simple thank you page that shows the user's +registration. Add the `thankyou.jsp` below to `src/main/webapp`. **thankyou.jsp** @@ -186,7 +222,9 @@ If you don't recall how the Struts 2 property and url tags work consult the [Usi ### Create action mapping in struts.xml -To specify the relationship between the form submission page, the Struts 2 Action class, and the success view page we need to add an action node to `struts.xml`. Add this action node to `struts.xml` (`src/main/resources`) after the hello action and before the closing package node. +To specify the relationship between the form submission page, the Struts 2 Action class, and the success view page +we need to add an action node to `struts.xml`. Add this action node to `struts.xml` (`src/main/resources`) after +the hello action and before the closing package node. **action node for struts.xml** @@ -196,9 +234,12 @@ To specify the relationship between the form submission page, the Struts 2 Actio </action> ``` -The above action tells Struts 2 that when the register action is provided to call method `execute` of class `Register`. If that method returns result "success" return to the browser the `thankyou.jsp`. +The above action tells Struts 2 that when the register action is provided to call method `execute` of class `Register`. +If that method returns result "success" return to the browser the `thankyou.jsp`. -Note that we don't need to tell Struts 2 anything about processing the form. The transfer of the form field input values to the `personBean` object will happen automatically provided we've followed the convention of naming our form fields to match personBean.attributeName (e.g. `personBean.lastName`). +Note that we don't need to tell Struts 2 anything about processing the form. The transfer of the form field input values +to the `personBean` object will happen automatically provided we've followed the convention of naming our form fields +to match personBean.attributeName (e.g. `personBean.lastName`). ### Create a link to register.jsp @@ -212,7 +253,11 @@ So that the user can find the registration page, add this link to index.jsp __Run The Example__ -If everything is correct, you should be able to run the application (using `mvn jetty:run`), and open this URL in your web browser: [http://localhost:8080/form-processing/index.action](http://localhost:8080/form-processing/index.action). On that page should be a link to register. Click on that link and you should see the `register.jsp` page. +If everything is correct, you should be able to run the application (using `mvn jetty:run`), and open this URL in your +web browser: +[http://localhost:8080/form-processing/index.action](http://localhost:8080/form-processing/index.action). On that page +should be a link to register. +Click on that link and you should see the `register.jsp` page. 
