Getting started on a shared server

Installing TerraForm

1. Set up a working folder where you can experiment with TerraForm (for example, c:\inetpub\wwwroot\terraform\ or c:\cfusionmx\wwwroot\terraform\).
   
   
2. Download the TerraForm Core Package and unzip it to your Desktop.
   
   
3. Copy the customtags and terraformresources folders to the working folder you just created.
   
   

A simple form

Copy the following code into a new file, form1.cfm. If you run it, you should see a small blank form. You will note that we are setting up two variables at the top of the page to make our form code easier to read. These are the relative paths from this page to the TerraForm tags. terraform.cfm and terrafield.cfm are both custom tags that could be called using the <cf_terraform.../> syntax. However, since you are using a shared server, the <cfmodule.../> syntax illustrated here is probably more convenient. [For more information, see Different ways to call custom tags]

Show Me!

Try hitting the "Enter" button on the form. You'll notice the form just keeps returning. Type something in the "Name" field and hit "Enter". You'll notice the form remembers what you typed after you submit it. What's happening here? The form is being rejected during validation, but it's not telling us why. We must specify a location in the HTML to insert the error messages. Add the following lines under the opening table tag and try again.

  <messagesblock>
    <tr>
      <td colspan="2">
        <messages>
      </td>
    </tr>
  </messagesblock>

Show Me!

You should see messages appearing at the top of the form that tell you what the problems are. <messages> is a placeholder. When TerraForm decides there are errors it looks for this placeholder and inserts the error messages in its place. If there are any errors it also includes the entire section inside the messagesblock tags, and if not it discards that entire section. Here, if there are errors a new table row is added. If not, then the table row is dispensed with.

With TerraForm helping you to fill in the form correctly, you'll quickly discover nothing happens when you are successful. Add the following lines after the </cfmodule> at the bottom (the closing form tag). We'll keep this simple, but in a real application you would typically want to include a handler template (that might write the info to the database), followed by a cflocation to a thank you page.

<cfif Form.Form1 EQ "Valid">
  <p>Thank you <cfoutput>#Form.Name#</cfoutput>!</p>
</cfif>

Show Me!

In a long form it is useful to have the names of the fields that are in error highlighted. In order to do that, we need to indicate to TerraForm which labels go with which fields. In a form like this it's easy, but a complex form may have a much more confusing layout. We mark the labels by adding the attribute labelfor="fieldname" to the <td>s for the words "Name:" and "Age:", as follows:

      <td labelfor="name">
        Name:
      </td>
      .
      .
      .
      <td labelfor="age">
        Age:
      </td>

Show Me!

OK! so we've created a form with two required fields, where the second one must be an integer greater than or equal to 18. Look at the <cfmodule template="#terrafield#" /> tags for the three fields. You may notice the /> at the end. This is shorthand for a closing </cfmodule> tag. All <cfmodule template="#terrafield#" /> tags must be closed. If you wrap them around something, then the content between the tags is taken as the default value — rather like the way a <textarea/> tag pair works. Try it here. Replace

        <cfmodule
          template="#terrafield#"
          fieldname="name"
          datatype="string"
          required="yes"
        />

with

        <cfmodule
          template="#terrafield#"
          fieldname="name"
          datatype="string"
          required="yes"
        >Bohumil Hrabal</cfmodule>

Show Me!

There he is in the name field: a Czech novelist (use your name if you like!). Another way to add defaults is like this:

<cfmodule
	  template="#terrafield#"
	  fieldname="age"
	  datatype="integer"
	  required="yes"
	  min="18"
	  default="94"
	/>

Show Me!

— as an attribute. Use whichever you prefer. Try replacing the age field with this new code.

By now you will have noticed the minimum value: "18". You can also specify a maximum value using the max attribute. If you want an age 18 years or younger, you can specify max="18". But remember that integers stretch infinitely in both directions, while ages are never less than 0. So you should also specify min="0".

That's about all we can learn from this form. There's just one final point of clarification: the labelfor attributes and the messagesblock and messages tags are not some new tags you haven't heard about. But they're not invalid either, as TerraForm will examine them and either remove them completely or replace them with valid . They are just placeholders.

Summary

In this example we have built a basic form with data validation, default values, and error messages. The completed form:

Show Me!