Getting started on your own server

Installing TerraForm

1. Download the TerraForm Core Package and unzip it to your Desktop.
   
   
2. Copy the content of the customtags folder to your server's custom tags folder (something like c:\cfusion\customtags\ or c:\cfusionmx\customtags\).
   
   
3. Set up a working folder where you can experiment with TerraForm (for example, c:\inetpub\wwwroot\terraform\ or c:\cfusionmx\wwwroot\terraform\).
   
   
4. Copy the terraformresources folder to your working folder. The terraformresources folder contains files that need to be located beneath your website root, including images and JavaScript files. Each site you build using TerraForm will need this folder, but you can rename it and place it anywhere in your site (this time though, leave it as is).
   
   

A simple form

Copy the following code into a new file, form1.cfm. If you run it, you should see a small blank form.

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 </cf_terraform> 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 <cf_terrafield/> tags for the two fields. You may notice the /> at the end. This is shorthand for a closing </cf_terrafield> tag. All <cf_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

        <cf_terrafield
          name="name"
          datatype="string"
          required="yes"
        />

with

        <cf_terrafield
          name="name"
          datatype="string"
          required="yes"
        >Bohumil Hrabal</cf_terrafield>

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:

<cf_terrafield
  name="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!