For Adobe ColdFusion application servers How it works: a technical overview

From the visitor's perspective

Here's what happens when a visitor encounters and submits a TerraForm form. Here we are assuming a setup as described in the Recommended Implementation.

  1. The visitor loads the URL of a ColdFusion page.
    1. The page includes the form controller file.
    2. The controller file includes the form file.
    3. The TerraForm tags are encountered.
      • TerraForm detects no status field and decides this is a new form.
      • TerraForm renders the form, inserting default values and placing the hidden status field at the bottom. The form action address is set to the current .
    4. Processing returns to the controller file.
    5. The controller file checks to see if the form submission is valid by checking the status field. It isn't.
    6. The page finished rendering.
  2. The visitor completes the form, but fills it in incorrectly. The visitor submits the form.
    1. The page includes the form controller file.
    2. The controller file includes the form file.
    3. The TerraForm tags are encountered.
      • TerraForm detects the status field and decides this is a submitted form.
      • TerraForm validates the form. The form fails validation.
      • TerraForm renders the form, inserting the submitted values and placing the hidden status field at the bottom. TerraForm highlights the error fields and places some explanatory messages at the top of the form.
    4. Processing returns to the controller file.
    5. The controller file checks to see if the form submission is valid by checking the status field. It isn't.
    6. The page finished rendering.
  3. The visitor corrects the errors on the form and resubmits it.
    1. The page includes the form controller file.
    2. The controller file includes the form file.
    3. The TerraForm tags are encountered.
      • TerraForm detects the status field and decides this is a submitted form.
      • TerraForm validates the form. This time, the form passes validation.
      • TerraForm discards the form markup and sets the form status field to "valid".
    4. Processing returns to the controller file.
    5. The controller file checks to see if the form submission is valid by checking the status field. It is valid.
    6. The controller file includes the form handler. This handler might insert the form data into a database, or perhaps send an email message.
    7. A cflocation tag is used to move the visitor to another address. This stops the user from inadvertantly resubmitting the form.

The tags

This section describes what is going on behind the scenes when the ColdFusion server encounters each TerraForm custom tag. Note that this overview is simplified and skips some minor steps.

<cf_terraForm>

  1. TerraForm variables and settings are initialised.
  2. TerraForm decides whether it is rendering a new form, or a form that has been submitted already. It does this by inspecting the value of a hidden status HTML field that has the same name as the form.

<cf_terraLabel/>

  1. As each cf_terraLabel tag is encountered, the data is copied into an array of field labels that will be available to the cf_terraForm closing tag.
  2. For each tag, a placeholder is inserted into the .

<cf_terraField/>

  1. As each cf_terraField tag is encountered, the data is copied into an array of fields that will be available to the cf_terraForm closing tag.
  2. For each field, a placeholder is inserted into the .

<cf_terraRule/>

  1. As each cf_terraRule tag is encountered, the data is copied into an array of rules that will be available to the cf_terraForm closing tag.

</cf_terraForm>

  1. For each field, TerraForm incorporates any preset values, sets the datatype and format, checks browser compatibility.
  2. For each field, TerraForm searches for a value, looking in the form scope * , the field's inputScopeList, the form's inputScopeList, and finally the field default. It accepts the first value it finds, even if that value is blank.
  3. If the form is new:
    1. TerraForm loops through each of the fields generating markup for each one.
    2. TerraForm searches the page for field placeholders and inserts the markup for each field.
    3. TerraForm adds the hidden status field to the bottom of the form.
    4. TerraForm displays the new, empty form.
  4. If the field has already been submitted:
    1. TerraForm loops through all the fields cleaning up the submitted values.
    2. TerraForm validates each field in various ways:
      • First it checks for missing required fields.
      • Next it checks that the right type of data has been entered in each field.
      • Next it checks that the data conforms to built-in rules such as min or maxlength.
      • Next it checks that any boolean rules set with cf_terraRule validate.
      • Finally, if a custom validation template has been supplied, then TerraForm includes that file.
    3. At this point, TerraForm has a list of error fields and error messages. If both lists are empty then the form has passed validation.
    4. If the form has failed validation:
      • TerraForm loops through each of the fields generating markup for each one.
      • TerraForm searches the page for field placeholders and inserts the markup for each field.
      • TerraForm adds the hidden status field to the bottom of the form.
      • TerraForm displays the failed form with submitted data includes, error fields highlit, and a list of error messages displayed at the top of the form.
    5. If the form has passed validation:
      • TerraForm loops through all the fields tidying up the submitted values.
      • TerraForm discards the entire content between the opening and closing cf_terraForm tags.
      • TerraForm sets the hidden status field "valid".

* The cf_terraForm scope attribute defines the primary scope for the form, and defaults to form. If the attribute has been set to another value such as attributes then TerraForm will look there first and ignore the form scope.
Uniform Resource Locator
HyperText Markup Language
The coding language used to create hypertext documents for use on the World Wide Web.
No comments yet