Processing Form Submissions
| To demonstrate how to process returned forms, you must create a simple template that echoes the movie title you entered. The template is shown in Listing 12.2. Listing 12.2. form1_action.cfmProcessing Form Fields<!--- Name: form1_action.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 1</title> </head> <body> <!--- Display search text ---> <cfoutput> <strong>Movie title:</strong> #FORM.MovieTitle# </cfoutput> </body> </html> Processing Text SubmissionsBy now the <cfoutput> tag should be familiar to you; you use it to mark a block of code that ColdFusion should parse and process. The line <strong>Movie title:</strong> #FORM.MovieTitle# is processed by ColdFusion. #FORM.MovieTitle# is replaced with the value you entered in the MovieTitle form field. NOTE Use of the prefix FORM is optional. Using it prevents ambiguity and improves performance, but it also makes the code less reusable.
Create a template called form1_action.cfm that contains the code in Listing 12.2 and save it. Then resubmit your movie's name by clicking the form's submit button again. This time you should see a browser display similar to the one shown in Figure 12.3. Whatever name you enter in the Movie field in the form is displayed. Figure 12.3. Submitted form fields can be displayed simply by referring to the field name. As you can see, FORM fields are used in ColdFusion like any other variable type. Processing Check Boxes and Radio ButtonsOther input types you will frequently use are check boxes and radio buttons.
The code example in Listing 12.3 creates a form that uses both option buttons and check box fields. Listing 12.3. form2.cfmUsing Check Boxes and Radio Buttons<!--- Name: form2.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 2</title> </head> <body> <!--- Payment and mailing list form ---> <form action="form2_action.cfm" method="POST"> Please fill in this form and then click <strong>Process</strong>. <p> <!--- Payment type radio buttons ---> Payment type:<br> <input type="radio" name="PaymentType" value="Cash">Cash<br> <input type="radio" name="PaymentType" value="Check">Check<br> <input type="radio" name="PaymentType" value="Credit card">Credit card<br> <input type="radio" name="PaymentType" value="P.O.">P.O. <p> <!--- Mailing list checkbox ---> Would you like to be added to our mailing list? <input type="checkbox" name="MailingList" value="Yes"> <p> <input type="submit" value="Process"> </form> </body> </html> Figure 12.4 shows how this form appears in your browser. Figure 12.4. You can use input types of option buttons and check boxes to facilitate the selection of options. Before you create form2_action.cfm to process this form, you should note a couple of important points. First, look at the four lines of code that make up the Payment Type radio button selection: <input type="radio" name="PaymentType" value="Cash">Cash<br> <input type="radio" name="PaymentType" value="Check">Check<br> <input type="radio" name="PaymentType" value="Credit card">Credit card<br> <input type="radio" name="PaymentType" value="P.O.">P.O. Each one contains the exact same name attributename="PaymentType". The four <input> fields have the same name so your browser knows they are part of the same set. If each radio button had a separate name, the browser wouldn't know that these buttons are mutually exclusive and thus would allow the selection of more than one button. Another important point: Unlike <input> type text, radio buttons don't prompt the user for any textual input. Therefore, you must use the value attribute for the browser to associate a particular value with each radio button. The code value="Cash" instructs the browser to return the value Cash in the PaymentType field if that radio button is selected. Now that you understand radio button and check box fields, you're ready to create a template to process them. Create a template called form2_action.cfm using the template code in Listing 12.4. Listing 12.4. form2_action.cfmProcessing Option Buttons and Check Boxes<!--- Name: form2_action.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 2</title> </head> <body> <!--- Display feedback to user ---> <cfoutput> <!--- Payment type ---> Hello,<br> You selected <strong>#FORM.PaymentType#</strong> as your payment type.<br> <!--- Mailing list ---> <cfif MailingList IS "Yes"> You will be added to our mailing list. <cfelse> You will not be added to our mailing list. </cfif> </cfoutput> </body> </html> The form processing code in Listing 12.4 displays the payment type the user selects. The field PaymentType is fully qualified with the FORM field type to prevent name collisions. When the check box is selected, the value specified in the value attribute is returned; in this case, the value is Yes. If the value attribute is omitted, the default value of on is returned.
Now, execute form2.cfm in your browser, select a payment option, and select the mailing list check box. Click the Process button. Your browser display should look like Figure 12.5. Figure 12.5. You can use ColdFusion templates to process user-selected options. That worked exactly as intended, so now get ready to complicate things a little. Reload template form2.cfm and submit it without selecting a payment type or by leaving the MailingList check box unselected. ColdFusion generates an error message, as shown in Figure 12.6. As you can see, the field you don't select generates an element is undefined error. Figure 12.6. Option buttons or check boxes that are submitted with no value generate a ColdFusion error. Check the code in Listing 12.3 to verify that the form fields do in fact exist. Why does ColdFusion report that the form field doesn't exist? That is one of the quirks of HTML forms. If you select a check box, the on value is submitted; but, nothing is submitted if you don't select the check boxnot even an empty field. The same is true of radio buttons: If you make no selection, the field isn't submitted at all. (This behavior is the exact opposite of the text <input> type, which returns empty fields as opposed to no field.) How do you work around this limitation? You could modify your form processing script to check which fields exist by using the #IsDefined()# function and, if the field exists, process it. But the simpler solution is to prevent the browser from omitting fields that aren't selected. You can modify the radio button field so that one radio button is pre-selected. This way, users will have to make a selection or use the pre-selected option. To pre-select a radio button, just add the attribute checked to it. Check boxes are trickier because by their nature they must be able to be turned off. Check boxes are used for on/off states, and, when the check box is off, there is no value to submit. The solution here is to set a default value in the action template. As you have already learned, this can be done easily using the <cfparam> tag. Look at this code: <cfparam NAME="FORM.MailingList" default="No"> When ColdFusion encounters this line, it checks to see whether a variable named FORM.MailingList exists. If it does, processing continues. If it doesn't exist, ColdFusion creates the variable and sets the value to whatever is specified in the default attribute. The key here is that either waywhether the variable exists or notthe variable does exist after the <cfparam> tag is processed. It is therefore safe to refer to that variable further down the template code. The updated form is shown in Listing 12.5. The first option button in the PaymentType field is modified to read <input type="radio" name="PaymentType" value="Cash" checked>. The checked attribute ensures that a button is checked. The MailingList check box has a value of Yes when it is checked, and the <cfparam> in the action page ensures that if MailingList is not checked, the value automatically is set to No. Listing 12.5. form3.cfmPre-Selecting Form Field Values<!--- Name: form3.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 3</title> </head> <body> <!--- Payment and mailing list form ---> <form action="form3_action.cfm" method="POST"> Please fill in this form and then click <strong>Process</strong>. <p> <!--- Payment type radio buttons ---> Payment type:<br> <input type="radio" name="PaymentType" value="Cash" CHECKED>Cash<br> <input type="radio" name="PaymentType" value="Check">Check<br> <input type="radio" name="PaymentType" value="Credit card">Credit card<br> <input type="radio" name="PaymentType" value="P.O.">P.O. <p> <!--- Mailing list checkbox ---> Would you like to be added to our mailing list? <input type="checkbox" name="MailingList" value="Yes"> <p> <input type="submit" value="Process"> </form> </body> </html> Create and save this template as form3.cfm. Then create a new file named form3_action.cfm containing the code in form2_action.cfm, and add the following code to the top of the page (right below the comments): <!--- Initialize variables ---> <cfparam name="MailingList" default="No"> Try using it and experiment with the two fields. You'll find that this form is reliable and robust, and it doesn't generate ColdFusion error messages, no matter which options are selected (or not). Processing List BoxesAnother field type you will frequently use is the list box. Using list boxes is an efficient way to enable users to select one or more options. If a list box is created to accept only a single selection, you can be guaranteed that a value is always returned. If you don't set one of the options to be pre-selected, the first one in the list is selected. An option always has to be selected. List boxes that allow multiple selections also allow no selections at all. If you use a multiple-selection list box, you once again have to find a way to ensure that ColdFusion doesn't generate variable is undefined errors. Listing 12.6 contains the same data-entry form you just created, but it replaces the option buttons with a list box. Save this template as form4.cfm, and then test it with your browser. Listing 12.6. form4.cfmUsing a <select> List Box for Options<!--- Name: form4.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 4</title> </head> <body> <!--- Payment and mailing list form ---> <form action="form3_action.cfm" method="POST"> Please fill in this form and then click <strong>Process</strong>. <p> <!--- Payment type select list ---> Payment type:<br> <select name="PaymentType"> <option value="Cash">Cash</option> <option value="Check">Check</option> <option value="Credit card">Credit card</option> <option value="P.O.">P.O.</option> </select> <p> <!--- Mailing list checkbox ---> Would you like to be added to our mailing list? <input type="checkbox" name="MailingList" value="Yes"> <p> <input type="submit" value="Process"> </form> </body> </html> For this particular form, the browser display shown in Figure 12.7 is probably a better user interface. The choice of whether to use radio buttons or list boxes is yours, and no hard and fast rules exist as to when to use one versus the other. The following guidelines, however, might help you determine which to use:
Figure 12.7. You can use HTML list boxes to select one or more options. Processing Text AreasText area fields are boxes in which the users can enter free-form text. When you create a text area field, you specify the number of rows and columns of screen space it should occupy. This area, however, doesn't restrict the amount of text users can enter. The field scrolls both horizontally and vertically to enable the users to enter more text. Listing 12.7 creates an HTML form with a text area field for user comments. The field's width is specified as a number of characters that can be typed on a single line; the height is the number of lines that are displayed without scrolling. TIP The <textarea> cols attribute is specified as a number of characters that can fit on a single line. This setting is dependent on the font in which the text is displayed, and the font is browser specific. Be sure you test any <textarea> fields in more than one browser because a field that fits nicely in one might not fit at all in another. Listing 12.7. form5.cfmUsing a <textarea> Field<!--- Name: form5.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 5</title> </head> <body> <!--- Comments form ---> <form action="form5_action.cfm" method="POST"> Please enter your comments in the box provided, and then click <strong>Send</strong>. <p> <textarea name="Comments" rows="6" cols="40"></textarea> <p> <input type="submit" value="Send"> </form> </body> </html> Listing 12.8 contains ColdFusion code that displays the contents of a <textarea> field. Listing 12.8. form5_action.cfmProcessing <textarea> Fields<!--- Name: form5_action.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 5</title> </head> <body> <!--- Display feedback to user ---> <cfoutput> Thank you for your comments. You entered: <p> <strong>#FORM.comments#</strong> </cfoutput> </body> </html> Figure 12.8 shows the <textarea> field you created, and Figure 12.9 shows how ColdFusion displays the field. Figure 12.8. The HTML <textarea> field is a means by which you can accept free-form text input from users. Figure 12.9. Without ColdFusion output functions, <textarea> fields are not displayed with line breaks preserved. Try entering line breaks (by pressing the Enter key) in the text field and then submit it. What happens to the line breaks? Line break characters are considered white-space characters (just like spaces) by your browser, and all white space is ignored by browsers. WHITE SPACE IS IGNORED is displayed no differently than WHITE SPACE IS IGNORED The only way to display line breaks is to replace the line break with an HTML paragraph tag: <p>. You therefore have to parse through the entire field text and insert <p> tags wherever necessary. Fortunately, ColdFusion makes this task a simple one. The ColdFusion #ParagraphFormat()# function automatically replaces every double line break with a <p> tag. (Single line breaks aren't replaced because ColdFusion has no way of knowing whether the next line is a new paragraph or part of the current one.) NOTE The ColdFusion Replace() and ReplaceList() functions can be used instead of ParagraphFormat() to have greater control over the paragraph formatting. These functions are explained in Appendix C, "ColdFusion Function Reference." The code in Listing 12.9 contains the same comments form as the one in Listing 12.7, with two differences. First, default field text is provided. Unlike other <input> types, <textarea> default text is specified between <textarea> and </textarea> tagsnot in a value attribute. Second, you use the wrap attribute to wrap text entered into the field automatically. wrap="virtual" instructs the browser to wrap to the next line automatically, just as most word processors and editors do. Listing 12.9. form6.cfmThe HTML <textarea> Field<!--- Name: form6.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 6</title> </head> <body> <!--- Comments form ---> <form action="form6_action.cfm" method="POST"> Please enter your comments in the box provided, and then click <strong>Send</strong>. <p> <textarea name="Comments" rows="6" cols="40" wrap="virtual"> Enter your comments here ... </textarea> <p> <input type="submit" value="Send"> </form> </body> </html> Listing 12.10 shows the template to display the user-supplied comments. The Comments field code is changed to #ParagraphFormat(FORM.Comments)#, ensuring that multiple line breaks are maintained and displayed correctly, as shown in Figure 12.10. Listing 12.10. form6_action.cfmUsing ParagraphFormat<!--- Name: form6_action.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 6</title> </head> <body> <!--- Display feedback to user ---> <cfoutput> Thank you for your comments. You entered: <p> <strong>#ParagraphFormat(FORM.comments)#</strong> </cfoutput> </body> </html> Figure 12.10. You should use the ColdFusion ParagraphFormat() function to display <textarea> fields with their line breaks preserved. Processing ButtonsThe HTML forms specification supports only two types of buttons. Almost all forms, including all the forms you create in this chapter, have a submit button. Submit, as its name implies, instructs the browser to submit the form fields to a Web server. TIP Most newer browsers actually require no submit button at all, and force a submit if the Enter key is pressed. The second supported button type is reset. Reset clears all form entries and restores default values if any existed. Any text entered into <input type="text"> or <textarea> fields is cleared, as are any check box, list box, and option button selections. Many forms have reset buttons, but you never need more than one. On the other hand, you might want more than one submit button. For example, if you're using a form to modify a record, you could have two submit buttons: one for Update and one for Delete. (Of course, you also could use two forms to accomplish this task.) If you create multiple submit buttons, you must name the button with the name attribute and be sure to assign a different value attribute for each. The code in Listing 12.11 contains a reset button and two submit buttons. Listing 12.11. form7.cfmTemplate with a Reset<!--- Name: form7.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 7</title> </head> <body> <!--- Update/delete form ---> <form action="form7_action.cfm" method="POST"> <p> Movie: <input type="text" name="MovieTitle"> <p> <!--- Submit buttons ---> <input type="submit" name="Operation" value="Update"> <input type="submit" name="Operation" value="Delete"> <!--- Reset button ---> <input type="reset" value="Clear"> </form> </body> </html> The result of this code is shown in Figure 12.11. Figure 12.11. When you're using multiple submit buttons, you must assign a different value to each button. When you name submit buttons, you treat them as any other form field. Listing 12.12 demonstrates how to determine which submit button was clicked. The code <cfif FORM.Operation IS "Update"> checks whether the Update button was clicked, and <cfelseif FORM.Operation IS "Delete"> checks whether Delete was clicked, but only if Update was not clicked. Listing 12.12. form7_action.cfmMultiple Submit Button Processing<!--- Name: form7_action.cfm Author: Ben Forta (ben@forta.com) Description: Introduction to forms Created: 12/20/04 ---> <html> <head> <title>Learning ColdFusion Forms 7</title> </head> <body> <!--- User feedback ---> <cfoutput> <cfif FORM.Operation IS "Update"> <!--- Update button clicked ---> You opted to <strong>update</strong> #MovieTitle# <cfelseif FORM.Operation IS "Delete"> <!--- Delete button clicked ---> You opted to <strong>delete</strong> #MovieTitle# </cfif> </cfoutput> </body> </html> |
See Chapter 8, "Using ColdFusion," for a detailed discussion of the ColdFusion <cfoutput> tag.
EAN: N/A
Pages: 282