Structure example

Structures are particularly useful for grouping together a set of variables under a single name. The example in this section uses structures collect information from a form, and to submit that information to a custom tag, named cf_addemployee. For information on creating and using custom tags, see Chapter 10, "Creating and Using Custom CFML Tags".

Example file newemployee.cfm

The following ColdFusion page shows how to create structures and use them to add data to a database. It calls the cf_addemployee custom tag, which is defined in the addemployee.cfm file.

<html>

<head>
<title>Add New Employees</title>
</head>

<body>
<h1>Add New Employees</h1>
<!--- Action page code for the form at the bottom of this page --->

<!--- Establish parameters for first time through --->
<cfparam name="Form.firstname" default="">
<cfparam name="Form.lastname" default="">
<cfparam name="Form.email" default="">
<cfparam name="Form.phone" default="">
<cfparam name="Form.department" default="">

<!--- If at least the firstaname form field is passed, create
   a structure named employee and add values --->
<cfif #Form.firstname# eq "">
  <p>Please fill out the form.</p>
<cfelse>
  <cfoutput>
   <cfscript>
    employee=StructNew();
    employee.firstname = Form.firstname;
    employee.lastname = Form.lastname;
    employee.email = Form.email;
    employee.phone = Form.phone;
    employee.department = Form.department;
   </cfscript> 

<!--- Display results of creating the structure --->
   First name is #StructFind(employee, "firstname")#<br>
   Last name is #StructFind(employee, "lastname")#<br>
   EMail is #StructFind(employee, "email")#<br>
   Phone is #StructFind(employee, "phone")#<br>
   Department is #StructFind(employee, "department")#<br>
  </cfoutput>

  <!--- Call the custom tag that adds employees --->
  <cf_addemployee empinfo="#employee#">
</cfif>

<!--- The form for adding the new employee information --->
<hr>
<form action="newemployee.cfm" method="Post">
First Name:&nbsp;
<input name="firstname" type="text" hspace="30" maxlength="30"><br>
Last Name:&nbsp;
<input name="lastname" type="text" hspace="30" maxlength="30"><br>
EMail:&nbsp;
<input name="email" type="text" hspace="30" maxlength="30"><br>
Phone:&nbsp;
<input name="phone" type="text" hspace="20" maxlength="20"><br>
Department:&nbsp;
<input name="department" type="text" hspace="30" maxlength="30"><br>

<input type="Submit" value="OK">
</form>
<br>
</body>
</html>

Reviewing the code

The following table describes the code:

Code

Description

<cfparam name="Form.firstname" default=""> <cfparam name="Form.lastname" default=""> <cfparam name="Form.email" default=""> <cfparam name="Form.phone" default=""> <cfparam name="Form.department" default="">

Set default values of all form fields so that they exist the first time this page is displayed and can be tested.

<cfif #form.firstname# eq ""> Please fill out the form.<br>

Test the value of the form's firstname field. This field is required. The test is False the first time the page displays.

If there is no data in the Form.firstname variable, display a message requesting the user to fill the form.

<cfelse> <cfoutput> <cfscript> employee=StructNew(); employee.firstname = Form.firstname; employee.lastname = Form.lastname; employee.email = Form.email; employee.phone = Form.phone; employee.department = Form.department; </cfscript> First name is #employee.firstname#<br> Last name is #employee.lastname#<br> EMail is #employee.email#<br> Phone is #employee.phone#<br> Department is #employee.department#<br> </cfoutput>

If Form.firstname contains text, the user submitted the form.

Use CFScript to create a new structure named employee and fill it with the form field data.

Then display the contents of the structure

cf_addemployee empinfo="#duplicate(employee)#"> </cfif>

Call the cf_addemployee custom tag and pass it a copy of the employee structure in the empinfo attribute.

The duplicate function ensures that the custom tag gets a copy of the employee structure, not the original. While this is not necessary in this example, it is good practice because it prevents the custom tag from modifying the calling page's structure contents.

<form action="newemployee.cfm" method="Post"> First Name:  <input name="firstname" type="text" hspace="30" maxlength="30"><br> Last Name:  <input name="lastname" type="text" hspace="30" maxlength="30"><br> EMail:  <input name="email" type="text" hspace="30" maxlength="30"><br> Phone:  <input name="phone" type="text" hspace="20" maxlength="20"><br> <p>Department:  <input name="department" type="text" hspace="30" maxlength="30"><br> <br> <input type="Submit" value="OK"> </form>

The data form. When the user clicks Submit, the form posts the data to this ColdFusion page.

