How do I build a form that lets me edit existing data?

Your TerraForm form can be used to allow input of new data or to edit existing data. TerraForm will look in the locations you specify as it attempts to fill in the form. If it doesn't find any data for a field, it will insert a default value or simply leave it blank.

To get started, write a query to retrieve the data for your form from your database. This could be as simple as:

<cfquery name="myQuery" datasource="myDsn">
  SELECT *
  FROM   members
  WHERE  memberId = #form.memberId#
</cfquery>

or as complicated as you like. Add the following attribute to your cf_terraform tag:

inputScopeList="myQuery"

TerraForm will look in this record set for columns matching the names of each of your fields, and include any data it finds. Many developers consider using matching form field names and database column names a best practice. However, if your columns and fields don't match, we recommend that you use aliases in your query. For example:

<cfquery name="myQuery" datasource="myDsn">
  SELECT fname AS firstName,
         lname AS lastName
  FROM   members
  WHERE  memberId = #form.memberId#
</cfquery>

That's all you need to know to deal with most situations. However, TerraForm provides a few extra features you may need from time to time.

1. The "input scope list" doesn't necessarily need to be the name of a query — it is simply a place TerraForm should look. Your input scope could be a genuine ColdFusion scope such as request or session or it could be a structure such as request.memberDetails.
2. You can specify more than one input scope and TerraForm will search through each in turn. Thus you can have a hierarchy of input sources, or you can simply fill in your fields based on two different queries for whatever reason. For example:

   InputScopeList="member,request.defaultMemberDetails"

3. You can specify input scopes for individual form fields, using the same inputscopelist attribute on the cf_terrafield tag. TerraForm will look in the field's scopes before the form's scopes.
   
   
4. While regular fields take data from just the first row of a query, fields that allow multiple selected values (such as checkboxes) will read a value from each row in a query record set. For example:

   <cf_terrafield
     name="interestId"
     format="checkbox"
     query="allInterests"
     valuecolumn="interestId"
     displayColumn="interestName"
     inputscopelist="myInterests"
   />

   Here, allInterests is a query record set containing all the possible interests the member could pick from, whereas myInterests contains this member's previously selected interests. myInterests is a query record set containing one column (interestId) but multiple rows, one for each ID corresponding to one of the member's interests. TerraForm will read the entire column, and check the appropriate interests.