Using <CFFORM> To use ColdFusion for client-side form validation, we must use ColdFusion forms as opposed to the plain HTML variety of forms we have using to this point. ColdFusion forms closely mirror HTML forms in style and structure. We create a ColdFusion form by using the <CFFORM> tag to begin our form, and then we add various CFFORM elements to the form such as <CFINPUT> boxes and <CFSELECT> menus. These form elements are much the same as their HTML counterparts, except they usually have a few extra attributes. As a matter of fact, you can mix normal HTML form elements and CFFORM elements in the same ColdFusion form. Using the <CFFORM> Tag We use the <CFFORM> tag in much the same fashion as an <HTML> form tag. The two even perform much the same function. The major difference between the two is that the <CFFORM> tag enables us to include special ColdFusion form elements, and it will automatically write JavaScript form validation code for us. The <CFFORM> tag also takes the METHOD and ACTION attributes (amongst others) that we would normally include in an HTML <FORM>. Common <CFFORM> elements include ColdFusion tags such as <CFINPUT> and <CFSELECT>, which are very similar to their HTML cousins. There are other ColdFusion form elements that have no HTML equivalents, but we will not be discussing them here. For a complete list of ColdFusion form elements and attributes, see the "Reference" section of the accompanying web site at www.LearnColdFusionMX.com. Using the <CFINPUT> Tag The <CFINPUT> tag is almost identical in function to the standard HTML <INPUT> tag except that it has a few more attributes. See Table 5.2 for a complete list of <CFINPUT> attributes and their descriptions. Table 5.2. <CFINPUT> Attributes| Attribute | Description | Notes |
|---|
| CHECKED | Makes a check box or radio button preselected | Only used if the TYPE attribute is CHECKBOX or RADIO | | MAXLENGTH | The maximum number of characters | The same as the HTML attribute | | MESSAGE | A validation failure message | The error message a user will see if validation fails | | NAME | The unique name of the form element | The same as the HTML attribute | | ONERROR | JavaScript error function | Used to override your own JavaScript message | | ONVALIDATE | JavaScript validation function | Used to select a JavaScript validation function if you do not want to use the ColdFusion generated function | | PASSTHROUGH | For unsupported HTML attributes | Used to pass HTML <INPUT> attributes not directly supported by <CFINPUT> | | RANGE | Used to set a minimum or maximum range | Used to specify a numeric range; entered as two numbers separated by a comma | | REQUIRED | YES or NO | Indicates whether a value is mandatory | | SIZE | Field size | The same as the HTML attribute | | TYPE | TEXT, RADIO, CHECKBOX, or PASSWORD | The same as the HTML attribute | | VALIDATE | Field validation type | Used to set an option field validation type (see Table 5.3) | | VALUE | Used to set an initial value | The same as the HTML attribute |
Like its HTML cousin, the <CFINPUT> tag is positioned within a <CFFORM>. The <CFINPUT> tag can be used for various types of input, depending on the value of its TYPE attribute. It can become a text box, check box, radio button, or password box. The following code shows a <CFINPUT> text box that is required and that will display a custom error message if the user tries to leave the text box blank. [View full width] <CFINPUT TYPE="Text" NAME="UserName" MESSAGE="Please enter a valid username" REQUIRED="Yes"> You can also get <CFINPUT> fields to validate against several different types of data by including the VALIDATE attribute and one of the validation types listed in Table 5.3. The following line of code illustrates how to validate a field to make sure it contains a credit card number. [View full width] <CFINPUT TYPE="Text" NAME="CCNumber" MESSAGE="Please enter a valid number" VALIDATE="creditcard" REQUIRED="Yes"> Table 5.3. <CFINPUT> Validation Types| Validation Type | Description |
|---|
| CREDITCARD | Checks for a correctly formatted credit card number | | DATE | Checks for a date in the MM/DD/YY format | | EURODATE | Checks for a date in the DD/MM/YY format | | FLOAT | Checks for numbers, which can include decimal point values | | INTEGER | Checks for numbers, which cannot include decimal point values | | SOCIAL_SECURITY_NUMBER | Checks for the U.S. social security format (such as 123-45-6789), using spaces or hyphens to separate groups | | TELEPHONE | Checks for the U.S. telephone number format (such as 123-456-7890), using spaces or hyphens to separate groups | | TIME | Checks for a time value in hh:mm or hh:mm:ss format | | ZIPCODE | Checks for a U.S. zip code in either five- or nine-digit format |
Using the <CFSELECT> Tag The <CFSELECT> tag functions much like its HTML cousin, with a couple of notable exceptions. First, you can make the field required. Second, <CFSELECT> comes with built-in support for generating a list of options from a database query. To generate a list of options for a <CFSELECT> list from a database query, you must first define the query in the template using a <CFQUERY> tag. Next, include the QUERY attribute of the <CFSELECT> tag to nominate which query should be used to build a list of options. You then use the DISPLAY and VALUE attributes of the <CFSELECT> tag to specify what value to display for each option and what value each option should pass when the form is submitted. For a complete list of <CFSELECT> attributes, see to Table 5.4. Table 5.4. <CFSELECT> Attributes| Attribute | Description | Notes |
|---|
| DISPLAY | Query column/field name | Query column/field to use as display text for list OPTION | | MESSAGE | Validation failure message | The error message a user will see if validation fails | | MULTIPLE | Allows multiple list selections | The same as the HTML attribute | | NAME | The unique name of the FORM element | The same as the HTML attribute | | ONERROR | JavaScript error function | Used to override your own JavaScript message | | PASSTHROUGH | For unsupported HTML attributes | Used to pass HTML <SELECT> attributes not directly supported by <CFINPUT> | | QUERY | Query name | The name of the query used to populate <CFSELECT> list OPTION | | REQUIRED | YES or NO | Indicates whether a value is mandatory | | SELECTED | Selected value | Used to mark one of the Options as selected, as in HTML | | SIZE | List size | The same as the HTML attribute | | VALUE | Query column/field name | Query column/field to use as VALUE attribute for list Option |
Listing 5.7 shows the code necessary to create a data-driven <CFSELECT> list. We specify the query at the top of the page. The <CFSELECT> tag's QUERY attribute nominates this as the query from which to construct its list of OPTIONs. The DISPLAY attribute specifies which value to display for each OPTION (in this case, the DepartmentName field from the query) and which VALUE (DepartmentID) to pass for each OPTION. We also have thrown in our own option (searching all departments) and have made this the list default using the SELECTED attribute. Listing 5.7 Query Driven <CFSELECT> List [View full width] <!--- get department information for the select menu ---> <CFQUERY NAME="qDepartments" DATASOURCE="Staff"> SELECT DepartmentID, DepartmentName FROM Departments ORDER BY DepartmentName </CFQUERY> <HTML> <HEAD> <TITLE>CFSELECT Demo</TITLE> </HEAD> <BODY> <CFFORM ACTION="action page" METHOD="POST" ENABLECAB="Yes"> <CFSELECT NAME="Depts" QUERY="qDepartments" VALUE="DepartmentID" DISPLAY="DepartmentName"> <OPTION VALUE="" SELECTED>All Depts</OPTION> </CFSELECT> </CFFORM> </BODY> </HTML> Figure 5.14 shows what this list would look like in the browser. Figure 5.14. The <CFSELECT> browser display. Figure 5.15 shows the results of a View, Source command and the resulting HTML select list that has been built by ColdFusion. Note the <OPTION> tags and their values. Figure 5.15. The form source code. |