Code	Description
<cfparam name="Form.firstname" default=""> <cfparam name="Form.lastname" default=""> <cfparam name="Form.email" default=""> <cfparam name="Form.phone" default=""> <cfparam name="Form.department" default="">	Set default values of all form fields so that they exist the first time this page is displayed and can be tested.
<cfif #form.firstname# eq ""> Please fill out the form.<br>	Test the value of the form's firstname field. This field is required. The test is False the first time the page displays. If there is no data in the Form.firstname variable, display a message requesting the user to fill the form.
<cfelse> <cfoutput> <cfscript> employee=StructNew(); employee.firstname = Form.firstname; employee.lastname = Form.lastname; employee.email = Form.email; employee.phone = Form.phone; employee.department = Form.department; </cfscript> First name is #employee.firstname#<br> Last name is #employee.lastname#<br> EMail is #employee.email#<br> Phone is #employee.phone#<br> Department is #employee.department#<br> </cfoutput>	If Form.firstname contains text, the user submitted the form. Use CFScript to create a new structure named employee and fill it with the form field data. Then display the contents of the structure
cf_addemployee empinfo="#duplicate(employee)#"> </cfif>	Call the cf_addemployee custom tag and pass it a copy of the employee structure in the empinfo attribute. The duplicate function ensures that the custom tag gets a copy of the employee structure, not the original. While this is not necessary in this example, it is good practice because it prevents the custom tag from modifying the calling page's structure contents.
<form action="newemployee.cfm" method="Post"> First Name:  <input name="firstname" type="text" hspace="30" maxlength="30"><br> Last Name:  <input name="lastname" type="text" hspace="30" maxlength="30"><br> EMail:  <input name="email" type="text" hspace="30" maxlength="30"><br> Phone:  <input name="phone" type="text" hspace="20" maxlength="20"><br> <p>Department:  <input name="department" type="text" hspace="30" maxlength="30"><br> <br> <input type="Submit" value="OK"> </form>	The data form. When the user clicks Submit, the form posts the data to this ColdFusion page.

Example file addemployee.cfm

The following file is an example of a custom tag used to add employees. Employee information is passed through the employee structure (the empinfo attribute). For databases that do not support automatic key generation, you must also add the Emp_ID.

<cfif StructIsEmpty(attributes.empinfo)>

  <cfoutput>
    Error. No employee data was passed.<br>
  </cfoutput>
  <cfexit method="ExitTag">
<cfelse>
  <!--- Add the employee --->
  <cfquery name="AddEmployee" datasource="cfsnippets">
    INSERT INTO Employees
      (FirstName, LastName, Email, Phone, Department)
    VALUES (
    '#attributes.empinfo.firstname#' ,
    '#attributes.empinfo.lastname#' ,
    '#attributes.empinfo.email#' ,
    '#attributes.empinfo.phone#' ,
    '#attributes.empinfo.department#' )
  </cfquery>
</cfif>
<cfoutput>
  <hr>Employee Add Complete
</cfoutput>

Reviewing the code

The following table describes the code:

Code

Description

<cfif StructIsEmpty(Attributes.empinfo)> <cfoutput> Error. No employee data was passed. </cfoutput> <cfexit method="ExitTag">

If the custom tag was called without an empinfo attribute, display an error message and exit the tag.

<cfelse> <cfquery name="AddEmployee" datasource= "cfsnippets"> INSERT INTO Employees (FirstName, LastName, Email, Phone, Department) VALUES ( '#attributes.empinfo.firstname#' , '#attributes.empinfo.lastname#' , '#attributes.empinfo.email#' , '#attributes.empinfo.phone#' , '#attributes.empinfo.department#' ) </cfquery> </cfif>

Add the employee data passed in the empinfo structure to the Employees table of the cfsnippets database.

Use direct references to the structure entries, not structfind functions.

If the database does not support automatic generation of the Emp_ID key, you must add an Emp_ID entry to the form and add it to the query.

<cfoutput> <hr>Employee Add Complete </cfoutput>

Display a completion message. This code does not have to be inside the cfelse block because the cfexit tag prevents it from being run if the empinfo structure is empty.

Developing ColdFusion MX Applications with CFML
Using Arrays and Structures

Code	Description
<cfif StructIsEmpty(Attributes.empinfo)> <cfoutput> Error. No employee data was passed. </cfoutput> <cfexit method="ExitTag">	If the custom tag was called without an `empinfo` attribute, display an error message and exit the tag.
<cfelse> <cfquery name="AddEmployee" datasource= "cfsnippets"> INSERT INTO Employees (FirstName, LastName, Email, Phone, Department) VALUES ( '#attributes.empinfo.firstname#' , '#attributes.empinfo.lastname#' , '#attributes.empinfo.email#' , '#attributes.empinfo.phone#' , '#attributes.empinfo.department#' ) </cfquery> </cfif>	Add the employee data passed in the empinfo structure to the Employees table of the cfsnippets database. Use direct references to the structure entries, not `structfind` functions. If the database does not support automatic generation of the Emp_ID key, you must add an Emp_ID entry to the form and add it to the query.
<cfoutput> <hr>Employee Add Complete </cfoutput>	Display a completion message. This code does not have to be inside the `cfelse` block because the `cfexit` tag prevents it from being run if the empinfo structure is empty.

Structure example

Example file newemployee.cfm

Reviewing the code

Example file addemployee.cfm

Reviewing the code

Comments