Structures are similar to the data types that we've discussed to this point, and they are quite similar to arrays. The main difference is that a value within a structure is not identified by an index. However, it can be called by name.
ColdFusion structures utilize familiar dot notation, such as MyStructure.Name, to identify a structure name and key. This type of identification is much more manageable in an application setting where you need to be able to associate a variable name with its value. Believe me, you can easily get lost in the index numbers and values of an array.
One structure that is typical to ColdFusion applications is the form. When you submit a form, you pass key/value pairs to the action page. The form structure keys are represented by the form control names and the values are those associated with each form control. These values are stored in a structure called form. I'm sure that you're familiar with outputting variables such as form.name, form.address, and form.email. You might not have known it, but you were outputting values from a structure.
Creating a Structure
It's easy to create a structure in ColdFusion. Structures are created by using the StructNew() function. The function call does not require any additional parameters. Let's stay with our authors and email theme for a bit longer and try the following code:
There's nothing more to it than that.
Adding Elements to a Structure
After you have created a structure, it remains empty until you add data to it. There are different ways to add data to a structure. These methods vary in the syntax technique that is used:
Let's look at some real code that shows what you've learned so far about structures and that employs each method of adding data:
<cfset st_AuthorData=StructNew()> <cfset st_AuthorData.FullName="Neil Ross"> <cfset tmp=StructInsert(st_AuthorData, "Email", "email@example.com")> <cfset st_AuthorData["City"]="Mechanicsburg">
Now let's dump this structure and check out how it differs from an array or query object:
Outputting a Structure
Outputting a structure key value is simple. You just use the dot notation that we looked at earlier to specify the structure and key:
Now let's put it all together in Listing 7.7 and see what you've learned:
Listing 7.7 Outputting AuthorData Structure
<html> <head> <title>Inside ColdFusion MX - Structures</title> </head> <body> <table> <tr> <td> <!--- Create the structure ---> <cfset st_AuthorData=StructNew()> <!--- Set structure key/value pairs ---> <cfset st_AuthorData.FullName="Neil Ross"> <cfset st_AuthorData.Email="firstname.lastname@example.org"> <cfset st_AuthorData.City="Mechanicsburg"> <cfset st_AuthorData.State="Pennsylvania"> <cfset st_AuthorData.FavoriteTeam="Arkansas Razorbacks"> <!--- Dump the structure because we can ---> <cfdump var="#st_AuthorData#"> <br> <br> <!--- Output the structure ---> <cfoutput> The author's name is: #st_AuthorData.FullName#<br> He can be reached by email at: #st_AuthorData.Email#<br> He currently resides in: #st_AuthorData.City#, #st_AuthorData.State#<br> His favorite team is: #st_AuthorData.FavoriteTeam# </cfoutput> </td> </tr> </table> </body> </html>
Figure 7.8 shows what the template generates in a browser.
Figure 7.8. AuthorData structure in a browser.
If you need to loop through the entire structure and output all the key values, you'll want to code a collection loop. A collection loop loops over a component object model (COM) collection or a ColdFusion structure. It's similar to the simple index loop that we did for the one-dimensional array. Let's take a look at the syntax:
<cfloop collection="structure_name" item="key"> <cfoutput>code code code</cfoutput> </cfloop>
The collection attribute names the structure through which your code will loop. The item attribute identifies the variable that holds the values, or keys of the structure, through which you want to loop. Examine the following code, which demonstrates the use of a collection loop to output the key/value pairs in the st_AuthorData structure:
<cfset st_AuthorData=StructNew()> <cfset st_AuthorData.FullName="Neil Ross"> <cfset st_AuthorData.Email="email@example.com"> <cfset st_AuthorData.City="Mechanicsburg"> <cfloop collection="#st_AuthorData#" item="key"> <cfoutput> #key# - #StructFind(st_AuthorData,key)# </cfoutput><br> </cfloop>
Once again, ColdFusion gives us a number of native functions to manipulate our structures:
Popular structure functions include the following:
If you're going to be using structures in your ColdFusion applications, consider all the structure functions and put together a dummy structure to run tests, as we've done in the preceding example.