This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
Macromedia ColdFusion MX Development Copyright 2002 by Que
Executive Editor Candace Hall
Acquisitions Editor
All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from the publisher. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions. Nor is any liability assumed for damages resulting from the use of the information contained herein.
Lloyd Black
International Standard Book Number: 0789726939
Copy Editor
Library of Congress Catalog Card Number: 2002103038
Chuck Hutchinson
Printed in the United States of America First Printing: July 2002 05
04
03
02
Development Editor Maureen A. McDaniel
Technical Editor David Swim
Managing Editor Tom Hayes
Project Editor Natalie Harris
Indexer Kelly Castell
Proofreader 4
3
2
1
Jessica McCarty
Team Coordinator
Trademarks
Cindy Teeters
All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Que cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.
Interior Designer Trina Wurst
Cover Designer Radar Design
Page Layout
Warning and Disclaimer Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness is implied. The information provided is on an “as is” basis. The author and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book.
About the Author Eric Ladd ([email protected]) is a Macromedia Certified Advanced ColdFusion Developer and a principal and senior developer for NetLink Resource Group in Alexandria, Virginia. NetLink specializes in custom application development for Internet, intranet, and extranet systems and has served the Web development needs of clients such as the U.S. Postal Service, Litton/PRC (currently Northrop Grumman), MCI, Digex, Marriott International, the National Institutes of Health, and the Pan American Health Organization. Eric has coauthored six books for the Que imprint of Pearson Technology Group. Prior to this book, his most recent effort was Platinum Edition Using XHTML, XML, and Java 2 (ISBN: 0-7897-2473-1), which received positive critical and reader reviews and is currently used at many universities as a comprehensive Web development text. In addition to the books he has coauthored, Eric has made authoring and technical editing contributions to 10 other Que titles. On top of his development and writing activities, Eric holds faculty appointments with the George Washington University in Washington, D.C., and EEI Communications in Alexandria, Virginia, where he teaches classes in dynamic Web technologies such as JavaScript, ColdFusion, and Active Server Pages. Outside of work, Eric enjoys hitting the gym, biking, and being dragged around the Metro D.C. area by his boxers Zack and Ripley.
Dedication In memory of my mother, Beth Ladd.
Acknowledgments Eric is grateful to the staff of Que Publishing for the opportunity to work on this book. Special thanks to Todd Green for lunch in Chicago and helping to formulate the idea for the book, to Acquisitions Editor Lloyd Black for his vigilance in keeping the book on schedule, to Development Editor Maureen McDaniel for ensuring a high-quality final product, to Copy Editor Chuck Hutchinson for sharing his gift for the lost art of good grammar, and to Karen Shields and Natalie Harris for shepherding the book through the final review and preproduction processes. Special thanks also to David Swim, who, in his debut role as a Technical Editor, called attention to numerous fixes and improvements. Additionally, Eric would also like to thank those who were supportive, patient, and understanding while he disappeared yet again to write another book. Special recognition to Dad in Remsen, New York; Brenda in Richmond, Virginia; and to many good friends and colleagues: Bob Leidich, Gordon Vivace, Shane Orzechowski, Kathy Webb, Melissa Robison, Carolyn McHale, Michele Keen, Randy Bowers, Mike Miller, Jim O’Donnell, Joe Barrios, Gus Ventura, John Malone, Mark Thompson, and Tim Law.
Tell Us What You Think! As the reader of this book, you are our most important critic and commentator. We value your opinion and want to know what we’re doing right, what we could do better, what areas you’d like to see us publish in, and any other words of wisdom you’re willing to pass our way. As an Executive Editor for Que, I welcome your comments. You can fax, e-mail, or write me directly to let me know what you did or didn’t like about this book— as well as what we can do to make our books stronger. Please note that I cannot help you with technical problems related to the topic of this book, and that due to the high volume of mail I receive, I might not be able to reply to every message. When you write, please be sure to include this book’s title and author as well as your name and phone or fax number. I will carefully review your comments and share them with the author and editors who worked on the book. Fax:
Executive Editor, Programming Que 800 East 96th Street Indianapolis, IN 46240 USA
Introduction About This Book Welcome to the world of ColdFusion development! This book was written to guide you through the basics of using Macromedia ColdFusion MX to develop dynamic, database-driven Web sites and applications. You’ve chosen to become a ColdFusion developer at a great time in its history. The development environment is at its most robust and powerful level with more than 75 basic instructions and 240 built-in functions at your disposal. ColdFusion’s performance and scalability are at all-time highs, and the ColdFusion Application Server has been rewritten in Java, meaning that you can deploy it on any server that has Java support. ColdFusion continues to power more and more dynamic Web sites, so the skills you develop in working with this book will always be in demand and valuable. As a ColdFusion developer, you’ll find that you’re part of an active and vibrant community that sponsors regional user groups, seminars, and mailing lists that you can post to when you encounter challenging programming requirements. Macromedia’s DevCon developers conference is a fantastic annual event where you can increase your knowledge, become certified in ColdFusion development, catch glimpses of how ColdFusion will continue to evolve, and network with other developers like yourself. Be sure to check Macromedia’s site (http://www.macromedia.com/) for dates and locations. If you’re like most developers, you’ll find the effort you put into mastering ColdFusion to be both personally and professionally enjoyable. We’re glad you chose this book to help you with that effort!
How to Use This Book Students learning ColdFusion always crave examples, and this book provides broad and instructive sets of examples showing how to work with ColdFusion. The many examples included in this book are there for you to type in, tweak, experiment with, and adapt to your own purposes. Most are inspired by functionality found in real-world applications, meaning that you’ll be working with very relevant and valuable code. Be sure to explore each example thoroughly and don’t be afraid to make mistakes! You can learn a lot about programming from your errors, too. Another important aspect of the examples in this book is that they illustrate best practices in ColdFusion programming. You should focus on incorporating these best practices into your own coding habits. Not only will this make your code easier to maintain, in many cases it will also help your applications to run more efficiently.
2
Introduction
Who Should Use This Book ColdFusion MX Development was written with the ColdFusion beginner in mind. A number of good books have been written about ColdFusion, but few, if any, are in a tutorial style that welcomes a newcomer to ColdFusion programming. This book fills that void by providing an example-driven way to learn ColdFusion that starts from first principles. After you complete this book, or if you’ve had some beginning-level exposure to ColdFusion, you should consider moving on to a more intermediate level book that discusses some of the more advanced features of ColdFusion MX.
How This Book Is Organized Each chapter of the book covers an important ColdFusion foundation skill. The coverage of each chapter is as follows: Chapter 1, “The ColdFusion Development Environment,” explains the different components that make up a ColdFusion-based Web server and what tools you can use to assist in your development work. Chapter 2, “Variables and Variable Scope,” introduces you to the many different kinds of variables in the ColdFusion environment and how you can use them to accomplish tasks such as processing data submitted from an HTML form. Chapter 3, “Implementing Conditional Logic,” demonstrates how to construct ifthen rules that govern how ColdFusion responds to different situations. Chapter 4, “Interacting with Databases: Retrieving Data,” shows you how to query a database and use the returned data to construct a dynamic Web page. Chapter 5, “Interacting with Databases: Inserting, Updating, and Deleting,” explains how to perform database queries other than data retrieval. You’ll learn how to collect data via an HTML form and create a new record in a relational database table. You’ll also learn how to edit and delete existing records. Chapter 6, “Using ColdFusion Lists, Arrays, and Structures,” shows you how to use some special data structures and their accompanying functions to store and manipulate data more efficiently. Chapter 7, “Implementing ColdFusion Loops,” introduces you to the different kinds of iterative instructions you can implement with ColdFusion. Chapter 8, “Sending E-mail with ColdFusion,” shows you how to compose and send dynamic e-mail messages. You’ll also learn how you can get ColdFusion to answer the mail. Chapter 9, “Troubleshooting Your ColdFusion Code,” provides you with tips and techniques for chasing down some of the common errors that come up during ColdFusion development.
Introduction
Chapter 10, “Adding JavaScript to Your Forms,” demonstrates how you can use ColdFusion to soup up your HTML forms with JavaScript that enforces required fields and validates user input. Chapter 11, “Maintaining State Information,” explains how you can build “memory” into your dynamic Web sites. With it, you can remember important information, such as the contents of a person’s shopping cart. Chapter 12, “Using the ColdFusion Application Framework,” describes the features of ColdFusion that help you to bring many individual ColdFusion scripts together to work in concert as an application. Chapter 13, “Creating a Search Engine with Verity,” shows you how to set up a basic search engine on your site by using Verity, a free-text search tool that comes bundled with ColdFusion. Chapters 14, 15, and 16 provide short case studies in how to use ColdFusion to build three common Web-enabled sites. In Chapter 14, “Case Study: Corporate Intranet Directory,” you’ll see how to develop an employee directory for a corporate intranet, including tools for managing the names in the directory. Chapter 15, “Case Study: Conference Registration Site,” shows you how to develop a site that registers conference attendees. Chapter 16, “Case Study: Online Store,” walks you through the basic steps of building an online store. The appendixes contain references on how to use the ColdFusion tags and functions you’ll learn about over the course of the book. Appendix A, “ColdFusion Markup Language Tag Reference,” summarizes the usage and syntax of the tags, and Appendix B, “ColdFusion Markup Language Functions,” does the same thing for the functions.
Conventions Used in This Book This book uses several common conventions to help teach ColdFusion. Some of the typographical conventions used in the book include the following: • Commands and computer output appear in a special monospaced computer font. • New terms being introduced are in italics. • Any lines of code that are too long to fit across a single line will be broken across two or more lines, and a code continuation character (➥) will appear on the subsequent lines. In addition to the typographical conventions, the following special elements are used to bring special information to your attention:
3
4
Introduction
NOTE Notes augment the material you read in each chapter. These notes clarify concepts and programming practices.
TIP Tips offer shortcuts and solutions to common problems.
CAUTION Cautions warn you about roadblocks and potential pitfalls that can occur while you’re developing ColdFusion applications.
What’s Next Now that you have a sense of what this book is all about, it’s time to jump in and begin your exploration of the ColdFusion development environment. Chapter 1 introduces you to the basic elements of this environment: the ColdFusion Application Server, the ColdFusion Administrator, and ColdFusion Studio.
1 The ColdFusion Development Environment As the Internet has become more pervasive in the business world, developers have come under increased pressure to build Web applications that support their companies’ mission-critical business functions. As with any Web-based deliverable, these applications need “to be done yesterday” and also are expected to scale effortlessly with the growth of the business. These stringent requirements have compelled developers to seek development environments in which they can quickly build, test, and deploy the applications their companies need. Macromedia’s ColdFusion continues to be a favorite application development platform among Web programmers who need to be able to rapidly deploy complex, interactive sites. This chapter introduces you to the ColdFusion application development environment. In this chapter, you’ll • Learn how the ColdFusion Application Server processes requests for ColdFusion pages • Tour the ColdFusion Administrator, a browser-based interface that enables you to configure the ColdFusion Application Server • Learn about ColdFusion Studio, a useful tool for authoring ColdFusion templates
8
Chapter 1: The ColdFusion Development Environment
What Is ColdFusion? ColdFusion is a Web application development environment produced by the Macromedia Corporation. The primary component of the ColdFusion environment is the ColdFusion Application Server, a service that processes the ColdFusion scripting instructions that you write. The Application Server works together with your Web server to produce dynamically generated HTML pages as shown in Figure 1.1. Databases CF Page
E-mail
HTTP Request Internet or Intranet
Web Server
Cold Fusion Application Server
Directories
File System
Web Browser Web page
Web page
COM/DCOM
Web Servers
Client
Network
Server
Figure 1.1 Requests for ColdFusion templates are handed off to the ColdFusion Application Server, which processes the embedded programming instructions and generates the HTML page that is delivered to the browser. The major steps in the delivery of a ColdFusion-based page are as follows: 1. A user makes an HTTP request for a file containing ColdFusion code (called a ColdFusion template) or submits a form that has a ColdFusion template as its action attribute. ColdFusion templates end with the extension .cfm. 2. The Web server recognizes the request for a ColdFusion template and hands the template over to the ColdFusion Application Server for processing. 3. The ColdFusion Application Server parses out the programmatic instructions, makes all necessary calls to other services on the network (database servers, mail servers, directory servers, and so on), performs any required data manipulation, and then prepares an HTML document as its response to the HTTP server.
What Is ColdFusion?
9
4. The HTML document is returned to the Web server, which, in turn, sends it to the user’s browser. You give instructions to the ColdFusion Application Server through the ColdFusion Markup Language (CFML), a tag-based language that you embed inside HTML code to produce a ColdFusion template. In addition to the tags, CFML features scores of useful built-in functions that enable you to easily handle programming constructs such as query recordsets, arrays, strings, lists, dates, and variables. In addition to its capability to interact with ODBC- and OLE DB-compliant databases, ColdFusion extends its usefulness with the capability to interact with other services running on your server. They include • The local file system • Other HTTP servers • FTP servers • Mail servers • Lightweight Directory Access Protocol (LDAP) directory servers • Verity search engine collections • Java applets • COM/DCOM objects Thus, performing basic tasks common to many Web-based applications becomes easy. In an electronic commerce application, for example, you could gather a user’s purchases as he or she shops, storing them as an HTTP cookie or as a ColdFusion session variable. At checkout time, you appeal to the cookie or session variable for the user’s purchases and present them for confirmation. Then you collect the user’s credit card information, stashing it in your customer database, and e-mail a receipt confirming the purchase. All these steps are simple to implement when you use ColdFusion. W H AT E L S E D O I N E E D TO K N OW TO D E V E L O P C O L D F U S I O N A P P L I C AT I O N S ? Understanding the ColdFusion development environment and mastering CFML are two important steps in becoming proficient in developing ColdFusion applications. To do serious application development, however, you also should be versed in the following skills: • HTML—CFML instructions are embedded inside HTML code, so to excel at ColdFusion development, you need to truly understand HTML and be able to work with raw HTML code. • Relational database design—You should have a command of data modeling theory and know how to express your model in terms of fields and tables in a relational database
10
Chapter 1: The ColdFusion Development Environment
• Structured Query Language (SQL)—SQL is the language used to interact with back-end relational databases. SQL is a useful language to know, regardless of the programming technology you use. • JavaScript—You can combine JavaScript and ColdFusion to produce applications more powerful and flexible than those you could create with ColdFusion alone. For example, client-side JavaScript that validates form data before it is submitted frees up the ColdFusion Application Server from having to perform the same task. Thus, your server has more resources to dedicate to the tasks that it absolutely has to perform. You will most definitely need to have a basic understanding of HTML, SQL, and relational database design to become a competent ColdFusion developer. After you feel well-grounded in these basics, you can then move on to building JavaScript-enabled ColdFusion applications. Knowing JavaScript, however, is not an absolute prerequisite for being able to develop with ColdFusion.
The ColdFusion Application Server The ColdFusion MX Application Server can run on any operating system that has a Java Virtual Machine (JVM). Before the MX release, different releases of ColdFusion were available for many different operating systems. Rather than continue to support multiple platforms, Macromedia decided to recode the ColdFusion Application Server in Java, thereby making ColdFusion deployable on any machine that supports Java. ColdFusion can work with a wide variety of HTTP servers as well: • Netscape servers, such as FastTrack or Enterprise • Microsoft Internet Information Server (IIS) • Apache Installing the ColdFusion Application Server on any platform is fairly straightforward. On a Windows machine, you are walked through the process over the course of several dialog boxes that prompt you for information such as the directory where you want to install ColdFusion, which Web server ColdFusion will be working with, and what password you want to use with the ColdFusion Administrator and ColdFusion Studio. If you’re doing a Unix or Linux installation, you simply need to launch the installation file and respond to the few questions you’re asked during the install process. After you install the application server, you can immediately check to see whether it is working properly by accessing the ColdFusion documentation page at http://127.0.0.1/CFDOCS/dochome.htm. There, you can find links to help and documentation in HTML and PDF formats (see Figure 1.2).
Using the ColdFusion Administrator
11
Figure 1.2 The ColdFusion documentation page puts a wealth of ColdFusion information at your fingertips. NOTE The IP address 127.0.0.1 is reserved for addressing the Web server running on the machine on which you installed ColdFusion.
With the ColdFusion Application Server installed, you then can configure the server using the ColdFusion Administrator. The Administrator is a ColdFusion application that lets you look under the hood of the ColdFusion engine and tweak it for optimum performance. The many functions of the Administrator are discussed in the next section.
Using the ColdFusion Administrator A lot is going on behind the scenes within the ColdFusion development environment, and you can orchestrate all aspects of this activity through the ColdFusion Administrator. Specifically, you can • Create and configure data sources • Restrict the use of potentially harmful CFML tags • Activate debugging messages that enable you to troubleshoot your applications more easily
12
Chapter 1: The ColdFusion Development Environment
• Specify how and where the ColdFusion Application Server should log certain events • Configure the ColdFusion Application Server to work with an electronic mail server • Create searchable Verity collections • Install custom CFML tags • Register Java applets To access the ColdFusion Administrator, access the URL http://127.0.0.1/CFIDE/administrator/index.cfm and enter the Administrator password you specified during the installation of the ColdFusion Application Server. After you’re authenticated, you see a page such as the one in Figure 1.3.
Figure 1.3 You can control the ColdFusion development environment through a browser-based interface. The main administrator page is split into two frames. The left frame contains links that enable you to quickly navigate to the major parts of the Administrator. The right frame displays the settings that you can change within a given part. The next several sections of this chapter walk you through the various parts of the Administrator and point out the
Using the ColdFusion Administrator
13
ColdFusion environment parameters that you can control through the Administrator.
Configuring the ColdFusion Application Server If you click the Settings link under the Server Settings section in the left frame, you’ll see the configuration options shown in Figure 1.4. These options include • Number of simultaneous requests—You can enhance the application server’s performance by limiting the number of requests that it can simultaneously process. Any requests beyond this limiting number are queued in memory and processed in the order in which they are received. • Request timeout—You can specify a certain number of seconds after which the processing of a template will time out. This option helps you to avoid situations in which infinite loops or other programming glitches might bog down your server. NOTE Even if you specify a timeout value, you should keep in mind that users can override this value by adding a RequestTimeOut parameter to the URL of the ColdFusion template they are calling. If you have the timeout set to 30 seconds, for example, a user could circumvent this setting by entering a URL such as http://www.cfserver.com/template.cfm?RequestTimeOut=300
The RequestTimeOut parameter passed with the URL will increase the timeout value for that request to 300 seconds instead of the 30 seconds you specified in the Administrator.
• UUID for cftoken—ColdFusion uses a cookie called cftoken to assist in session management. Normally cftoken’s value is a randomly assigned number, but enabling this option prompts ColdFusion to use a Universally Unique Identifier (UUID) for cftoken’s value. • Enable HTTP Status Codes—When enabled, this option instructs ColdFusion to add HTTP status codes for unhandled pages. • Whitespace management—Previous versions of ColdFusion put in whitespace characters where CFML instructions were parsed out of the template. This extra whitespace often made for cumbersomely large HTML files generated as a result of the template being processed. If you suppress whitespace, ColdFusion will consolidate all whitespace down to a single character, allowing your resulting HTML file to transfer and load more quickly.
14
Chapter 1: The ColdFusion Development Environment
NOTE You have to restart the ColdFusion service if you enable whitespace suppression in order for this change to take effect.
• Missing template and error handlers—In the event that a user requests a template that is not on the server or that an error occurs during the processing of a template, you can direct the user to a customized page that alerts him or her to the problem. This process is analogous to setting up a custom 404 page on an HTTP server.
Figure 1.4 On the ColdFusion Administrator Server Settings page, you can specify general parameters for the way the application server operates.
Setting Up Mappings Sometimes setting up a logical path or alias to a long directory path is much easier than typing that path again and again. You can set up this path through the ColdFusion Administrator’s Mappings page (see Figure 1.5). To set up a directory mapping, enter the logical path in the first text field, enter the actual directory path into the second text field, and then click the Add Mapping button.
Using the ColdFusion Administrator
15
Figure 1.5 You can shorten long, tedious directory paths by setting up aliases in the ColdFusion Administrator. TIP It’s easier to use the built-in Java applet to browse the server when you’re specifying the directory path. This way, you also reduce the chance of your making a mistake while typing in the path.
Using ColdFusion with a Mail Server You can send electronic mail messages from your ColdFusion applications after you configure ColdFusion to work with your mail server. Figure 1.6 shows the Mail Server portion of the ColdFusion Administrator, which you can call up by clicking the Mail Server link in the left frame. Here, you can tell the ColdFusion Application Server the name or IP address of your mail server, the server port it should use (typically port 25), and a connect timeout value. NOTE Your mail server administrator may have to make some configuration changes on the mail server to allow ColdFusion to send e-mail messages. If your mail messages don’t seem to be going through, check with the administrator to see whether the mail server is configured to accept and forward mail messages originating from your ColdFusion server’s IP address.
16
Chapter 1: The ColdFusion Development Environment
Figure 1.6 Telling ColdFusion some information about your mail server is an important prerequisite for sending electronic mail through ColdFusion applications.
Setting Up Data Sources ColdFusion can communicate with databases on the same server or, in some cases, on a remote server, provided that a data source that “points to” that database is available. ColdFusion can work with Open Database Connectivity (ODBC) and Object Linking and Embedding (OLE DB) data sources. If you click the Data Sources link, you’ll see a page like the one shown in Figure 1.7. Here, you create, modify, test, and delete data sources. These data sources are pointers to database files, together with specifications on how ColdFusion should interact with the database. TIP Clicking the Verify All Connections button near the bottom of the page tests the connection to all your data sources.
The initial page of the Data Sources section contains a list of all the available data sources and what kind of driver is being used to access the data source. Additionally, each data source has Edit, Verify, and Delete buttons next to it. When you click a Verify button, ColdFusion will test its connection to that data source and let you know if the test succeeded or failed.
Using the ColdFusion Administrator
17
Figure 1.7 In the Data Sources section of the ColdFusion Administrator, you specify which databases ColdFusion can use and how it should connect to those databases. To create a new data source, follow these steps: 1. Type the name of the data source into the text field at the top of the Data Source Name column. 2. Select which kind of driver you want to use from the drop-down list at the top of the page. 3. Click the button labeled Add to create the data source. The right frame will change to the page shown in Figure 1.8. NOTE The configuration of the screen you see in Figure 1.8 will be different for each kind of driver because each driver has its own specific parameters that need to be set.
4. Fill in the information requested on the page, making sure to specify the drive and directory path to the database file, if you’re using a filebased database like Microsoft Access, or the system database name, if you’re using a client/server database like Informix. ColdFusion comes with a Java applet that enables you to browse the drives and directories until you find the file you want.
18
Chapter 1: The ColdFusion Development Environment
Figure 1.8 When setting up a data source, you need to give it a name, specify the location of the database file, and set other driver-specific parameters. 5. At this point, you have two options. You can click the Submit button to create the data source and return to the initial data source page, or you can click the Show Advanced Settings button to reveal a more detailed version of the configuration page (see Figure 1.9).
Figure 1.9 You also can configure how ColdFusion interacts with the data source when you create it. 6. Choose values for the ColdFusion settings to associate with the data source. This includes values for the login timeout (how long ColdFusion will try to connect to the data source), the number of simultaneous connections to allow to the database, a special username and password for ColdFusion to use when logging in to the database, whether to maintain a connection to the database between requests, and any restrictions on SQL operations done against the database. You also can enable retrieval of text from long text fields in your database. Activating this feature can degrade the performance of your
Using the ColdFusion Administrator
19
server, so be sure to monitor performance data if you select it. The number of characters to be selected from the long text field is controlled by the long text buffer size. 7. Click the Submit button to create the data source and return to the main data source page. To edit an existing data source, click its name or its Edit button from the main data source page. Doing so takes you to a page that looks almost like the one in Figure 1.8. From there, you can edit the data source’s properties or click the Show Advanced Settings button to open an expanded edit page similar to the one in Figure 1.9. After you finish making your changes, click the Update button to save them. If you need to delete a data source, simply click the data source’s Delete button. CAUTION After you delete a data source, it will no longer be available to any of your ColdFusion applications. Before you delete a data source, make sure that none of your applications contain references to it. Also, keep in mind that deleting a data source is not the same as deleting the database it points to. If you want to delete the database, you need to do that through the database program itself (for client/server databases such as SQL Server and Oracle) or through your operating system’s file interface (for file-based databases such as Access or FoxPro).
Using the Verity Search Engine ✔ To learn how to set up a search engine on your site, see Chapter 13, “Creating a Search Engine with Verity.”
ColdFusion comes bundled with a version of the popular Verity search engine, enabling you to easily set up searchable sets of documents. In Verity vernacular, these sets of documents are called collections, and you can create your own collections from the ColdFusion Administrator’s Verity Collections page (see Figure 1.10). The Verity page is divided into three parts. The upper part enables you to create a new Verity collection. To do so, you type in a name for the collection, specify the directory where ColdFusion should store the collection, and provide a language context for the collection. The middle part shows any existing Verity collections and enables you to perform different operations on those collections. The most common task is to index a collection. When you click the Index button, you have the option of specifying (by file extension) which types of files you want to index, the directory you want to index, and whether you want to recursively index subdirectories. When Verity indexes a collection, it examines the contents of each file and builds the files that make up the collection.
20
Chapter 1: The ColdFusion Development Environment
Figure 1.10 Verity collections are groups of searchable documents that you can access through ColdFusion. NOTE Not only can Verity index commonly used text-based files (.html, .cfm, .txt, .rtf), but it also can index Adobe Acrobat PDF files and files generated by popular desktop software applications such as Microsoft Office.
The lower part is for managing Verity K2 collections. The Verity K2 service also does free-text searching but much more rapidly than the regular Verity service.
Using Debugging ColdFusion’s debugging feature is invaluable when you’re troubleshooting an application. Figure 1.11 shows the Debugging Settings section of the ColdFusion Administrator. The check boxes control what kinds of debugging messages you receive from the server. You can choose any combination of these options: • Enabling Debugging—When checked, this feature appends debugging information to the bottom of each page ColdFusion generates. You get to choose the information you want displayed in the Custom Debugging Output section of the page.
Using the ColdFusion Administrator
21
• Enable Robust Exception Information—When displaying custom debugging information, ColdFusion can include items like the physical path to the template, the names of your data sources, the SQL statements you’re executing, and the line number of the error. If you think that exposing this information could put your server at risk, then you should make sure that the Enable Robust Exception Information checkbox is not checked. • Enabling Performance Monitoring—On Windows machines, ColdFusion will interface with the Performance Monitor to make performance of the Application Server visible in the Performance Monitor display. For other operating systems, ColdFusion uses a utility called cfstat to gather and display performance information. • Enabling CFSTAT—If this box is checked, the cfstat utility will be enabled and available for use in tracking performance.
Figure 1.11 You can choose which kinds of debugging messages you want displayed during application development and testing. ColdFusion appends debugging information to the bottom of the HTML page it generates in response to a browser’s request. As you can see in Figure 1.12, the debugging information is easy to pick out from the rest of the document.
22
Chapter 1: The ColdFusion Development Environment
Figure 1.12 Debugging information always appears at the end of the ColdFusion page. NOTE The debugging information format you see in Figure 1.12 is called the “classic” format that has been the norm for releases of ColdFusion up through ColdFusion 5. ColdFusion MX also allows a new format called “dockable” in which debugging information is displayed in an expandable tree.
One nice feature about ColdFusion debugging information is that you can restrict the delivery of the information to a specific set of IP addresses but not to every user. Thus, if you and/or your development team all have fixed IP addresses, you can click the Debugging IP Addresses link and insert these addresses into the IP address list you see in Figure 1.13. That way, your developers will see debugging messages, but regular application users will not. TIP If your IP addresses are dynamically assigned, you might want to do your ColdFusion development and testing on a separate server and then port the finished application to a production server when you’re done. You then can turn on debugging for the development server without restricting the output to specific IP addresses, and your developers still can obtain debugging feedback.
Using the ColdFusion Administrator
23
Figure 1.13 Restricting debugging information to the IP addresses of your development team prevents users from seeing the information.
Scheduling ColdFusion Templates The ColdFusion Scheduler will execute templates at intervals you specify. This feature might be useful, for example, when you’re reporting to management. You could write a template that queries your e-commerce site’s sales figures from the previous day and puts them in a summary e-mail to the sales manager. To schedule a template, you first need to go to the Scheduled Task page of the ColdFusion Administrator. There, you’ll see a list of any tasks currently scheduled. If you click the Schedule New Task button, you’ll move to a page similar to the one shown in Figure 1.14.
Figure 1.14 ColdFusion templates can be run automatically according to schedules that you create.
24
Chapter 1: The ColdFusion Development Environment
When scheduling a task, you must provide information such as the following: • Start and end dates for the task. (ColdFusion assumes no end date if none is specified.) • The frequency of the task (once, daily, every 45 minutes, and so on). • The URL of the template and any login and proxy information needed to invoke the template. • The place to write the output from the template, should you choose to record it. After you enter all the scheduling parameters, click the Submit button to schedule the task. If you need to modify the task later, click the task name from the main Tasks page and make the edits on the Add/Edit Scheduled Task page (which looks exactly like the page in Figure 1.14). When you finish making your changes, click the Submit button to apply them.
Registering Applets ColdFusion works well with Java applets, but only after you’ve registered the applets with the ColdFusion Administrator. To register, click the Java Applets link in the Administrator and then click the Register New Applet button to open the page shown in Figure 1.15.
Figure 1.15 You can embed Java applets in your ColdFusion templates after you register them. The information you must provide on the applet registration page may look familiar to you if you use the HTML element frequently. The values for the code, codebase, method, height, width, vspace, hspace, and align attributes are exactly what you would put in the corresponding fields on
Using the ColdFusion Administrator
25
the registration page. ColdFusion will use this information to write out an element for you. The text entered in the Not Supported Message box is exactly what you might specify in an alt attribute, except what you enter through the ColdFusion Administrator can be marked up with HTML code. In the applet parameters section, you can specify the parameter/value pairs to be passed to the applet. Specifying these pairs is analogous to using the <param> element to pass parameters to an applet placed with the element.
Using Custom Tags Another of ColdFusion’s many great features is that you can develop your own tags when existing CFML tags won’t do the job. You can develop custom ColdFusion tags in CFML or in more complicated programming languages such as C++ or Java. After you develop a custom tag, you need to register it with the ColdFusion Administrator. To do so, click the CFX Tags link, choose the button corresponding to which language the tag is written in (C++ or Java), and then provide the requested information. This includes important details such as the supporting DLL, shared object, or .jar file; whether to keep the custom tag loaded in memory; and a description of the tag. NOTE All custom tags that you write in C++ or Java must begin with CFX_. Custom tags written in CFML begin with CF_ and can reside in the same directory as your other application templates. Alternatively, you can click the Custom Tag Paths link and set up your own paths for your custom tag libraries.
Changing Security Settings Clicking the Sandbox Security link in the Administrator takes you to the page you see in Figure 1.16. A “sandbox” is a collection of templates on your server that need a specific security configuration. You can add a sandbox to your server by entering the path to the templates that are to comprise the sandbox and then clicking the Add button. Assuming ColdFusion Security has been enabled by means of the checkbox at the top of the page, you will see your new sandbox listed with any existing sandboxes near the bottom of the page. After you have defined a sandbox, you can then apply the desired security settings to it by clicking on its Edit button. This brings you to a page where you can restrict access to data sources, use of CFML tags and functions, grant access permissions to files and directories, and restrict ColdFusion calls to various server and TCP/IP ports. Figure 1.17 shows the tab where
26
Chapter 1: The ColdFusion Development Environment
you can restrict the use of CFML tags. Each of the tags listed has a potentially harmful use on the server, so you may wish to consider disabling them. For example, can move, rename, or delete files anywhere on the server. Putting this kind of power into the wrong hands could have catastrophic results.
Figure 1.16 Security settings are applicable to areas called “sandboxes” that you set up on your server.
Setting Up Logging Like many applications, ColdFusion logs any errors it encounters while processing your templates. To access the Logging section of the ColdFusion Administrator, click the Logging Settings link you see in the Administrator. Here you can tell ColdFusion the directory where you want the ColdFusion logs stored, the maximum size of each log file, and the maximum number of archived log files. Additionally, you can instruct ColdFusion to log slow running pages, all CORBA calls, and all scheduled tasks by checking the appropriate options (see Figure 1.18).
Using the ColdFusion Administrator
27
Figure 1.17 You can protect your server from malicious code by restricting which CFML tags can be run.
Figure 1.18 ColdFusion Application Server errors are logged in files stored in a directory of your choosing.
28
Chapter 1: The ColdFusion Development Environment
ColdFusion classifies errors according to type and creates different log files for each type of error. The different log files include • application.log—Logs any errors that occur during the processing of a template. • executive.log—Records errors detected by the ColdFusion Executive (the overarching ColdFusion service). • mail.log—Logs any errors that occur during interactions with mail servers. • cfadmin.log—Records all activity in the ColdFusion Administrator. • scheduler.log—Contains any error messages generated by the ColdFusion Scheduler, which is responsible for making sure that templates scheduled to be run at specific times are actually processed. • server.log—Records any errors encountered by the ColdFusion Application Server. • migration.log—Notes any problems detected while migrating applications to a ColdFusion MX server. • webserver.log—Logs any HTTP errors that occur during a request for a ColdFusion template. NOTE A special option on the Mail Server page (refer to Figure 1.6) lets you log mail server error messages by their severity (Debug, Information, Warning, or Error), and you can choose to log the content of every e-mail that ColdFusion sends. You can access this page by first clicking the Mail Server link in the lefthand frame of the Administrator.
TIP If you opt to log all e-mail messages, make sure you archive the contents of the file periodically so that it does not become so large as to become unmanageable.
If you click the Log Files link, you can manage the log files themselves (see Figure 1.19). The Administrator enables you to read, search, download, store, or delete any of the individual files. TIP Be sure to check the Size column on the Log Files page before working with a particular file. If the file is large, searching, viewing, or downloading the file will take quite a while.
Using ColdFusion Studio
Figure 1.19 files.
29
The Log Files page gives you direct access to ColdFusion’s log
TIP You can implement your own custom log files by using the tag that was introduced in ColdFusion 5.0.
Using ColdFusion Studio ColdFusion templates must be plain text files, just as HTML documents are. So, technically, all you need to write ColdFusion templates is an editor that can write plain text files. This means that you could compose your templates using Notepad, Microsoft Word, or any HTML authoring tool that enables you to edit the raw code. Although any text editor is fine, you should seriously consider using Macromedia’s ColdFusion Studio as your development tool of choice for ColdFusion templates. Based on the popular authoring program HomeSite, ColdFusion Studio comes with many helpful features that directly support you as you write CFML code. This section introduces you to ColdFusion Studio and how to use Studio to make your development work much less tedious.
Customizing the ColdFusion Studio Interface Figure 1.20 shows the ColdFusion Studio user interface. The interface is toolbar oriented, and you have the option of displaying any or none of the toolbars. Additionally, you can customize many of the toolbars to include only the buttons you use frequently or buttons that you create. The major components of the interface include • Main Toolbar—The Main Toolbar contains buttons that perform common file-related tasks such as opening, saving, and printing, and editing tasks such as cutting, copying, and pasting. Buttons also launch Studio’s verification tools: a link checker, an HTML validator, and a spell checker.
30
Chapter 1: The ColdFusion Development Environment
• QuickBar—The QuickBar plays host to several tabs (all of which you can display or hide easily), including Common, Fonts, Tables, Frames, Lists, Forms, CFML, Script, and Active Server Pages (ASP). Each tab, in turn, contains buttons that place HTML and CFML tags into your documents. By putting the tags into logical groupings on the tabs, you can easily switch back and forth between sets of buttons as you need them.
Figure 1.20 of HomeSite.
The ColdFusion Studio user interface strongly resembles that
TIP To show or hide toolbars on the QuickBar, press Shift+F8 to open the Customize dialog box (see Figure 1.21). In the Toolbars window, all the available toolbars are listed. To include a toolbar on the QuickBar, make sure that the box next to the desired toolbar is checked.
• Editor Toolbar—The behavior of the editing window is controlled by the Editor Toolbar (located along the left side of the editing window). Buttons on this toolbar control properties such as word wrapping, block indenting, and numbering of the code lines. In addition, you can toggle the window between browser preview mode and edit mode and between full-screen and partial-screen modes.
Using ColdFusion Studio
31
Figure 1.21 You can configure the QuickBar to display only the toolbars you use regularly. TIP ColdFusion error diagnostic messages usually refer to a line number where it has detected the error, so having line numbering turned on in the editing window is helpful.
The remaining buttons on the Editor Toolbar support what Macromedia calls Studio’s What-You-See-Is-What-You-Need (WYSIWYN) feature. This includes Tag Completion (a container tag’s closing tag will automatically appear when you finish typing in the opening tag), Tag Tips (pop-up messages that show all the possible attributes permitted by the tag’s syntax), and Tag Insight (which provides a drop-down list of attributes the tag can take, enabling you to easily choose the ones you want). Figure 1.22 shows Tag Insight in action. NOTE With some practice, most users acclimate themselves to the WYSIWYN features and can develop more rapidly. If you find them more of a hindrance, you can suppress them by deselecting their buttons on the Edit Toolbar.
• Resource Tab—The Resource Tab typically appears to the left of the edit window, although you can change its position easily enough. The Resource Tab is itself tabbed to give you access to local and remote disk drives, ColdFusion data sources on remote servers, groups of related templates called projects, tag snippets (chunks of reusable code), and the full set of ColdFusion and ColdFusion Studio documentation in HTML format.
32
Chapter 1: The ColdFusion Development Environment
Figure 1.22 With Tag Insight activated, you can select which attributes you want to place inside a tag from a context-sensitive list.
Using the Resource Tab The Resource Tab is an incredibly useful window to many of the resources developers need while creating a ColdFusion application. This section takes a closer look at the tabs on the Resource Tab and what they let you access. In Figure 1.20, the Files Tab is open. When this tab is selected, the Resource Tab is divided into two windows. In the upper window, you can navigate drives and folders on your machine. As you change from one folder to another, the files in that folder appear in the lower window. Having the list of files at your disposal is very valuable. You can double-click a file to open it, drag and drop an HTML file or a ColdFusion template into the edit window to set up a link to it, or drag and drop an image file into the edit window to place the image in your document. NOTE ColdFusion Studio 5 adds a second Files Tab so you can more easily call up files that are on different drives or servers.
Notice that one of the options in the upper window is labeled Macromedia FTP & RDS. Choosing this option presents you with a list of remote servers like the one in Figure 1.23. ColdFusion Studio enables you to work with
Using ColdFusion Studio
33
remote servers via standard FTP or by a Remote Development Service (RDS) connection. When you use RDS, you are connecting to the server via the ColdFusion service. Regardless of how you’re connected, when you double-click a file on a remote server, the file is downloaded to your machine and presented in the edit window so that you can work on it. When you save your changes, Studio uploads the modified file to the remote machine.
Figure 1.23 No need to use a separate FTP client because ColdFusion Studio has one built right in. NOTE To set up a new remote server profile, right-click the Macromedia FTP & RDS entry at the top of the tree listing the servers and choose Add FTP Server or Add RDS Server as needed.
CAUTION If you don’t save frequently, your FTP connection may time out, and you’ll have to reconnect to the remote server.
The Database Tab enables you to access the system data sources on a remote server that’s running ColdFusion. This capability can be incredibly valuable during development, especially when you’re writing queries. Each data source on the server is presented in a tree structure that you can expand to display the tables, views, and queries stored in the corresponding database file. You also can expand a given table to display the database
34
Chapter 1: The ColdFusion Development Environment
columns that compose the table. Studio will show you not only the name of the column, but also its type and length (see Figure 1.24). Double-clicking a database table prompts Studio to download a copy of the table.
Figure 1.24 By connecting to a remote ColdFusion server through the Database Tab, you can view the tables, fields, and queries available under each data source on the server. Projects are groups of related files stored together. For example, you can group all the templates that support a single application into a project. After you group them, you can open, close, and save all the files simultaneously. Furthermore, you can perform search-and-replace operations across all the files, making it simple to deploy global changes in your applications. You can access the projects you’ve created through the Projects Tab on the Resources Tab. The Snippets Tab enables you to set up folders to hold frequently used blocks of code (see Figure 1.25). This is an excellent place to store code for standard headers and footers, common form controls (for example, a dropdown list of all 50 states—something that is painful to have to type each time you need it!), client-side imagemaps, and so on. Finally, the Help Tab gives you access to complete documentation on all CFML tags and functions, explanations of how to use and customize ColdFusion Studio, references for HTML and cascading style sheets, and information on how to contact Macromedia for technical support.
Using ColdFusion Studio
35
Figure 1.25 The Snippets Tab is like a big Clipboard where you can store chunks of code that you use frequently.
Using Special ColdFusion Studio Tools In addition to the excellent tag support provided by the Tag Toolbar and the easy access to resources through the Resource Tab, ColdFusion Studio also comes with a few other useful tools. This section takes a brief look at three of them: the Tag Chooser, the Expression Builder, and the SQL Builder. THE TAG CHOOSER Figure 1.26 shows the Tag Chooser, which you can activate by pressing Ctrl+E. Within the Chooser, all HTML and CFML tags are stored in an easy-to-navigate tree structure that enables you to zero in on the tags you want quickly. As you move through the tree structure, the various tags available are displayed in the right side of the Chooser. To insert one of the tags into your document, click it and then click the Select button in the lower right. THE EXPRESSION BUILDER You launch the ColdFusion Studio Expression Builder by pressing Ctrl+Shift+E. The Expression Builder is useful in two ways. First, it is helpful when you’re building complicated expressions that involve ColdFusion functions. You can see the expression in the window at the top of the Builder and edit it there as necessary (see Figure 1.27).
36
Chapter 1: The ColdFusion Development Environment
Figure 1.26 If you don’t like using the toolbars, the Tag Chooser can put all the HTML and CFML tags at your fingertips.
Figure 1.27 Can’t remember one of the CFML list functions? Look it up through the Expression Builder. The other useful feature of the Expression Builder is that it catalogs all CFML functions, constants, operators, and variables in the tree you see on the left side of the Builder. By navigating the tree, you can easily look up one of the CFML functions that are otherwise too numerous to commit to memory. As you move through the tree, the available functions, constants, operators, and variables are displayed in the right side of the Builder. After you finish composing your expression, clicking the Insert button places it into your template. THE SQL BUILDER If you need to use a query stored in one of your data sources or if you need to construct a new query, you can choose the Insert SQL Statement option from the Tools menu to open the window shown in Figure 1.28. From this window, you can connect to one of the ColdFusion servers that Studio is configured to work with and navigate to the Queries subtree of the data source you’re using. From there, you can choose one of the queries and insert it directly into your template.
Using ColdFusion Studio
37
Figure 1.28 ColdFusion Studio can easily grab a pre-existing query from one of your data sources. If you need to compose a brand new query, you can click the New Query button you see in Figure 1.28 to launch the Query Builder shown in Figure 1.29. The Query Builder gives you a visual environment in which to construct your query. You can open as many tables as you need in the Query Builder window and do joins on the tables by simply dragging the joining fields from one table to another. As you do, the corresponding SQL statement is constructed at the bottom of the Query Builder. When you’re done building the query and click the Close button, the Query Builder will give you the option to insert the SQL statement right into your template.
Figure 1.29 The ColdFusion Studio Query Builder is similar to the Microsoft Query Builder and can place the SQL statements you build directly into your template file.
38
Chapter 1: The ColdFusion Development Environment
What’s Next Now that you’ve toured the ColdFusion application development environment, you’re ready to begin writing ColdFusion templates. Templates are written in the ColdFusion Markup Language (CFML), a tag-based language with nearly 100 commands and several hundred built-in functions. As with any new computing language, though, you’ll start with the basics. The next chapter shows you how to set up ColdFusion variables with the CFML tag and also introduces you to the many variable scopes available in the ColdFusion environment.
2 Variables and Variable Scope One of the most basic yet useful features of the ColdFusion development language is the ability to store information in memory for later use. The memory areas that hold the information are called variables, and ColdFusion supports the creation of many kinds. ColdFusion also allows you to store many different kinds of data in variables, including text, numbers, dates, times, and Boolean (TRUE or FALSE) values. These different kinds of data are called data types. In this chapter, you will • Learn how to create your own variables • Learn how ColdFusion assigns data types and how you can check a variable’s data type • See how to retrieve a value stored in a variable and incorporate it into a Web page • Learn about ColdFusion variable scopes and how ColdFusion searches through the different scopes
42
Chapter 2: Variables and Variable Scope
Setting Up Variables Every variable must have both a name and a value. The value is the information you want to store for later use. The variable’s name identifies the memory area where the information is stored. Naming the variable is important because you use the variable’s name to retrieve the value stored there. You assign a name and value to a ColdFusion variable by using . The following is the basic form of a instruction:
ColdFusion has a few rules about how you choose your variable names: • Variable names have to start with a letter. • Variable names can be made up of letters, numbers, and the underscore (_) character. No other characters are allowed. These sample commands use valid variable names:
Note that each variable name is a compound word made up of two smaller words. A common technique (used in the preceding examples) to help with the readability of these names is to use an uppercase letter when starting a new word. Another approach is to use the underscore character between words:
Either choice is a valid way to go, and ultimately you must decide which approach makes the most sense for you. The important point to remember is to resist the urge to use spaces in variable names to separate the individual words. ColdFusion does not allow spaces in variable names. NOTE ColdFusion variable names are not case sensitive.
Variable Data Types When you first establish a variable in ColdFusion, it is typeless, meaning that no data type is assigned to it. ColdFusion determines a data type later
Variable Data Types
43
when you make use of the variable. It does so by considering the context in which you’re using the variable. Consider, for example, the following command:
The value 100 could represent a number of things: • The numerical value 100 • The character string “100” • A Boolean value of TRUE (any number other than zero can be used to represent TRUE) When you set up the variable, ColdFusion is not concerned with which of these possibilities matches your intent. It is only at some later point in the script that the data type becomes important. Suppose that farther down in your script you issue this command:
Because you’re doing a multiplication operation, ColdFusion can deduce that myVariable should have a numeric data type. ColdFusion converts the value stored in myVariable to that data type so that the multiplication can be performed. Suppose instead you have the following command:
In this case, the ampersand (&) implies that you are doing string concatenation. String concatenation refers to the joining together of two or more strings into a single string. Because each thing being concatenated must be a string, ColdFusion can deduce that myVariable should be of a string data type, and it converts the value stored in myVariable accordingly. Finally, suppose instead you use the following instruction:
The use of Not suggests that you’re logically negating the value of a Boolean variable (changing TRUE to FALSE or vice versa). In response, ColdFusion assigns a Boolean data type to myVariable so that the negation can be completed. NOTE Multiplication, concatenation, and Boolean negation are all examples of ColdFusion operations, and the characters that represent them—*, &, and Not, respectively—are referred to as operators. Operators generally suggest to ColdFusion which data type it should assign to a variable.
44
Chapter 2: Variables and Variable Scope
The multiplication operator is one of ColdFusion’s arithmetic operators. The others are addition (+ operator), subtraction (- operator), and division (/ operator).
You can check a variable’s data type by using . is most typically used to assign a variable’s default value, as in the following example:
✔ To learn more details about how to process check box and radio button fields, see “Example: Using Form Variables,” in Chapter 2.
This command essentially says, “If the variable called myVariable is not defined, then use a default value of 50 for it.” This command can be helpful in situations in which the variable may or may not exist. One such situation that occurs frequently in Web development is handling check box and radio button fields submitted through a Hypertext Markup Language (HTML) form. If a check box or radio button field is selected, its name and value are passed to the ColdFusion server for processing. If, however, it is not selected, no name and value are passed. In that case, if you look for the field’s name, you won’t find it in ColdFusion’s memory. Ordinarily, this would generate an error message, but can prevent the error by providing a default value for the field. also can be used to assess a variable’s data type. Consider the
following code:
This code would execute without error. The following code, however, would produce an error:
The double quotation marks around the value in the line suggest a string variable, but the data type of numeric in the instruction conflicts with that. Generating an error message may seem like a dire way to test for a variable’s data type, but it’s not as bad as it sounds because ColdFusion allows you to detect and respond to errors as they occur. When using to determine a data type, you can set the type attribute to many popular ColdFusion data types, including the following:
Outputting Variable Values
45
• Any • Array • Binary • Boolean • Date • Numeric • Query • String
Outputting Variable Values You can manipulate variable values with ColdFusion operators as much as you would like, but ultimately you’ll want to display one or more of the variable values in the Web page that you’re using ColdFusion to build. To accomplish this task, you use , which has a companion closing tag, . All tag pairs must be balanced for your script to be processed. TIP If you’re using ColdFusion Studio or HomeSite to do your ColdFusion development, you can activate the Tag Completion feature, which will automatically put in closing tags for you. Thus, if you type , the program will drop in the and your tags will remain balanced.
To place a variable’s value onto your Web page, you place the variable’s name between and . Additionally, you have to surround the variable’s name with the # character. It is the # characters that tell ColdFusion to substitute the variable’s value in place of the name. Recall the instructions you read earlier:
Example: Incorporating Variable Values into HTML with Listing 2.1 shows a complete ColdFusion script that uses these variables and their values.
46
Chapter 2: Variables and Variable Scope
Listing 2.1
Outputting Variable Values into HTML Code
Outputting Variable Values into HTML Code is a ColdFusion comment. Comments describe what you’re doing in the code and are not processed by the ColdFusion Application Server.
When processed by the ColdFusion Application Server, the preceding code will result in the following HTML being delivered to the requesting browser: Outputting Variable Values into HTML Code Welcome to ColdFusion!
Outputting Variable Values
47
The values “olive” and 5 are substituted into the tag, and the value “red” is substituted into the tag, thereby producing a page with an olive-colored background, a 5-pixel left margin, and a red level 1 heading.
Example: Using a Single Tag Listing 2.2 shows an alternative version of the code in Listing 2.1 in which only one tag is used. Listing 2.2
Another Approach to Outputting Variable Values into HTML Code
Outputting Variable Values into HTML Code Color choice error!
You choose the same foreground and background color! This would make the text on your pages unreadable. Please use your browser’s Back button and choose another color combination.
Basic If-Then Rules
71
Listing 3.2 continued Customized Color Page
Here is your custom color combination!
Note the use of the tag, which tells the ColdFusion Application Server to stop processing the script. Also, note that you can use
or
because both equals and is are valid ways to test for equality between Form.bgcolor and Form.fgcolor.
Example: Checking for the Existence of Form Fields In Chapter 2, “Variables and Variable Scope,” you learned how to use the tag to specify a default value for a variable that might not exist. This capability is particularly useful when you’re processing a form with check boxes or radio buttons because such form fields are not passed to the ColdFusion server if they aren’t selected. For this example, consider the HTML form in Listing 3.3, which asks users to indicate which age range they fall into. Listing 3.3
Age-Range Specification Form
Age Range
Please choose the age range your age falls within and click the “Continue” button.
72
Chapter 3: Implementing Conditional Logic
Listing 3.3 continued 65 or more years
Some people shy away from providing information about their age, so it’s certainly plausible that they might not select one of the radio buttons. In that case, Form.age will not be defined if you try to reference it in the processing script called ageprocessor.cfm. As an alternative to , you can use together with the IsDefined() function to see whether the form field is there. IsDefined() tests whether a variable exists and returns TRUE if the variable does exist and FALSE if it does not. Listing 3.4 shows you how to use this function. Listing 3.4
The ageprocessor.cfm Script
Age Information
Basic If-Then Rules
Listing 3.5 Color choice error!
You chose the same foreground and background color! This would make the text on your pages unreadable. Please use your browser’s Back button and choose another color combination.
Here is your custom color combination!
80
Chapter 3: Implementing Conditional Logic
Both scripts will produce the same output on the browser screen, but the version in Listing 3.9 is more efficient because it evaluates the condition only once.
Example: Making a Form Field Required Sometimes a user needs to fill out a form field but doesn’t for one reason or another. In this case, you can use to determine whether the field was completed and, in the event that it wasn’t, ask the user to return to the form page and fill out that field. Consider the mailing list sign-up form in Listing 3.10. Listing 3.10
A Form with a Required Field
An HTML Form with a Required Field
To sign up for our mailing list, please fill out the form below and click the “Submit” button. The E-Mail Address field is required.
E-Mail Address:
Mail Format:
Plain Text HTML
Expanding to an If-Then-Else Rule
Listing 3.10
81
continued
The mail format information is collected by means of a radio button. Even if the user doesn’t fill in that field, you can still provide a default value for it using . If the user doesn’t provide an e-mail address, however, there’s no default value you can assume that will work. You have to get that information from the user. You can use a instruction in the listsignup.cfm script to determine whether the user filled in the e-mail address field. If she didn’t fill it in, the browser will submit a blank value (also called the empty string or a string with no characters in it). Thus, your should examine the contents of the Form.email variable and see whether it is equal to the empty string. If so, you need to tell the user to go back and fill in her address. Listing 3.11 shows you how to do this. Listing 3.11
The listsignup.cfm Script
Mailing List Sign Up
82
Chapter 3: Implementing Conditional Logic
Listing 3.11 continued Error!
We need your e-mail address to be able to sign you up! Please use the Back button on your browser to return to the sign-up form and enter your e-mail address before submitting.
Sign-up Information
You are signing up for our mailing with the following information:
E-mail address: #Form.email#
Mail format: #Form.format#
By examining the condition Form.email eq “”, you are testing to see whether the user filled in the required field. Using this condition isn’t the only way to perform the test, though. Another approach involves the use of the ColdFusion Len() function. Len() tells you how many characters a string has, so if you pass Len() the value of Form.email, you can check whether it returns a value of zero as follows: Error!
We need your e-mail address to be able to sign you up! Please use the Back button on your browser to return to the sign-up form and enter your e-mail address before submitting.
Sign-up Information
You are signing up for our mailing with the following information:
Expanding to an If-Then-Else Rule
83
E-mail address: #Form.email#
Mail format: #Form.format#
The if-then-else logic in the preceding example is equivalent to what you saw in Listing 3.11. There is an advantage to using the Len() function versus testing the string to see whether it is equal to the empty string. The Len() function returns a numeric value that is either zero (if the string contains no characters) or some positive number (if the string has some characters). ColdFusion interprets a zero as a Boolean FALSE and any non-zero numbers as a Boolean TRUE. Because expects an expression that evaluates to either TRUE or FALSE, you can rewrite the preceding instruction as follows: Sign-up Information
You are signing up for our mailing with the following information:
E-mail address: #Form.email#
Mail format: #Form.format#
Error!
We need your e-mail address to be able to sign you up! Please use the Back button on your browser to return to the sign-up form and enter your e-mail address before submitting.
Note here that you have to reverse the two blocks of code to match the condition in the instruction. If the e-mail field was filled in, Len(Form.email) returns some positive number and is interpreted as TRUE. This compels you to take the code to process when the e-mail address is provided and move it between the and tags.
84
Chapter 3: Implementing Conditional Logic
✔ To learn how to add JavaScript to your HTML forms, see “Making Fields Required,” in Chapter 10.
You can use instructions to enforce the required fields on your forms, but the price you pay is an increased load on the server. It would be better if you knew that the form data submitted was complete so that you don’t have to use ColdFusion to check it. You can accomplish this by including JavaScript code in your code for the HTML form. When the user clicks the Submit button, JavaScript can inspect the required fields, flag any of them that aren’t filled out, and suppress the submission of the form data. This way, you know that if the form data was submitted, it has to be complete. Even if you don’t know JavaScript, ColdFusion can help you implement it in your forms. You’ll learn how to use JavaScript in Chapter 10, “Adding JavaScript to Your Forms.”
Example: Creating Grammatically Correct Output When you’re focused on building a dynamic, database-driven Web site, you can easily overlook good grammar in the HTML pages you generate. In particular, developers often miss using the plural forms of nouns and verbs in their output. Have you ever seen a sentence on a Web page like the following? 1 records found!
The word records doesn’t match the number 1. Sometimes developers try to gloss over this mistake with output like this: 1 record(s) found!
But you don’t need to do that with ColdFusion because you can use to determine which words are grammatically correct. Consider the pizza order form in Listing 3.12. Listing 3.12
Pizza Order Form
Pizza Order Form
Please choose the toppings you’d like on your pizza and click the “Continue Order” button.
Expanding to an If-Then-Else Rule
Listing 3.12 continued Onions
The form uses a series of check boxes to ask the user which toppings to put on the pizza. The processing script processtoppings.cfm needs to be prepared for two possibilities: • The user chose no toppings, in which case Form.toppings is undefined. • The user chose one or more toppings, in which case Form.toppings is passed to ColdFusion as a comma-delimited list of the toppings selected. In the second case, you also have to be sensitive to the possibility that the user chose only one topping. If so, you need to use the singular forms of nouns and verbs. The script in Listing 3.13 shows you one way to do so. Listing 3.13
The processtoppings.cfm Script
Pizza Topping Processor
Are you sure you want a plain pizza?
Adding More Conditions to Your If-Then-Else Rule
87
✔ To learn more details about ListLen() and other ColdFusion list functions, see “ColdFusion Lists” in Chapter 6.
The ListLen() function tells you how many items are in the commadelimited list stored in Form.toppings. If Form.toppings takes on the default value of the empty string, it is considered to be a list with zero items.
Adding More Conditions to Your If-Then-Else Rule Sometimes it’s not enough to have a separate code block to process when the Boolean condition in a instruction turns out to have a value of FALSE. In some instances, you might need to move on to test yet another condition rather than move directly to the “else” part of the statement. ColdFusion supports the tag to help you with this task. tags occur after the initial , but before the tag, if one exists. You are free to use as many tags as you like. As an example, consider the code that processes a form field named ssn that collects a Social Security number:
You must enter your Social Security number before submitting the form. Please use the Back button on your browser to go back and correct your submission.
Please enter your Social Security Number in the form xxx-xx-xxxx.
Your Social Security Number is #Form.ssn#.
The Boolean condition in the tag checks to see whether the ssn field was left blank. If it was, the user sees a message that submission of the Social Security number is required. If the field was not left blank, processing moves to the tag, which checks to make sure that the Social Security number is not made up of 11 characters (9 digits plus 2 dashes). If that condition has a value of TRUE, the user sees a message that indicates the expected format for the Social Security number. If the second condition is FALSE, processing passes to , where the user receives a confirmation of the Social Security number entered.
88
Chapter 3: Implementing Conditional Logic
In short, you use to test conditions beyond the initial one. The following examples illustrate situations in which you might need to test.
Example: Revisiting the Pizza Topping Selection Form Earlier, you saw how to process the pizza topping selection form using and to ensure grammatically correct sentences. Next, you’ll expand the form processing script to respond to certain topping choices. Examine the code shown in Listing 3.14. Listing 3.14
Expanded processtoppings.cfm Script
Pizza Topping Processor
Do you really want little salty fish on your pizza?
Green or black olives?
Shall we send you some breath mints, too?
91
92
Chapter 3: Implementing Conditional Logic
Listing 3.15 continued
Note here the use of the tag, which reads in content from a separate file and dynamically incorporates it into the current script. The separate file is specified by the template attribute. is ideal for helping to modularize your ColdFusion logic and your HTML content so that you can deploy it on every page but maintain it in only one place. TIP If one of the conditions you’re testing is more likely to turn out to have a value of TRUE than the other, put that condition in the tag. Then put your next most likely condition in the first tag, and so on. This coding technique improves performance because it prevents ColdFusion from having to work its way through the conditions that are less likely to be true. Because users can hit your site any day of the week, no day is probably more likely than any other, so the days are considered in the order they normally occur.
Considering Multiple Cases In the preceding example, you used several tags to test cases for five of the seven days in the week. For such situations, ColdFusion provides you with another tag——that you can use to test the same conditions, but in a more structured way.
Example: Revisiting the Day-Specific Content Listing 3.16 illustrates how to use the tag to implement the same logic as in Listing 3.15. Listing 3.16
Day-Specific Content Created with
Incorporating Day-Specific Content
What’s Next
95
Listing 3.17 continued
Note that the first two blocks handle multiple values. For example, the first redirects the user to the accounting home page if the chosen department is Accounting, Payables, or Receivables. You can consolidate multiple values into a single tag by separating the values with commas. Note also the tag, which redirects users to a new page as specified by the tag’s url attribute.
What’s Next This chapter showed you how to implement conditional processing in a ColdFusion script. You learned how to construct an “if-then” rule using . You next learned how to extend your commands to “if-thenelse” rules by adding a tag. You also saw how to test other conditions in a command by adding a tag. Finally, you learned how to use to consider an expression with many possible outcomes.
96
Chapter 3: Implementing Conditional Logic
ColdFusion was originally released as a tool to help Web developers communicate with back-end databases. Indeed, many of the tags you’ve been using so far such as , , and used to be written as , , and to reflect ColdFusion’s early focus on database connectivity. As ColdFusion matured into a more robust application development environment, the db was dropped in favor of cf. ColdFusion still enables developers to work with databases, and the next two chapters will show you how to compose and issue commands to databases from within your ColdFusion scripts.
4 Interacting with Databases: Retrieving Data One of ColdFusion’s core strengths is its ability to interact with databases. For ColdFusion to work with a database, the database must be set up as a data source through the ColdFusion Administrator. Data sources can be set up through ODBC, OLE (Object Linking and Embedding) DB, or through native drivers that are provided with ColdFusion. After the data source is established, you use the tag to compose and send your commands to the database. Database commands are written in the Structured Query Language (SQL). Different SQL commands are available for each of the different ways you might interact with the database. This chapter focuses on the use of the SQL SELECT statement, which you use to retrieve data stored in the database. You’ll learn more details about the other kinds of SQL statements in Chapter 5, “Interacting with Databases: Inserting, Updating, and Deleting.” In this chapter, you’ll learn how to • Compose SQL SELECT statements that retrieve the data you need • Use to issue SQL statements against a data source • Generate HTML output using data retrieved from a query • Build pages that allow users to search your databases
100
Chapter 4: Interacting with Databases: Retrieving Data
Retrieving Information from a Database ColdFusion can use data retrieved from a database to construct a Web page, send an e-mail message, or perform many other functions. To get the data out of the database, you use the CFML tag together with an SQL SELECT statement that specifies the data that you want to retrieve. The ColdFusion Application Server executes the tag and stores the database data returned to it in a special memory area called a query variable. The query variable is structured in a way that makes it easy for you to access and use the data inside it to create many types of output. The next few sections introduce you to each basic aspect of using ColdFusion to work with databases.
Composing SQL SELECT Statements The most basic SELECT statement indicates the table containing the data you want to retrieve and the names of the fields where the data is stored. For example, the following query would retrieve the data stored in the StudentLastName and StudentFirstName fields of a table named Students: SELECT StudentLastName, StudentFirstName FROM Students
Assuming the fields are named intuitively, the query retrieves the first and last names of all the students in the table. If you want to retrieve the values in all the fields in the table, you can use the asterisk (*) as a wildcard character as follows: SELECT * FROM Students
TIP Using the asterisk as a wildcard character can certainly save you a good bit of typing, but in the interest of good performance, you should specify only the values of fields you really need instead of using the asterisk all the time. Otherwise, you use up memory to store database data that you don’t intend to use.
The two queries you’ve seen so far retrieve information from every record in the database table. Often, though, you need to restrict your focus to a certain subset of records in the table. You can do so by adding a WHERE clause to your statement. For example, you can extend the first query you saw to the following: SELECT StudentLastName, StudentFirstName FROM Students WHERE StudentGradeLevel = 10
Retrieving Information from a Database
101
Now the query returns only the first and last names of those students who are in grade 10. You can extend the WHERE clause to express more complex conditions by using AND and OR. For example, to retrieve the names of all students in grades 10 or 11, you would issue the following query: SELECT StudentLastName, StudentFirstName FROM Students WHERE (StudentGradeLevel = 10) OR (StudentGradeLevel = 11)
The parentheses are not syntactically necessary, but they do enhance the readability of the statement. Here, the OR means that one condition or the other needs to hold true for the record to be selected. Thus, the query will select the name of any student in grade 10 or 11 from the database. To retrieve the names of students in grade 10 whose last name is also Smith, you would write SELECT StudentLastName, StudentFirstName FROM Students WHERE (StudentGradeLevel = 10) AND (StudentLastName = ‘Smith’)
In this case, the AND forces both conditions to hold true for a record to be selected. In the last query, note that the last name Smith must be enclosed in single quotation marks. This is true of database fields that contain character data: Any time you refer to a specific literal value of that field, the value has to be enclosed in single quotation marks. This is not true of other kinds of database fields, though, so if you’re searching for a specific value of a numeric, date/time, or Boolean field, you would not need single quotation marks around the value. NOTE Database fields that contain character data can be identified by many different labels, depending mostly on which database platform you’re using. Some of the more popular labels include Text, Memo, Char, and Varchar. If you see any of these labels listed as a field’s data type, you’ll need single quotation marks around any literal values of the field.
Even though you can choose from plenty of existing algorithms for sorting data, having your SQL command sort the retrieved data is always better than doing it yourself. You accomplish this by adding an ORDER BY clause to the end of your query as follows: SELECT StudentLastName, StudentFirstName FROM Students WHERE StudentGradeLevel = 9 ORDER BY StudentLastName
102
Chapter 4: Interacting with Databases: Retrieving Data
The data returned by the preceding query will be sorted in alphabetical order by the students’ last names. Because two students might have the same last name, you’ll then want to use their first names to determine who comes first in the ordering. You can specify the use of the first name for secondary ordering by adding the StudentFirstName field to the ORDER BY clause: SELECT StudentLastName, StudentFirstName FROM Students WHERE StudentGradeLevel = 9 ORDER BY StudentLastName, StudentFirstName
CAUTION You can’t include a field in the ORDER BY clause that has not been named in the SELECT part of the statement. For example, in the preceding query, you could not include StudentGradeLevel in the ORDER BY clause because only StudentLastName and StudentFirstName are being selected as part of this query.
The kind of sorting that occurs depends on the data type of the database fields you’re using to do the sorting. In the preceding examples, the ordering is alphabetical because StudentLastName and StudentFirstName are both text fields. If you sort on a numeric field, the ordering goes from smaller numbers to larger numbers. If you sort on a date/time field, the ordering goes from least recent to most recent. TIP To reverse any of the orderings, add the SQL keyword DESC to the end of your ORDER BY clause. Adding this keyword has the effect of changing from ascending order to descending order.
What you have seen so far is enough to help you through most of the SELECT statements you’ll need to write. However, you can use some additional SQL operators with a SELECT statement to enhance your ability to retrieve data from your databases. This section wraps up with coverage of some of these extras. IN
The SQL IN operator provides a list of values that you’re interested in finding in the database. Suppose, for example, you want to see all the first and last names of students in grade 10, 11, or 12. You could write your query as follows: SELECT StudentLastName, StudentFirstName FROM Students WHERE (StudentGradeLevel = 10) OR (StudentGradeLevel = 11) OR (StudentGradeLevel = 12) ORDER BY StudentLastName, StudentFirstName
Retrieving Information from a Database
103
The preceding query would work just fine, but the IN keyword gives you a more compact way to express the same thing: SELECT StudentLastName, StudentFirstName FROM Students WHERE StudentGradeLevel IN (10,11,12) ORDER BY StudentLastName, StudentFirstName
The list of values following IN must be enclosed in parentheses for the statement to be syntactically correct. Also, the values must be separated from each other by a comma. If you use a text field value in your WHERE clause, each value has to be enclosed in single quotation marks, as in this example: SELECT StudentLastName, StudentFirstName FROM Students WHERE StudentLastName IN (‘Smith’,’Jones’,’Brown’) ORDER BY StudentLastName, StudentFirstName
BETWEEN
The SQL BETWEEN operator is useful when you want to search over a range of values. Recall the query from the preceding section where you queried out students who were in grade 10, 11, or 12. Another way to accomplish the same thing would be to use the following: SELECT StudentLastName, StudentFirstName FROM Students WHERE StudentGradeLevel BETWEEN 10 AND 12 ORDER BY StudentLastName, StudentFirstName
The WHERE clause that uses BETWEEN will be inclusive of values that defined the range you’re searching over, so the preceding query picks up students in grades 10 and 12 as well. Using BETWEEN is essentially a shorthand way of writing SELECT StudentLastName, StudentFirstName FROM Students WHERE (StudentGradeLevel >= 10) AND (StudentGradeLevel = 3.0
With the basics of how to compose a SELECT query under your belt, you’re now ready to move on to the tag, which sends an SQL query on to the target database for processing.
Using has both opening and closing tags, and the SQL statement you want executed goes between the tags. also requires the datasource attribute, which you use to tell ColdFusion which data source you want the query executed against. A sample command might
look like this: SELECT ProductName, ProductPrice FROM Products WHERE ProductInStock = 1 ORDER BY ProductName
106
Chapter 4: Interacting with Databases: Retrieving Data
When you create a SELECT query like this, the data returned from the database will go into a query variable in ColdFusion’s memory. To facilitate your access to the data in the query variable, you should give the variable a name using the name attribute of the tag as follows: SELECT ProductName, ProductPrice FROM Products WHERE ProductInStock = 1 ORDER BY ProductName
After the preceding query executes, the data requested from the database will reside in a ColdFusion query variable named qGetProductData. TIP Making all your query names start with the letter q is good practice. This convention helps you to remember that the name refers to data returned from a query. ✔ To learn more details about the different types of data sources, see “Setting Up Data Sources,” in Chapter 1.
ColdFusion assumes you’re interacting with an ODBC data source. If you aren’t, you can use the dbtype attribute of the tag to indicate a different kind. For example, if the data source inventory in the preceding query were an OLE DB data source, you would write the command as follows: SELECT ProductName, ProductPrice FROM Products WHERE ProductInStock = 1 ORDER BY ProductName
has several other attributes that are useful in certain situations:
• maxrows—This attribute puts a limit on the number of records that the query can retrieve. This capability can be useful when a user is searching a very large database and you want to keep the amount of information coming back to him manageable. Very often, this attribute’s value is something you let users specify on the form they fill out to initiate the search. • username, password—Some data sources are password-protected to keep unauthorized users away from sensitive information. If you establish a password-protected data source, you need to give
Retrieving Information from a Database
107
ColdFusion username and password information so that it can connect to the data source and execute the desired query for you. • timeout—This attribute specifies the number of seconds the query has to run to completion. If the query does not finish within the allocated time, ColdFusion produces a timeout error. If you use the timeout attribute, the value you specify there will override any timeouts set through the ColdFusion Administrator. • cachedwithin—This attribute allows you to cache the results from a query in the server’s memory for a span of time that you specify. This capability can enhance the performance of your server by eliminating the need to keep establishing connections to your data source and repeat the same queries again and again. When query data is cached, the data can be retrieved much more quickly from the cache than it can be retrieved from the database. After a tag is processed, ColdFusion creates several variables and associates them with the name that you gave to the query. These variables include the following: • RecordCount—The number of records returned by the query • CurrentRow—The number of the record that ColdFusion is currently focused on • ExecutionTime—The amount of time in milliseconds that the query took to run • ColumnList—A comma-delimited list of the retrieved database fields. You very often use the RecordCount property immediately after the query to determine how to respond to the user, as shown in the following code excerpt: SELECT ProductName, ProductPrice FROM Products WHERE ProductInStock = 1 ORDER BY ProductName #qGetProductData.RecordCount# products found!
108
Chapter 4: Interacting with Databases: Retrieving Data
No products found!
The initial uses the value of qGetProductData.RecordCount to determine whether any records exist. If RecordCount is zero, this result is interpreted as a Boolean FALSE and the user is informed that no records were found. Otherwise, RecordCount is some number that is larger than zero, which is interpreted as a Boolean TRUE. In that case, you output the value of RecordCount to tell the user how many records you’ve found. By using combinations of the attributes discussed in this section together with your knowledge of how to compose SQL SELECT statements, you can write commands that retrieve exactly the data you want from any data source. After the data is returned to ColdFusion, you’ll then want to do something with it. The next section shows you how to use data in a query variable to create many different kinds of HTML output.
Outputting Query Results A tag can retrieve data from the database for you, but to get that data out of ColdFusion’s memory and onto a Web page, you have to use the tag you learned about in Chapter 2, “Variables and Variable Scope.” In this case, however, you can add a query attribute to the instruction to tell it to use data from your query to create the output. When you give a set of query results to work with, it will generate one piece of output for each record that was retrieved by the query. This means you can generate a lot of HTML output with a very small amount of CFML code. To illustrate the point, consider the following short example: SELECT ProductName, ProductPrice FROM Products WHERE ProductInStock = 1 ORDER BY ProductName #qGetProductData.RecordCount# products found!
The instruction outputs each product name and price on its own line in the resulting Web page. If 5 products are retrieved from the database, only 5 lines of output are created. If 500 products are retrieved, ColdFusion generates 500 lines of output. After output is generated for each retrieved record, the instruction is over, and ColdFusion moves on to whatever instruction comes next. Of course, you can generate much more interesting HTML output than just individual product names and prices on their own lines of the document. The next three examples show you how to construct an HTML list, table, and form drop-down list by using with a set of query results.
Example: Creating Bulleted or Numbered Lists Listing 4.1 shows a query that retrieves customer data from a database and how you can generate a bulleted list of customer names from the output. Sample output from the script is shown in Figure 4.1. Listing 4.1
Generating a Bulleted List of Customer Names
SELECT CustLastName,CustFirstName
110
Chapter 4: Interacting with Databases: Retrieving Data
Listing 4.1
continued
FROM Customers ORDER BY CustLastName,CustFirstName Generating a Bulleted List from Query Data Customer Listing
#CustLastName#, #CustFirstName#
#CustTitle#
#CustCompany#
#CustCity#, #CustState#
Figure 4.3 shows some sample output from the script. Note that the column headings are automatically bold and centered within their cells. This formatting is handled automatically by the
tag.
Example: Creating a Drop-Down List in a Form As a final example of output you can create using and query data, consider a drop-down list in an HTML form. Often these lists are static because the options in them are unchanging. A good example would be a field in which you indicate your state of residence. In the U.S., such a list would contain all 50 states plus the District of Columbia and would not be likely to change anytime soon. On other occasions, though, your drop-down lists must be dynamically generated. For example, you might offer the user a drop-down list of the customers in your database. The user picks a customer and then sees that customer’s entire record. Listing 4.3 illustrates how you can create this kind of form element.
114
Chapter 4: Interacting with Databases: Retrieving Data
Figure 4.3 ColdFusion enables you to easily build an HTML table that displays your query data. Listing 4.3
Generating an HTML Form Drop-Down List
SELECT CustLastName,CustFirstName FROM Customers ORDER BY CustLastName,CustFirstName
Outputting Query Results
Listing 4.3
115
continued
Generating an HTML Form Drop-Down List from Query Data Customer Listing <select name=”customer” size=”1”> #CustLastName#, #CustFirstName#
117
118
Chapter 4: Interacting with Databases: Retrieving Data
Performing User-Driven Queries All the SELECT queries you have seen so far are static queries; that is, you’re issuing the same SQL statement time after time. Static SELECT queries have their place, but it can be more interesting to create SELECT queries in which some part of the query is determined by the user by means of HTML form submission. The examples in this section show you how to build interfaces that enable users to query your database tables and see the records that are returned by those queries.
Example: Picking from Existing Records One way to let users search your database is to present them with a listing that summarizes the records you have and to allow them to choose a record to review in more detail. Listing 4.4 showed how to generate a drop-down list of customer names. When you pick a customer from this list and click the submit button, the processing script called showcustomerdetail.cfm retrieves the chosen customer’s record and shows you the contents. Listing 4.5 illustrates how to display the customer’s detail record, and Figure 4.5 shows the resulting detail page. Listing 4.5
Customer Detail Page
SELECT * FROM Customers WHERE CustID = #Form.customer# Customer Search
Please enter a customer last name in the field below and click the “Search Customers” button.
Customer Last Name:
Listing 4.8 shows how to incorporate the user’s input into a query and check the results to see how to respond to the user.
124
Chapter 4: Interacting with Databases: Retrieving Data
Figure 4.7 A simple HTML form is all you need to allow the search to specify something to search for. Listing 4.8
Searching for a User-Specified Name
SELECT CustID,CustFirstName,CustLastName FROM Customers WHERE CustLastName = ‘#Form.custlastname#’ ORDER BY CustLastName,CustFirstName
Performing User-Driven Queries
Listing 4.8
continued
Customer Search Results Add a New Customer Add a New Customer
Please enter the data about the new customer and click the “Add Customer” button below.
First Name:
Last Name:
Adding New Records to a Database
Listing 5.1
continued
Title:
Company:
Address:
City:
State:
Zip/Postal Code:
Telephone:
Fax:
135
136
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
Listing 5.1
continued
E-mail Address:
Figure 5.1 Sales support staff can enter information about a new customer into an HTML form for submission to ColdFusion. The data collected on the form in Figure 5.1 is destined for a table in your relational database. For the purposes of this chapter, suppose that your table is called Customers, and it comprises the following fields:
Adding New Records to a Database
137
• CustomerID • FirstName • LastName • Title • Company • Address1 • Address2 • City • State • ZipCode • Phone • Fax • Email • DateEntered • DateLastModified CustomerID is the primary key field and will be automatically incremented
as new customers are added. All the other fields are text fields except for DateEntered and DateLastModified, which are date/time fields. NOTE Devoting some thought to the data types of the fields in your relational database tables is important. For example, fields that contain ZIP Codes should be text fields, in spite of the great temptation to make them numeric. There are a number of reasons for this: • Nine-digit ZIP Codes require the use of a dash to format them, and the dash is interpreted as a subtraction sign if the field is numeric. Thus, the four-digit part of the ZIP Code would be subtracted from the five-digit part, leaving you with a result that is very likely wrong. • If you’re storing ZIP Codes as five-digit numbers, the leading zero in a code like 02134 would be dropped if your ZIP Code field is numeric. • Some countries use postal codes that have letters in them. You wouldn’t be able to store these values in a numeric field. The same thinking applies to the phone and fax number fields as well, because these values may be formatted with parentheses and dashes. Be sure to give some consideration to database field data types and choose types that are consistent with the data users will be entering and how they format it.
138
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
What remains to be done is to write the ColdFusion script that takes the form data and builds the new database record from it. As a preliminary step, you’ll next see how to write an SQL INSERT query so that you can construct the proper command inside your tag.
Writing SQL INSERT Statements An SQL INSERT statement for the Customers table discussed in the preceding section might look like the following: INSERT INTO Customers (FirstName, LastName, Title, Company, Address1, Address2, City, State, ZipCode, Phone, Fax, Email, DateEntered, DateLastModified) VALUES (‘Eric’, ‘Ladd’, ‘Web Geek’, ‘NetLink Resource Group’, ‘809 Franklin Street’, ‘Suite 100’, ‘Alexandria’, ‘VA’, ‘22314-4145’, ‘703-299-1580’, ‘703-243-9203’, ‘[email protected]’, {ts ‘2002-05-18 14:25:31’}, {ts ‘2002-05-18 14:25:31’})
Following the SQL keywords INSERT INTO, you name the table where you want to create the new record and then provide a comma-delimited list of the fields in the table for which you have values. Then you provide the values themselves in a comma-delimited list following the VALUES keyword. The following are some important points to understand about how this SQL statement was written: • The order of the values has to match the order of the fields, and both lists must be enclosed in parentheses. The order that you use to list the fields, however, does not have to match the order that fields were created in the database. • The CustomerID field does not show up in the INSERT statement because it is automatically populated by the database. • All values going into fields that have a text data type are enclosed in single quotation marks. • The format for the values going into the DateEntered and DateLastModified fields is called ODBC date/time format. Recall from Chapter 2, “Variables and Variable Scope,” that ODBC date/time format is ColdFusion’s native way of expressing the value of a date/time variable and that you have to use the DateFormat() and TimeFormat() functions to convert from the ODBC format to a format more readily understood by a human reader. • You don’t have to provide a value for every field in the new record. For example, suppose you developed a Web-based wizard that collects the new customer data over several steps. If the only data collected in step
Adding New Records to a Database
139
1 is first name, last name, title, and company, you could start the new record as follows: INSERT INTO Customers (FirstName, LastName, Title, Company) VALUES (‘Eric’, ‘Ladd’, ‘Web Geek’, ‘NetLink Resource Group’)
As you gather more data in later wizard steps, you would update the record created by the preceding statement until you have the entire record built out. The SQL INSERT statement has a fairly standard format. What varies from one instance of INSERT to another are the values being used to create the new record. The examples you saw in this section used actual data, but in the ColdFusion environment, you have to use submitted form data to create the record. The next two sections show you how to use this data.
Example: Inserting Data Submitted on a Form The form you saw in Listing 5.1 is submitted to a ColdFusion script called addnewcustomer.cfm. Listing 5.2 shows you one way to implement this script. Listing 5.2
Source Code for addnewcustomer.cfm
Adding New Records to a Database
Listing 5.3
141
continued
INSERT INTO Customers (FirstName, LastName, Title, Company, Address1, Address2, City, State, ZipCode, Phone, Fax, Email, DateEntered, DateLastModified) VALUES (‘#Form.FirstName#’, ‘#Form.LastName#’, ‘#Form.Title#’, ‘#Form.Company#’, ‘#Form.Addr1#’, ’#Form.Addr2#’, ‘#Form.City#’, ‘#Form.State#’, ‘#Form.ZipCode#’, ‘#Form.Phone#’, ‘#Form.Fax#’, ‘#Form.Email#’, #Now()#, #Now()#) New Customer Created! New Customer Created!
A new customer record has been created for #Form.FirstName# #Form.LastName#.
In Listing 5.3, the instructions check the length of Form.Addr2. If the length is one or more characters, the condition inside is interpreted as a Boolean TRUE, and the database field Address2 and its corresponding value are made part of the query. If Form.Addr2 has no characters in it, Address2 is not included in the query. In this case, the Address2 field will have a value of NULL. TIP This type of conditional inclusion of a database field and its value is useful when you’re dealing with Access databases. By default, Access databases do not accept zero-length strings (strings with no characters in them) as values for text fields. The code in Listing 5.3 is one way to work around the error message Access will send back if you try to make an empty string the value of a text field.
142
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
Example: Using Another way to insert the data from the new customer information form is to use the tag. makes adding a new record somewhat easier by composing the INSERT statement for you. To be able to use , however, you have to make sure that your form fields and database fields have the exact same names. In the previous example, an exact match does not occur between the form and database field names, so some of those names will have to change before you can use . Generally, changing the form field names is easier. Listing 5.4 shows you the modified data collection form that is set up to work with . Listing 5.4
New Customer Data Form with Modified Field Names
New Customer Created! New Customer Created!
Adding New Records to a Database
Listing 5.5
145
continued
A new customer record has been created for #Form.FirstName# #Form.LastName#.
Note how eliminates the need for an INSERT query. All you need to specify is the name of the data source and the table where the new record should be created. ColdFusion combines that information with the names of the form fields (which are also the names of the database fields) to build the INSERT statement for you. By default, will include the value of every form field submitted in the INSERT query that it builds. If you don’t want to include a form field and its value in a query, you can use the formfields attribute to specify a list of the fields you want inserted. Listing 5.6 shows how to filter the database field Address2 out of the query if the corresponding form field is left blank. Listing 5.6
Excluding a Database Field from a Query
New Customer Created! New Customer Created!
A new customer record has been created for #Form.FirstName# #Form.LastName#.
As simple as is to use, you must recognize its limitations. The principal limitation of is that it can handle only data submitted on an HTML form. This means you can’t include fields such as DateEntered and DateLastModified in the INSERT query that creates. You would have to place values into these fields by using an UPDATE statement after the record is initially created. By creating the INSERT query yourself, you can handle both the form data and the time stamp fields in a single query. Another limitation of is that you don’t have the opportunity to transform the submitted form data if necessary. In the new customer information form, the user is expected to type the two-letter abbreviation for the
Updating Existing Database Records
147
state where the customer resides. Suppose you want to transform what is typed to uppercase letters so that all state abbreviations are stored in a consistent way. If you write the INSERT query yourself, you could include the Ucase() function to transform what the user typed as follows: INSERT INTO Customers (FirstName, LastName, Title, Company, Address1, Address2, City, State, ZipCode, Phone, Fax, Email, DateEntered, DateLastModified) VALUES (‘#Form.FirstName#’, ‘#Form.LastName#’, ‘#Form.Title#’, ‘#Form.Company#’, ‘#Form.Address1#’, ’#Form.Address2#’, ‘#Form.City#’, ‘#Ucase(Form.State)#’, ‘#Form.ZipCode#’, ‘#Form.Phone#’, ‘#Form.Fax#’, ‘#Form.Email#’, #Now()#, #Now()#)
You can’t use the Ucase() function with the tag because the tag uses only the exact values that the user typed.
Updating Existing Database Records When you have records in a database, you’ll invariably need to make changes in them from time to time. Updating records in a Web-based database is a three-step process: 1. Allow the user to choose the record that needs to be modified. 2. Display the contents of the chosen record in an HTML form. By doing so, you let the user see what’s in the record and make any necessary changes. 3. Use an SQL UPDATE statement to commit the changes to the database. The next two sections show you how to implement this process by first reviewing how to write SQL UPDATE statements and then by showing you the scripts used to implement the three steps.
Writing SQL UPDATE Statements SQL UPDATE statements change inaccurate or out-of-date database information. For example, a customer may be promoted and, as a result, have a new title. To change that title in the database, you could use the following UPDATE query: UPDATE Customers SET Title = ‘Director of Marketing’ WHERE CustomerID = 1861
148
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
The WHERE clause in the UPDATE statement is crucial. It focuses the effects of the statement to the record or records where the changes need to be made. If you execute the preceding query without the WHERE clause, all customers in your database would have their titles changed to Director of Marketing. NOTE Occasionally, creating an UPDATE query without a WHERE clause is appropriate. Suppose, for example, you need to raise the prices of all your products by 5%. In that case, you could use the following query: UPDATE Products SET ProductPrice = ProductPrice * 1.05
The absence of the WHERE clause means that every product will have its price multiplied by 1.05.
You aren’t limited to changing the value of just one field in an UPDATE statement. You can set new values for as many fields as you like by separating each with a comma. For example, if a company moves to a new building and you need to change a customer’s mailing information, you could use the following UPDATE query: UPDATE Customers SET Address1 = ‘2020 K Street NW’, Address2 = ‘Suite 1100’, City = ‘Washington’, State = ‘DC’, ZipCode = ‘20005’ WHERE CustomerID = 3922
As with the first INSERT queries you saw, the UPDATE queries in this section have data hard-coded into them. When implementing an UPDATE query with ColdFusion, you will very likely be using data submitted from an HTML form as the new values for the fields that need to change. The next section shows you how to use this data.
Example: Allowing Users to Update Records To begin the update process, you need to allow a user to select the record that needs to be changed. You can draw from what you learned in Chapter 4 to help with this procedure. Listing 5.7 shows you how to generate a drop-down list of customers from which the user can choose the customer record in need of modification. Listing 5.7
Generating a List of Customers
SELECT * FROM Customers WHERE CustomerID = #Form.CustomerID#
Please make any necessary changes to the data below and click the “Update Customer” button.
First Name:
Last Name:
Title:
Company:
Address:
151
152
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
Listing 5.8
continued
City:
State:
Zip/Postal Code:
Telephone:
Fax:
E-mail Address:
Updating Existing Database Records
Listing 5.8
153
continued
Figure 5.3 Presenting a customer’s record in an HTML form enables the user to edit the data. When the query is complete, generating the edit form is a matter of outputting values from the query into the value attributes of the tags that comprise the form. The hidden field is necessary so that the customer’s primary key value can be passed along to the final step in which the UPDATE query is performed. You need the primary key value for the WHERE clause of the UPDATE statement so that only the selected customer’s record is changed. TIP You can reuse a lot of the HTML code that makes up the form used to collect information for a new record when preparing the edit form.
The last step in the edit process is to take the data submitted from the edit form and use it to update the customer’s record. Because the user may have changed every value in the form, you must include every database field in the UPDATE query. In the event that the user does not change a field’s value, you would simply be overwriting that field’s existing value
154
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
with a copy of itself. Listing 5.9 shows the script that accomplishes the update. Listing 5.9
Updating a Customer Record
Customer Record Updated! Customer Record Updated!
#Form.FirstName# #Form.LastName#’s record has been updated.
The price you pay for the convenience of the tag is a lack of flexibility in performing the update. In Listing 5.9, you were able to use within to dynamically choose a value for the Address2 database field. This isn’t possible when you’re working with ; the values that are written to the database are exactly those values that were submitted on the form. Another drawback of using is that you can’t
156
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
update the value of the DateLastModified field like you could when using . The moral of the story is the same for both and : They both make your life easier under certain conditions but, in the long run, you’ll have more flexibility and control if you learn to write your own INSERT and UPDATE queries and execute them with .
Deleting Records from a Database Deleting a record from a database table is, like inserting, a two-step process: 1. Allow the user to choose the record that needs to be deleted. 2. Use an SQL DELETE statement to eliminate the record. Good interface design suggests that you confirm the delete operation with the user before actually doing it. Some developers implement this operation with a completely separate ColdFusion script, but the following sections will show you how to accomplish the same thing using JavaScript in the form that lets the user choose the record to be deleted.
Writing SQL DELETE Statements The SQL DELETE statement is easy to write, but it has a very final effect on a database record: It completely purges the record from the database. The only way to add the record back into the database after a DELETE is to rekey it or restore it from a backup copy of the database. NOTE After the value of a primary key field is deleted from the database table, it will never be reused. This is in the interest of preserving data integrity within the relational database.
You write a typical DELETE statement as follows: DELETE FROM Customers WHERE CustomerID = 5297
The WHERE clause is as important here as it was for the UPDATE statement because it focuses the effect of the DELETE query to only the record or records that need to be deleted. Without the WHERE clause, you would be saying that you want to delete all the records in the table! When using a DELETE query like the preceding one in managing a Webbased database, you’ll want to dynamically drop in the value of the Customer ID based on a choice made by the user. The next section shows you how to do so.
Deleting Records from a Database
157
Example: Allowing Users to Delete Records The first step in the delete process involves letting the user select which record he or she wants to delete. This step is similar to the first step in the edit process, although in this case you also want to include something that confirms the user’s request to initiate a delete operation. Listing 5.11 illustrates how to do both in the same script. Listing 5.11
Generating a Drop-Down List with Confirmation JavaScript
SELECT FirstName, LastName FROM Customers WHERE CustomerID = #Form.CustomerID# DELETE FROM Customers WHERE CustomerID = #Form.CustomerID# Customer Record Deleted Customer Record Deleted!
#FirstName# #LastName#’s record has been removed from the database.
160
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
Listing 5.12
continued
The script in Listing 5.12 shows the customer’s name in the HTML page that it returns to the user after the delete operation is complete. Including the name isn’t necessary, but if you want to do that, be sure to query the name out of the database before you perform the DELETE query. If you perform the DELETE query first, the record will be purged and no name will be left to go in and retrieve!
Example: Implementing Logical Deletes The kind of delete you saw in the previous section is what some developers call a hard delete. A hard delete removes a record from a database permanently. This type of delete is appropriate in some situations, but not in others. For example, if an employee leaves your company tomorrow, your employer would not hard delete that employee from its database because it still owes the employee a W-2 form at the start of the next tax year. Hard deleting the employee would eliminate all of that employee’s data, making it impossible to generate the W-2 in January. So, your employer needs to keep the employee’s data on hand, but it doesn’t want the employee showing up in the bi-monthly payroll, company directories, and any other information system that draws from the company’s employee database. One solution to this dilemma is to use what is called a logical or soft delete. A logical delete uses a Boolean field in the database that is set to TRUE when the record is to be considered active in the database and set to FALSE when the record is considered to be deleted from the database. Using this type of delete is almost like having an on-off switch for each record. By turning on the switch, you activate the record, and it can be recognized by queries in your application. When you turn off the switch, the record is not recognized by the application, but the data is still stored in the record, and you can access that data whenever you need to by simply turning the switch to on again. Implementing a logical delete involves more than just adding a Boolean field to your database table, though. You also have to adjust many, if not all, of your SQL queries so that they use the Boolean field. Suppose you add a Boolean field called Active to your Customers table. Going back through the listings you’ve seen in this chapter, you’ll have to change each to work with the new field as shown here. In Listing 5.2, you’ll have to include the Active field as follows:
You would need to make a similar change in Listing 5.3. In both listings, adding the Active field to the INSERT query sets the on-off switch to on so that the record is immediately considered to be active. If you’re using to add the new customer record, you’ll need to add a hidden field called Active to the new customer information form:
You need to add this field because the tag uses form field names and values to construct the INSERT query and the Active field won’t be set unless you have a form field that provides a value for it. Moving on to the edit process, you would have to make the following change to the SELECT query in Listing 5.7: SELECT CustomerID, FirstName, LastName FROM Customers WHERE Active = 1 ORDER BY LastName, FirstName
The addition of the WHERE clause ensures that you’re presenting only undeleted customers in the drop-down list. The rest of the queries in the edit process would not need to change because they affect only records that can be chosen from the list of undeleted customers. In the delete process, you would have to make the same change in Listing 5.11 that you made in Listing 5.7. The biggest change comes in Listing 5.12. To perform a logical delete of a customer, you use an SQL UPDATE query to change the value of the customer’s Active field from TRUE to FALSE as follows: UPDATE Customers SET Active = 0 WHERE CustomerID = #Form.CustomerID#
162
Chapter 5: Interacting with Databases: Inserting, Updating, and Deleting
Adding this query has the effect of turning the record’s on-off switch to off and effectively hides the record from the rest of the application. NOTE This section showed you the changes you would have to make for the insert, edit, and delete processes to support logically deleted records. In addition to these changes, you would also have to check the queries in other scripts in your application to make sure they are filtering out records whose Active field has been set to FALSE.
What’s Next In this chapter, you moved beyond the SQL SELECT query and saw how you could implement INSERT, UPDATE, and DELETE queries using the tag. You learned that inserting records is a two-step process: gathering information for the new record through an HTML form and then creating a new record from this data by creating an INSERT query with either or . You saw that editing existing records is a threestep process: allowing the user to choose a record to edit; presenting the information in the selected record through an HTML form; and then performing an UPDATE query, using either or , to commit the changes to the database. You learned that deleting a record is a twostep process: allowing the user to choose a record to delete and then performing a DELETE query using the tag to eliminate the record. Finally, you saw how to implement logical deletes in your application and how you would have to change your queries in the insert, edit, and delete processes to work with logically deleted records. In your experience with ColdFusion so far, you have been using variables that are fairly simple in nature. You have used variables that you created yourself through the tag; Form and URL variables, whose values are determined by form and query string data, respectively; and query variables, which contain data retrieved from a relational database. All these variable types are important in ColdFusion work, but you can use other, more complex variable types as well. These types include lists, arrays, and structures, and all three will be discussed in the next chapter.
6 Using ColdFusion Lists, Arrays, and Structures The variables you learned about in Chapter 2, “Variables and Variable Scope,” are sometimes referred to as scalar variables because each variable can store one and only one value. Scalar variables are fine for many programming purposes, but eventually you’ll be confronted with a situation in which it is more programmatically efficient to store multiple values in the same variable. ColdFusion supports storage of multiple values by means of lists, arrays, and structures. Each is a type of memory construct that enables you to store and retrieve more than one value, but the internal workings of each can vary greatly. Fortunately, each also has its own supporting class of CFML functions to help you create and manipulate them. In this chapter, you’ll learn how to • Create ColdFusion lists and handle them with CFML list functions • Build ColdFusion arrays and manage the data inside them • Work with ColdFusion structures, including those that are intrinsic to the ColdFusion environment
166
Chapter 6: Using ColdFusion Lists, Arrays, and Structures
Using ColdFusion Lists Lists are commonly used in written and spoken language to convey a number of pieces of information. For example, you might hear someone say, “My favorite colors are green, blue, and orange.” In that sentence, a list of three items is separated by commas. ColdFusion lists are similar. For example, consider the list colors set up by the following CFML code:
The items in the ColdFusion list are also separated by commas. In this case, the comma is called a delimiter, and the list is said to be a delimited list. The comma is the default delimiter for ColdFusion lists, but you can set up a list with any delimiter of your choosing. For example, the following command sets up a semicolon-delimited list:
NOTE Spaces are not required between items in a ColdFusion list like they are for a written list. If you include spaces, ColdFusion will treat them as being a necessary part of the item. For example, in the list
the second item in the list would be “ blue”, not “blue”, because of the space after the first comma.
You may have noticed in the previous commands that the items in the list are enclosed in quotation marks, suggesting that lists are strings. This is a correct observation: ColdFusion lists are merely strings that have a delimited structure that ColdFusion can recognize and use to your advantage. When you use any of the CFML list functions you’re about to learn, you are really doing string manipulation on the list. ColdFusion lists are useful because comma-delimited lists frequently crop up in the course of dynamic Web development. You have already seen such an example in Chapter 3, “Implementing Conditional Logic,” where you processed a user’s choice of pizza toppings. Recall that the HTML used to create the check boxes for the toppings was as follows:
Please choose the toppings you’d like on your pizza and click the “Continue Order” button.
Extra Cheese Pepperoni
Using ColdFusion Lists
In this case, all the check box fields have the same name, so the value of the variable Form.toppings will be a comma-delimited list. Another place where comma-delimited lists come up is in SQL statements. Recall from Chapter 4, “Interacting with Databases: Retrieving Data,” the SQL IN operator, which enables you to select, update, or delete records that match any value provided in a list of target values: SELECT * FROM publications WHERE publicationID IN (235,298,379,482) ORDER BY publicationTitle
Yet another example of lists showing up in the ColdFusion environment is when ColdFusion itself builds a list. Consider the following short HTML form:
First Name:
Last Name:
E-mail Address:
168
Chapter 6: Using ColdFusion Lists, Arrays, and Structures
When this form is submitted and the script namesubmit.cfm is invoked, ColdFusion will build a variable called Form.fieldnames containing a comma-delimited list of the names of the fields in the submitted form. For the preceding form, Form.fieldnames would have the value FNAME,LNAME,EMAIL. NOTE When ColdFusion builds the list of field names, it converts all the names to uppercase letters.
Now that you have some appreciation for how common lists are in the ColdFusion environment, you’re ready to see how you can do more with lists than just set them up. The next several sections contain short examples that illustrate the utility of lists and show how to use many of the built-in CFML list functions to work with them.
Example: Any String Is a List As noted earlier, a list is a string with a delimited structure. In fact, you can treat any string as a list even if it does not appear to have any delimiters in it. This includes even the simplest of strings. For example:
The variable list1 is equal to a string with no characters, or what is more commonly called the empty string. You can also refer to it as the empty list because it represents a list with no items in it. You can confirm this by using the ListLen() function as follows: Number of items in list1: #ListLen(list1)#
ListLen() returns a value of zero when it processes an empty list, so the output from the preceding code would be Number of items in list1: 0.
NOTE All CFML list functions start with the word List, and each needs to have a list passed to it as an argument when it is invoked. The CFML list functions also take an optional argument in which you can specify the delimiter character in use. If you don’t specify a delimiter character, ColdFusion assumes you’re using a comma. If you do specify a delimiter, it should be the last argument passed to the function.
Using ColdFusion Lists
169
The variable list2 is a simple one-word string, but it can also be interpreted as a one-item list. Thus, the output from the following line of code would be Number of items in list2: 1: Number of items in list2: #ListLen(list2)#
Example: Any Character Can Be a Delimiter Programmers customarily think of commas, semicolons, and pipe characters (|) as delimiters, but if you expand your thinking beyond those characters, you can get a lot more mileage from CFML list functions. Suppose you have published a form with a large text field to gather comments from a user as follows: Please enter your comments below, limiting your response to 100 words.
In the script that processes the submitted comments, you need to check Form.comments to make sure that it does not exceed 100 words. This may seem like a very involved challenge that would use a lot of string functions, but if you think of a paragraph as being a list of words delimited by the space character, enforcing the 100-word limit becomes easy: Your comments have exceeded the 100 word limit by #excessWords# words. Please shorten your response and resubmit.
Note in the preceding code that you must specify that the space character is the delimiter when using the ListLen() function. Otherwise, ColdFusion will assume that the comma is the delimiter, and your word count will not be accurate.
Example: Searching a List If you didn’t make up a list yourself, you may need to search through it to see whether an item is there. For example, you might search through the list Form.fieldnames when a form is submitted to look for a key form field
170
Chapter 6: Using ColdFusion Lists, Arrays, and Structures
name that tells you what action to take when the form is submitted. To do so, you would use the ColdFusion ListFind() function as follows: UPDATE publications SET pubTitle=’#Form.title#’, pubAuthor=’#Form.author#’ WHERE publicationID = #Form.pubID#
Looping Over a List
Listing 7.1
continued
Are you sure you just want a plain pizza?
Here’s a list of the toppings you ordered:
#topping#
197
198
Chapter 7: Implementing ColdFusion Loops
Listing 7.1
continued
The tag’s list attribute is set equal to the list stored in the variable Form.toppings. The index variable topping takes on the different values of the selected toppings as ColdFusion works its way through the list. For example, if Form.toppings had the value Extra Cheese,Pepperoni,Mushrooms
topping would first be equal to Extra Cheese, then equal to Pepperoni, and finally equal to Mushrooms. You use the tag to print out each top-
ping in turn as the list items in the bulleted list. The resulting bulleted list is shown in Figure 7.1.
Figure 7.1 When you use with a list, ColdFusion processes the loop code once for each item in the list. NOTE Having the # signs around Form.toppings in the tag’s list attribute is important because they force ColdFusion to substitute in the value of Form.toppings as the value of the attribute. Otherwise, ColdFusion would literally use the string “Form.toppings” as the list, and that would lead to some unintended consequences in the output!
Looping Over a List
199
Here’s an example of another situation in ColdFusion development in which the # signs are definitely needed. If you’re referring to a ColdFusion variable when setting a CFML tag’s attribute, you must use # signs around the variable to make ColdFusion use the value of the variable (rather than the name of the variable) as the value of the attribute.
Example: Creating a Generic Form Processor A popular type of CGI script is one that can process the data submitted on any HTML form. Regardless of how many fields are in the form, the script can handle each of those fields and incorporate them into some kind of output—very often composing an e-mail with the form field names and their associated values in the body of the message. You can download Perl scripts that do this from many different online libraries of publicly available code. One notable site is Matt’s Script Archive at http://www.worldwidemart.com/ scripts/. To accomplish the same thing in ColdFusion, you can take advantage of the fact that each time a form is submitted, ColdFusion builds a commadelimited list of all the form’s field names. ColdFusion calls this variable fieldnames, and it is available to you under the Form variable scope. You can see how ColdFusion creates this list when you have debugging features turned on. Figure 7.2 shows the Scope Variables section of the ColdFusion debugging output. Note that the list called fieldnames is created under the set of form variables. Listing 7.2 shows how to loop over this list to print out all the field names and their associated values. Listing 7.2
A Generic Form Processor
A Generic Form Processor SELECT StudentLastName, StudentFirstName FROM Students ORDER BY StudentLastName, StudentFirstName Putting Query Data into An Array Student array created!
Looping Over a Set of Query Results
Listing 7.3
205
continued
The CurrentRow variable used in Listing 7.3 is a helper variable that assists ColdFusion in counting through the rows of data returned by the query. As you can see from the example, you are welcome to use CurrentRow for your own purposes as well.
Example: Writing Query Data to a Text File Occasionally, you may need to export data from your database to a text file so that others can use it. The ColdFusion tag allows you to append data to a text file. Using inside a that loops over a query, you can write the query data into the text file as ColdFusion processes the records. Listing 7.4 shows how you can do this. Listing 7.4
Outputting Query Data to a Text File
Parsing a String New User Username and Password New User Created!
The username #Form.username# has been added to the database with an initial password of #pw#.
You should note several points about Listing 7.7: • You set the variable pw to be the empty string initially so that ColdFusion has something to work with as it begins to build the password. Setting this variable as empty is analogous to setting a counter variable equal to an initial value of zero. • The seed value used for the Randomize() function is taken from the system clock. The Now() function grabs the current date and time on the server, and that information is immediately fed into the Second() function, which plucks off the number of seconds in the time. Thus,
Implementing a For-Next Loop
213
the seed value is always a number between 0 and 59. This helps mix things up better than if you always use the same seed value each time the script runs. • The Randomize() function returns a value of YES when it is successful in seeding the random number generator. That value is stored in the variable called temp. • The generation of the random number, the conversion to a random character, and the concatenation of that character to the developing password are all broken into individual commands inside the loop. With time and experience, you’ll be able to write those steps as a single as follows:
Remember that when you have nested functions, you should work from the inside out. In the preceding code line, RandRange(97,122) is evaluated first, and the result it produces is immediately fed into the Chr() function. The resulting character is then concatenated to the string where the password is being constructed. • You don’t explicitly use the index variable count inside . There’s no problem with doing so; just don’t forget that ColdFusion needs the index variable even if you don’t. • In the query, the database fields are called Uname and Pword because username and password are reserved words in standard SQL. Figure 7.5 shows some sample output from the random password generation script.
Example: Putting Data into an Array Earlier in the chapter, you saw how to use a loop to put data retrieved from a database into an array. You also can use loops to put other kinds of data into arrays. Listing 7.8 shows a simple example. Listing 7.8
Creating an Array of Month Names
SELECT StudentLastName, StudentFirstName FROM Students ORDER BY StudentLastName, StudentFirstName Outputting Data from an Array
Here are the students in the array:
#students[i]#
Implementing a While Loop
Listing 7.9
217
continued
Here, you use the ArrayLen() function to determine how many elements are in the array and then loop from 1 up to the number of elements. The instruction inside the loop prints out each student name as a bulleted list item.
Implementing a While Loop ✔ To review examples of how to set up Boolean conditions, see “Basic If-Then Rules,” Chapter 3.
While loops are controlled by an associated Boolean condition. As long as the condition has a value of TRUE, the loop continues to run. When the condition takes on a value of FALSE, the loop will terminate. The Boolean conditions must be expressed in the same way you expressed them when you set up instructions in Chapter 3. The following examples show how to implement a ColdFusion while loop.
Example: Creating a Simple Counting Loop You can use while loops to create a counting loop similar to the for-next loop you learned about earlier in the chapter. Listing 7.10 shows an example of such a loop. Listing 7.10
A Counting Loop Processed as a While Loop
The critical part of this example is the following command:
This command ensures that x, which has a starting value of 1, will eventually become greater than 10. At that point, the Boolean condition “x le 10” will become false, and the loop will terminate. Without this command, the value of x will stay at 1, and the loop will run forever. This situation is called an infinite loop, and it can cause performance problems on your server by drawing system resources away from ColdFusion and other services. This is one potential pitfall of while loops: You have to guard against infinite loops by making sure that the associated Boolean condition eventually takes on a value of FALSE. TIP You also should make sure you have a reasonable script timeout set up in the ColdFusion Administrator. This way, you will limit a script with an infinite loop to running for only as many seconds as specified in the timeout setting.
Implementing a While Loop
219
Example: Revisiting the Random Password Generator Earlier in the chapter, you saw how to create random passwords for new system users. One limitation of that script is that the new password could be constructed using only lowercase letters a through z. Suppose you also want to use the capital letters and the digits 0 through 9. In that case, you first must identify the ASCII value ranges for all these character sets. They are as follows: • Digits—The digits 0 through 9 correspond to ASCII values 48 through 57, inclusive. • Uppercase letters—The uppercase letters A through Z correspond to ASCII values between 65 and 90, inclusive. • Lowercase letters—The lowercase letters a through z correspond to ASCII values between 97 and 122, inclusive. So, considering all the values between 48 and 122, the following are undesirable: 58, 59, 60, 61, 62, 63, 64, 91, 92, 93, 94, 95, and 96. Knowing this, you can modify the random password generator script to filter out these values. Listing 7.11 shows how to accomplish this task. Listing 7.11
Expanded Random Password Generator
220
Chapter 7: Implementing ColdFusion Loops
Listing 7.11
continued
New User Username and Password New User Created!
The username #Form.username# has been added to the database with an initial password of #pw#.
The second checks whether the chosen random number is in the bad list by using the ListFind() function.If the number is in the bad list, ColdFusion picks a different random number and tests the new number. This process continues until ColdFusion generates a random number that is not in the bad list. Figure 7.7 demonstrates that the modified script can now produce passwords with uppercase letters, lowercase letters, and digits. NOTE When you put one loop inside another, as in Listing 7.11, you create what’s called a nested loop.
222
Chapter 7: Implementing ColdFusion Loops
Figure 7.7 Using nested loops enables you to improve upon the initial random password script by using a broader set of characters in the password.Looping Over a Collection
Looping Over a Collection Collections are sets of key-value pairings. Any ColdFusion structure is an example of a collection. Additionally, many of ColdFusion’s variable scopes can be treated as collections. They include application, session, form, URL, CGI, and cookie variables. Looping over a collection refers to systematically working through all the keys in the collection and performing some action for each key-value pair. The following examples illustrate how you can use ColdFusion’s capability to loop over a collection to your advantage.
Example: Printing the Contents of a Collection ✔ To learn how to use ColdFusion’s session management features, see “Using ColdFusion Session Variables,” Chapter 11.
Looping over a collection is helpful during application debugging when you need to see the complete contents of a collection printed to the browser screen. For example, you might develop a shopping cart feature using ColdFusion session variables and, after some testing, want to inspect the contents of the cart to make sure it is working properly. In that case, you
Looping Over a Collection
could output the contents of the session variables collection by using the code in Listing 7.12. Listing 7.12
Outputting the Contents of the Session Variables Collection
A Generic Form Processor
Here are the form field names and values:
Field Name
Value
What’s Next
Listing 7.13
225
continued
#fieldname#
#Evaluate(collectionName & “.” & fieldname)#
The script uses the CGI variable REQUEST_METHOD to determine whether the get or post method was used and sets a variable called collectionName equal to URL or Form as appropriate. Then the script loops over the designated collection using the keys (which correspond to the field names) to retrieve the associated values.
What’s Next This chapter introduced ColdFusion looping and the tag. You learned how to iterate over the items in a ColdFusion list and over the records returned by a query. You then read how to implement for-next and while loops. Finally, you learned about ColdFusion collections and how to loop over the contents of a collection. Many dynamic Web sites use e-mail in some way. Electronic commerce sites send e-mails to customers to confirm their orders and follow up on the status of orders. Other sites let you sign up to receive an e-mail message notifying you of changes to content on the site. Regardless of your reason for using e-mail, ColdFusion makes it simple to build mail messages and distribute them to the intended recipients. What’s more, ColdFusion enables you to build your messages dynamically, meaning you can incorporate content from databases, form submissions, and other external sources. The next chapter introduces you to the tag and how you can use it to send messages from your ColdFusion-based Web site.
226
Chapter 7: Implementing ColdFusion Loops
8 Sending E-mail with ColdFusion If you’ve ever ordered something online, you very likely received an e-mail message shortly thereafter thanking you for your order and confirming the items in the order. You also may have received a follow-up message telling you when your order was shipped. Web sites commonly use e-mail to communicate with their users to let them know about new content, improved features, enhanced product offerings, or anything else that might bring the users back to the site for another visit. You also may be a member of a mailing list or listserv in which you send messages to a particular e-mail address and your message is, in turn, forwarded to all members of the list. This process could be performed manually, but that would require someone watching the incoming mail 24 hours a day and forwarding each message that comes in. Instead, it would be much more efficient to have a computer check the mailbox periodically and automatically forward to the list membership any messages that are there. ColdFusion can help you with both of these tasks. The tag sends outbound e-mail messages via a Simple Mail Transfer Protocol (SMTP) server. All aspects of the message, including sender, recipient, subject, and body, can be determined dynamically based on information available to ColdFusion from databases or other sources. The CFML tag retrieves e-mail messages from a mailbox on a Post Office Protocol (POP3) server. The retrieved messages are stored in a memory construct similar to query results, making it simple to loop through the messages and perform any necessary processing. In this chapter, you’ll learn how to • Send e-mail messages containing data submitted through an HTML form • Generate multiple messages by using query results in your commands • Send mail in HTML format
228
Chapter 8: Sending E-mail with ColdFusion
• Attach files to your e-mail messages • Download and process messages from a POP3 mailbox NOTE ColdFusion can send and receive e-mail messages, but it does not come bundled with an SMTP or a POP3 server. You need to have access to an SMTP server if you want to use to send e-mail. Similarly, you need to arrange for an e-mail account on a POP3 server if you want to use to retrieve mail messages. You can consult your mail administrator or your Internet service provider for more information.
Sending Messages with the Tag The tag is easy to use and allows surprising flexibility in how you compose your outgoing e-mail messages. has both an opening and a closing tag. The body of the message goes between the tags, and the attributes of the opening tag control, for example, who receives the message, who the message is from, and the subject of the message. For to send messages successfully, you need to specify an SMTP server for it to work with either in the tag itself or through the ColdFusion Administrator. If you have access to the Administrator, try logging in and selecting the link in the left frame labeled Mail Server. When you do, you see a screen like the one in Figure 8.1. You can specify the domain name service (DNS) name or IP address of the SMTP server you want ColdFusion to work with on this page. Additionally, you can test ColdFusion’s capability to connect to the nominated server by checking the box labeled Verify Mail Server Connection and then clicking the Submit Changes button. The Server Port is set to a default value of 25. SMTP traffic is usually sent via port 25, so you rarely will have to change this value. The Spool Interval refers to how often ColdFusion checks to see whether there are any messages to be sent out. When you generate an e-mail message with ColdFusion, it places the message into a mail spool. Messages accumulate in the mail spool, and a low-level ColdFusion thread periodically checks the mail spool to see whether anything is there. If so, the thread sends the messages on their way to the SMTP server. By default, ColdFusion checks the mail spool every 60 seconds, but you can set that value higher or lower as your volume of outgoing e-mail demands. Note that you can’t set the value to anything lower than 15 seconds.
Sending Messages with the Tag
229
Figure 8.1 Setting up an SMTP server in the ColdFusion Administrator saves you from having to specify the server each time you send out a message. The Connection Timeout value determines how long ColdFusion will try to establish contact with the SMTP server you direct it to work with. Normally, ColdFusion can connect to the mail server very quickly, and the timeout period is not an issue. If your mail server is somewhat unreliable, however, setting that value lower than its default of 60 seconds may make sense so that ColdFusion doesn’t waste a lot of timing waiting for a mail server that won’t answer. NOTE You have to restart ColdFusion to make the changes you made in the Mail Server Connection settings take effect.
Near the bottom of the screen are the Mail Logging settings. Here, you can specify what level of mail server errors you want to record in the ColdFusion log files, and you can even choose to log every e-mail message that ColdFusion generates. Logging all these messages can be useful for audit trail purposes, but it also can use up a lot of disk space, so make sure you empty out the log file periodically if you’re logging all e-mail messages. When you have your ColdFusion server set up to work with an SMTP server, you’re ready to begin generating e-mail messages. The examples in the next several sections show you how to generate them.
230
Chapter 8: Sending E-mail with ColdFusion
Example: Sending Data from a Form Probably the simplest example to consider is how to e-mail information passed to the ColdFusion server by means of an HTML form. Such forms occur frequently on Web sites and are used for gathering feedback or letting the site visitor express an interest in obtaining more information. Figure 8.2 shows a sample form that you might see on a company’s Web site. The corresponding HTML code is shown in Listing 8.1. Listing 8.1
Request for Information Form
#DateFormat(Now(),”mm/dd/yy”)# Please send company information to the following individual: #Form.fname# #Form.lname# #Form.address# #Form.city#, #Form.state# #Form.zip# #Form.country#
Sending Messages with the Tag
Listing 8.2
233
continued
Request Submitted Thank you, #Form.fname#!
Your request for more information has been received. We will send the information to you within 3 business days.
The tag in Listing 8.2 uses three required attributes—to, from, and subject—plus the optional cc attribute. Note that the values of the from and subject attributes use the submitted form data. The body of the message appears between and where, again, form data builds out the message text. You can even drop in dynamic values from other sources in the ColdFusion environment as shown by the use of the Now() and DateFormat() functions in the message body. TIP If you have multiple to and cc recipients, you can set those attributes equal to a comma-delimited list of primary and carbon-copy recipients instead of just a single e-mail address.
Example: Sending HTML-Formatted E-mail The tag generates messages that are in plain text format. You can produce messages in HTML format instead by including type=”HTML” in the tag. This way, you can use HTML tags to format the body of the message and, provided the recipient has a mail reader that can render HTML-based e-mail, the user will see the effects those tags produce when he or she reads the message. CAUTION Some people do not have a mail reader that can correctly render HTML-based e-mail, so be careful about sending HTML-formatted mail messages to those who haven’t explicitly told you that they want to receive their messages formatted with HTML.
234
Chapter 8: Sending E-mail with ColdFusion
In Chapter 7, “Implementing ColdFusion Loops,” you saw a generic form processor script in which the tag generated an HTML table displaying the names and values of the fields submitted from any HTML form. You can use that idea inside a tag to modify the generic form processor so that it builds the form information into an e-mail message rather than just displays it on the browser screen. Listing 8.3 shows how to accomplish this task. Listing 8.3
Generic Form Processor Revisited
A Generic Form Processor
Thank you for your submission!
No form data submitted!
235
236
Chapter 8: Sending E-mail with ColdFusion
NOTE HTML-formatted e-mail messages can use the tag to incorporate graphics into the messages. If you use , make sure you provide a fully qualified URL for the src attribute, as in this example:
Example: Attaching Files to E-mail Messages ColdFusion can include file attachments in the e-mail messages it creates. In earlier versions of ColdFusion, you used the mimeattach attribute of the tag to indicate the drive, path, and name of the file that you wanted to attach to the message. This approach worked fine but suffered from the unfortunate drawback of being able to handle only one file attachment. If you had multiple files to send, you had to create an e-mail for each file and send the attachments one at a time. As of ColdFusion 4.5, however, developers can now use the tag to incorporate as many file attachments as necessary. As an example of how this capability can be useful, consider the form shown in Figure 8.3, which allows users to select a number of different publications in PDF format to be sent to them by e-mail. The source code for the form is shown in Listing 8.4. Listing 8.4
Selecting PDFs to Be Sent by E-mail
Post a Message Post a Message
Please provide the information requested below and then click the “Post Message” button.
To:
Mailing List Subscribers
From:
Subject:
Message:
241
242
Chapter 8: Sending E-mail with ColdFusion
Listing 8.6
continued
Figure 8.5 mission.
One way to post to a mailing list is via an HTML form sub-
The script that processes the form submission, shown in Listing 8.7, queries the e-mail addresses of the current subscribers out of the database and then sends a copy of the submitted message to each one, thanks to the use of the query attribute in the tag. Listing 8.7
Sending a Message to Mailing List Subscribers
Mailbox Contents Mailbox Contents
The messages in your mailbox are shown below. Click on a message’s subject to view the entire message.
From
Subject
#from#
#subject#
The from, messagenumber, and subject variables referenced in Listing 8.8 refer to fields of information available in the query object named
246
Chapter 8: Sending E-mail with ColdFusion
qGetMessageHeaders. Others available when retrieving only message headers include date, to, cc, and replyto. The hyperlinks produced on the summary page point to a script called showmessage.cfm and pass to it a query string parameter that contains the message number. You’ll see how to use this message number in the next section.
Example: Retrieving the Entire Message When you’re ready to display the entire message, you need to use the tag with action set to GetAll. In this case, still creates a query object to hold all the data it downloads, but some additional fields are added to the query object beyond the fields you receive when only the headers are downloaded. These additional fields include • body—Contains the body of the message. • headers—Contains all header information. • attachments—Contains a tab-delimited list of the names of any attached files. • attachmentfiles—Contains a tab-delimited list of the names of the temporary files on the server where the attachment files are stored. You can use this extra information to display an entire message to the user. Listing 8.9 shows you how. Listing 8.9
Displaying an Entire Mail Message
CC:
#cc#
Subject:
#subject#
Message:
#body#
Message Deleted Message Deleted Return to the summary page
Deleting a mail message is easy enough, but it’s important to realize that message numbers are reassigned after a message is deleted from the server. Suppose you have messages numbered 1 through 10 on the server, and you delete number 4. After the delete, messages 1 through 3 will have the same number, but messages 5 through 10 will be renumbered as messages 4 through 9. Thus, it is important that users go to a fresh copy of the summary page rather than use the Back buttons on their browsers to back up to the original summary page they saw. Generating a fresh copy of the page
250
Chapter 8: Sending E-mail with ColdFusion
will ensure that they have the most up-to-date message numbers available and also will allow them to see any new messages that have arrived.
Whwat’s Next In this chapter, you learned how to use ColdFusion to send and receive e-mail messages. You saw how to use the tag to dynamically build and send e-mail based on data from queries and other sources within the ColdFusion environment. You also saw how ColdFusion can send out messages in HTML format and how to attach files to your outbound messages by using the tag. Finally, you read about how to use the tag to retrieve e-mail messages from a POP3 server mailbox. Now that you’ve had several chapters’ worth of practice in working with CFML, you’ve probably also had the chance to make plenty of mistakes. Like any computing language, CFML has a syntax that must be followed for your templates to be processed successfully. Unfortunately, all it takes is a simple typo for you to introduce a syntax error into your code. ColdFusion does a good job of providing detailed error information, but that information can sometimes be overwhelming to a new developer. The next chapter looks at some of the common errors you can encounter while doing ColdFusion development and how you can eliminate them. It also introduces you to some of the debugging features built into the ColdFusion Administrator and ColdFusion Studio.
9 Troubleshooting Your ColdFusion Code After working through nearly half of this book, you have no doubt come across the infamous “Error Occurred While Processing Request” screen. This is what ColdFusion displays when it encounters an error. Often it is hard to put aside the frustration you feel when this happens, but that is what you need to do so that you can focus on the content of the error message and learn from what it’s trying to tell you. ColdFusion error messages are packed with good information, but learning to interpret them can be a challenge for new developers. When an error happens, you need to correct, or debug, the error so that your script will run correctly. ColdFusion provides support for the debugging process in two important ways. First, you can use the ColdFusion Administrator to append debugging information to the end of each HTML page ColdFusion generates, and second, you can use ColdFusion Studio’s built-in debugging features to stop the script at various points to inspect what’s happening on the server. In this chapter, you’ll learn how to • Interpret common error messages and correct the underlying problems • Activate debugging information using the ColdFusion Administrator • Use CFML tags and functions to assist with debugging • Employ ColdFusion Studio’s debugging features
254
Chapter 9: Troubleshooting Your ColdFusion Code
Handling Common Error Messages Most of the problems you come across in your development work are caused by innocent typographical errors. No matter how minor the typo seems though, ColdFusion will generate an entire page of information about the error. This can be an overwhelming amount of information for a new developer to digest, but after you learn how to identify key pieces of information in the error message, you can usually zero in on the source of the error very quickly. The next several sections show you common error messages and help you to interpret the meaning of each.
Misspelled Tag or Attribute You can easily make a mistake when typing a tag’s keyword or one of its attributes. Consider the following short example: Hello, #firstName#!
The tag is misspelled, so ColdFusion will not be able to recognize the tag. The corresponding error message is shown in Figure 9.1.
Figure 9.1 Misspelling a tag name leaves ColdFusion unsure as to what command you want to execute.
Handling Common Error Messages
255
One of the most important pieces of information you can derive from the error message is the line number in the script where the error occurred. In Figure 9.1, this is revealed by the sentence The Error Occurred in C:\CFusionMX\wwwroot\ch9\fig91.cfm: line 1. Note also that the error page shows you the offending line of code in boldface text right below the mention of the line number. Another important piece of information is the diagnostic information ColdFusion provides. The sentence ColdFusion cannot determine how to process the tag cfste because the tag is unknown and not in any imported tag libraries. The tag name might be misspelled. In Figure 9.1 is ColdFusion’s attempt to tell you what’s wrong. In this case, the diagnostics are to the point and right on the money. As you’ll see with other errors, sometimes the diagnostic message can be a bit verbose, and you need to do some careful reading to figure out what’s going on. Another typographical error that occurs frequently is misspelling a tag’s attribute. Consider the following example: SELECT CustomerID, FirstName, LastName FROM Customers ORDER BY LastName, FirstName
#LastName#, #FirstName#
The preceding code produces the error message shown in Figure 9.2. The problem is that the query attribute of the tag is misspelled. ColdFusion identifies this error and provides you with a list of valid tag attributes.
Unbalanced Tags or Characters Many things in ColdFusion code occur in pairs. They include CFML commands that use opening and closing tags, parentheses, quotation marks, and # characters. The following example shows what happens when you leave off a closing tag: Today is #DateFormat(Now(),”mmmm dd, yyyy”)#.
The error message produced by this line of code is shown in Figure 9.3. Note that the initial part of the error message says Context validation
256
Chapter 9: Troubleshooting Your ColdFusion Code
error in tag cfoutput, but if you read a little further, ColdFusion tells you The start tag must have a matching end tag. This is an example of hav-
ing to read a little further into the diagnostics to figure out the problem. It is important to make sure you keep reading even if you don’t understand the initial part of the error message.
Figure 9.2 If you make a typo in an attribute name, ColdFusion provides a list of correctly spelled attributes in the error message. TIP A good way to avoid missing closing tags is to use the Tag Completion feature of ColdFusion Studio. When Tag Completion is active, Studio will add in the closing tag after you type the opening tag.
Errors that occur when other characters are not balanced tend to be more subtle. Consider the following example: Today is #DateFormat(Now(),”mmmm dd, yyyy)#.
The closing quotation mark character is missing from the value of the mask in the DateFormat() function. When this happens, ColdFusion is not sure where the mask ends. Once it bumps into the tag, it figures out that something is wrong and gives the error message you see in Figure 9.4.
Handling Common Error Messages
Figure 9.3
257
Forgetting a closing tag induces a context validation error.
Figure 9.4 Frequently, error messages are due to missing quotation marks or # characters.
258
Chapter 9: Troubleshooting Your ColdFusion Code
To see what happens if you leave off a closing parenthesis, consider the following example: Today is #DateFormat(Now(,”mmmm dd, yyyy”)#.
In the preceding code line, the Now() function is missing its closing parenthesis, so when ColdFusion encounters the comma that follows the opening parenthesis, it yields the error message you see in Figure 9.5. The diagnostic message tells you about an “Invalid CFML construct” and a “problem in the expression’s structure,” but it never explicitly tells you that you left off a closing parenthesis. In this case, that is something you have to figure out for yourself.
Figure 9.5 Some ColdFusion error diagnostics are not as forthcoming as you might like them to be.
Using Mathematical Symbols in Tags The tag is used to implement conditional logic based on the results of comparison operations such as “not equal to” or “greater than.” Recall that in CFML, you need to use English-language versions of these operators because the < and > characters are reserved for building CFML tags. You might easily forget this rule sometimes and do the following:
You can vote!
Handling Common Error Messages
259
In the preceding code, the equals sign (=) is used instead of eq or is. This results in the error message shown in Figure 9.6. The diagnostics in this case are quite good as ColdFusion says ColdFusion was looking at the following text: =.
Figure 9.6 If you use an equals sign inside a tag, ColdFusion is able to identify what you did and let you know about it. Note what happens with a slight change to the example, though: = 18>
You can vote!
Now the test is to see if Form.age is greater than or equal to 18. The problem here is that the greater than sign will close off the tag, so what ColdFusion effectively sees is this:
You can vote!
This won’t cause an error message, but it will create a problem with your logic. If Form.age is any non-zero number, it will be interpreted as a Boolean TRUE and the user, even if she is 12 years old, will see a message saying that she can vote! The characters that came after the greater than sign (= 18>) will also show up as part of the finished page.
260
Chapter 9: Troubleshooting Your ColdFusion Code
Referencing Undefined Variables Yet another typo-related error occurs when you misspell a variable name. Consider the following short example:
I would love to live in #ctiy#!
If you try to execute the preceding code, you see the error message shown in Figure 9.7. In this instance, ColdFusion tells you that it cannot find a value for the variable named CTIY.
Figure 9.7 Misspelling a variable name from any scope will result in a “Variable undefined” error. The same error can also happen with variables in other scopes, most notably the Form scope. Suppose you had set up the following field in a form:
When referring to the field in the processing script, you used the following:
Your email address is #Form.email#.
ColdFusion would look for a form field called email, but it wouldn’t find one because the field was named emial in the tag. What you really need to change in this case is your HTML code and not your ColdFusion code!
Handling Common Error Messages
261
NOTE Recall that you might also see the “Variable undefined” error when dealing with check boxes and radio buttons. If a check box or radio button is not selected, its name and value are not submitted to the server, and ColdFusion cannot determine a value for the field if you reference it. The tag is invaluable in this instance because it can provide a default value for the field in the event that it does not exist.
Database Errors Some of the more frustrating errors to diagnose are the ones that come from queries because ColdFusion simply passes along the error message from the database and doesn’t add any further explanation to the message. This leaves you pretty much on your own when it comes to debugging your SQL statements. To help you with that challenge, this section presents a number of common SQL error messages and ways you can overcome them. NOTE If the Database Activity debugging option in the ColdFusion Administrator is enabled, ColdFusion will display the SQL statement that it tried to execute and the data source at which the statement was directed. Studying the SQL statement can often help you find the source of the error quickly.
ERRORS STEMMING FROM TYPOS One typical error is making a typo when entering a database table or field name. For example: SELECT WorkshopName, WorkshopDescrition FROM Workshops ORDER BY WorkshpName
The preceding SQL command has two misspellings: the field name WorkshopDescription in the SELECT part of the statement and the field name WorkshopName in the ORDER BY clause. When you try to execute the query, you get the error message shown in Figure 9.8. The error diagnostics tell you Too few parameters. Expected 2. You can interpret this message as meaning that two database field names have not been spelled correctly, so you should double-check the spelling of all field names in the query. Another way to create the error you see in Figure 9.8 is to leave off single quotation marks (‘) where they are needed. For example: SELECT * FROM Attendees
262
Chapter 9: Troubleshooting Your ColdFusion Code
WHERE LastName = Jones
Figure 9.8 Too few parameters? Look at the number of expected parameters to determine how many field names are misspelled. Here, the last name Jones should have been enclosed in single quotation marks because it is the literal value of the LastName field that you’re searching for. When you leave off the single quotation marks, the SQL processor tries to interpret Jones as being a database field name. Because there is no database field named Jones, you get a Too few parameters. Expected 1. error from this query, meaning that one database field can’t be identified. You can easily fix this problem by wrapping the last name in single quotation marks as SQL requires: SELECT * FROM Attendees WHERE LastName = ‘Jones’
If you misspell a table name in a query, you will get a fairly straightforward message telling you that the table does not exist. For example: SELECT * FROM Registrtions
Handling Common Error Messages
263
ORDER BY DateRegistered
In this example, the table name Registrations is misspelled, leading to the error message in Figure 9.9. You can easily fix the error by correcting the spelling of the table name.
Figure 9.9 ColdFusion identifies a typo in a table name by telling you that the erroneously spelled table does not exist. The four major types of SQL statements you have read about in this book are SELECT, INSERT, UPDATE, and DELETE. If you misspell any of these reserved words or if you leave off a space character after one of them, you’ll see the error message shown in Figure 9.10. The error was triggered by the following query: INSRET INTO Attendees (FirstName, LastName) VALUES (‘Tom’, ‘Spencer’)
The diagnostics tell you Invalid SQL statement; expected ‘DELETE’, ‘INSERT’, ‘PROCEDURE’, ‘SELECT’, or ‘UPDATE’, meaning that one of the five necessary SQL commands was not present in the query. Finding the typo or the missing space character usually takes care of this error.
264
Chapter 9: Troubleshooting Your ColdFusion Code
Figure 9.10 Incorrectly spelling the name of the SQL command you’re executing will lead to an error message. DATA TYPE MISMATCHES One final kind of database error is called a data type mismatch. In this case, you are trying to compare a numerical field to a text value or vice versa. For example: SELECT WorkshopName, WorkshopDescription FROM Workshops WHERE SessionID = ‘2’ ORDER BY WorkshopName
In the preceding code, SessionID has a numeric data type, yet it is being compared to the literal text value ‘2’. This error constitutes a data type mismatch, and the result is the error message you see in Figure 9.11.
Handling Common Error Messages
265
ERRORS IN SQL SYNTAX Most of your other database errors will be due to incorrect SQL syntax. Many times this boils down to a missing single quotation mark or closing parenthesis. Consider the following example: UPDATE Attendees SET City=’Dover’, State=’DE, WHERE AttendeeID = 34372
Figure 9.11 Data type mismatches mean your database field is of one data type and the value you’re comparing it to is of a different data type. A single quotation mark is missing after the value DE in the preceding query. This leads to the error message you see in Figure 9.12. The diagnostics tell you that there is a Syntax error in string in query expression, which often means that a single quotation mark character is missing.
266
Chapter 9: Troubleshooting Your ColdFusion Code
Figure 9.12 in SQL.
All single quotation marks and parentheses must be balanced
Using Debugging Information So far, the chapter has been dedicated to helping you figure out why you keep seeing the “Error Occurred While Processing Request” screen, but even when those errors are cleared up, you may still have debugging left to do on your logic. A ColdFusion script can be interpreted and executed without error but still not produce the results you intended. In these situations, there is no error message with diagnostics to help you. Instead, you have to implement your own diagnostics to chase down the bugs. ColdFusion has a number of features to help you with this process. This section discusses the debugging information you can request through the ColdFusion Administrator (see Figure 9.13), including • Displaying customized debugging information • Enabling robust exception reporting • Enabling performance monitoring • Enabling the use of the CFSTAT utility
Using Debugging Information
267
Figure 9.13 You can control what debugging information appears on a page through the ColdFusion Administrator. If the corresponding debug options are enabled in the Administrator, all debugging information will be appended to the end of each page that ColdFusion generates. This information can be confusing to end users, so it’s best to restrict the debugging output to the IP addresses of your development team. You can do this by clicking the Debugging IP Addresses hyperlink in the left frame of the Administrator screen. Clicking this link brings up the page in Figure 9.14 where you can specify which IP addresses should be able to see the debugging output. If there are no IP addresses in the list, every user will see the debugging output. TIP The Add Current button you see in Figure 9.14 is a quick and handy way to add the IP address of your computer to the list of debugging output recipients.
The next five sections detail the kind of information you get from each of the types of debugging information.
268
Chapter 9: Troubleshooting Your ColdFusion Code
Figure 9.14 Debugging information should be restricted to the IP addresses of computers belonging to members of your development team.
Displaying Debugging Information The Enable Debugging check box you see in Figure 9.13 is an on/off switch for the display of customized debugging information. When the box is checked, the debugging information you’ve specified will be appended to the bottom of the page in one of two formats: • classic.cfm—This format, showing in Figure 9.15, is the traditional way to display debugging information from previous versions of ColdFusion. All of the data is simply appended to the end of the page in plain text format. • dockable.cfm—This format, new with ColdFusion MX, displays debugging information in an expandable tree format as shown in Figure 9.16. The tree is in a floating window in the figure, but it can be docked by clicking the docked debug pane link. This results in the debugging information being shown in a frameset with the debugging tree in the left-hand frame and the resulting page in the right-hand frame.
Using Debugging Information
269
Figure 9.15 Displaying debugging information in the “classic” style means that the information tacked on to the end of the resulting page.
Figure 9.16 The “dockable” style of displaying debugging information enables you to view more information by expanding the various items in the tree.
270
Chapter 9: Troubleshooting Your ColdFusion Code
CAUTION The “dockable” style of debugging information presentation is only compatible with Netscape Navigator 6.0 and higher and Microsoft Internet Explorer 4.0 and higher.
After you choose which debugging style you want to use, you can then proceed to configure which information you want in the debugging report. Your options include: • Report Execution Times—Enabling this feature instructs ColdFusion to include processing times for the requested template and any dependencies (such as includes or custom tag call) to run. By default, ColdFusion will only report on templates that require more than 250 milliseconds to run, but you can alter that value in the Administrator if needed. You also have two choices of output—the Summary mode will simply list out the templates and their execution times in plain text format and the Tree mode will display the templates and execution times in an expandable tree format. • Database Activity—Checking this box will result in query or stored procedure event information being included in the debugging output. • Exception Information—Enabling this feature causes ColdFusion to gather up and display all exceptions raised during the course of the processing. • Tracing Information—Checking this box means that event trace information will be included in the debugging output. • Variables—Enabling this feature means that ColdFusion wil display the names and values of all of the variables in the selected scopes. The scopes you can choose from include: Application, CGI, Client, Cookie, Form, Request, Server, Session, and URL. Just below the Custom Debugging Output form, there is a check box labeled Enable Robust Exception Information. When this box is checked, ColdFusion will display detailed information such as the URL of the template, the physical path of the template on the server, the SQL statement executed (if any), the data sources used (if any), the line number of the error and accompanying code snippet, and the Java stack trace. Some server administrators may be concerned about divulging this information for fear of hackers trying to use it to attack the server. If you share that concern, then you should deselect this check box.
Using Debugging Information
271
Performance Monitoring and cfstat If Performance Monitoring is enabled, your server administrator can track the performance of the ColdFusion Application Server by using the Windows NT or 2000 Performance Monitor or by using the command-line utility cfstat for UNIX systems. NOTE cfstat is automatically installed on UNIX servers as part of the ColdFusion installation. The Enable
CFSTAT check box has to be checked for cfstat to be available to you.
Alternatively, you can use ColdFusion to retrieve performance data by using the CFML GetMetricData() function. GetMetricData() returns a structure populated with different measures of server activity. The keys in the resulting structure include the following: • avgDBTime—Average database operation time • avgQueueTime—Average queue time (how long the average template was queued before processing) • avgReqTime—Average time to process a request • bytesIn—Number of bytes per second coming in • bytesOut—Number of bytes per second going out • cachePops—Number of times per second a cached template is removed (popped) from the template cache so that a new template can be placed into the cache • dbHits—Number of database operations ColdFusion performs per second • pageHits—Number of HTML pages generated by ColdFusion per second • reqQueued—Number of queued requests • reqRunning—Number of requests currently being processed • reqTimeout—Number of requests that timed out and never were processed NOTE On Windows systems, you use GetMetricData() as follows:
On UNIX systems, you use the following:
272
Chapter 9: Troubleshooting Your ColdFusion Code
Using CFML to Aid in Debugging Beyond the debugging support you can enable in the ColdFusion Administrator, some CFML tags and functions can also help you with troubleshooting. You read about the GetMetricData() function earlier in the chapter. The next three sections introduce you to three other useful instructions: , , and GetTickCount().
Using The tag halts the processing of a ColdFusion script. This capability can be helpful in pinning down a logic error because you can stop the script at various points in the processing and examine variable values in an attempt to determine where the logic has gone wrong. is a standalone tag that takes the showerror attribute, which you set equal to a message you want displayed when ColdFusion stops processing.
Using You can easily use a tag just to print out the values of simple variables such as numbers, dates, or strings. Outputting data stored in more complex data structures such as query objects, arrays, and structures usually requires you to write some kind of looping instruction to get everything printed out. A much faster solution is to use the tag to ask ColdFusion to print out the contents of a complex data structure in a single command. Consider this example: SELECT * FROM Employees ORDER BY LastName, FirstName
The resulting page is shown in Figure 9.17. The output is not in the most elegant format ever conceived, but it does allow you to see all the raw data that has been retrieved by the query.
Using GetTickCount() The GetTickCount() function can help you to identify commands that are taking a long time to run. You need to use the function before and after the potentially offending command and then compute the difference between the two values to figure out how many milliseconds it took for the command to be executed. For example:
Using ColdFusion Studio’s Debugging Features
273
Mailing List Sign-Up Form Mailing List Sign-Up Form
Please fill in the information below and click the “Subscribe” button to sign-up on our mailing list. Please note that all fields are required.
I have read and agree to abide by the rules of the mailing list.
The series of hidden fields near the bottom of the form instruct ColdFusion to perform required field checking. For each form field you want to be required, you need to add one hidden field whose name is the required field’s name with the suffix _required added to it. Figure 10.2 shows the HTML page generated when a user does not provide his or her last name, e-mail address, and desired e-mail format.
Figure 10.2 ColdFusion builds a list of corrective feedback messages to the user when an incomplete form is submitted. The chief benefits of the server-side approach are its ease of implementation and the fact that it tells the user about all the incomplete fields in a single page. These benefits are offset by two important drawbacks, though: • ColdFusion has to do the work to determine whether the required fields have been completed. This is an additional processing burden on your server that you could ask JavaScript to do instead. • Users have to use the Back button on their browsers to return to the form page. Depending on what browser they’re using, they may go back to a form with all the fields blanked out. This means they have to fill out the entire form again and not just the fields they didn’t complete the first time.
286
Chapter 10: Adding JavaScript to Your Forms
Using JavaScript to perform required field enforcement can alleviate these drawbacks, provided you know how to write the necessary script code. Fortunately, ColdFusion can write this code for you, meaning you don’t need to know any JavaScript to build it into your forms!
Example: Client-Side Enforcement of Required Fields The other approach to enforcing required fields is a client-side approach in which JavaScript checks the form data when the user clicks the submit button. To retool the sign-up page so that ColdFusion will add required field JavaScript to it, you have to do the following: 1. Change the tag to a tag. 2. Change the tags to tags. 3. Change the <select> tag to a tag. The , , and tags are “souped-up” versions of their HTML equivalents. The tag alerts ColdFusion that you want it to add some JavaScript that does some checking of the form before it is submitted. The and tags have special attributes that are used to indicate which fields in the form you want to have checked. Listing 10.3 shows the modified form code. CAUTION When you’re converting the form page, a common mistake is to change and <select> to and without changing and to and . Be sure to include the ColdFusion version of these ending tags as well.
CAUTION If your form started out in a file with a name ending in .htm or .html, be sure to resave the file with a .cfm extension. Otherwise, the ColdFusion tags won’t be processed. Listing 10.3
Mailing List Sign-Up Form with CFML Code to Add JavaScript
Mailing List Sign-Up Form
Please fill in the information below and click the “Subscribe” button to sign-up on our mailing list. Please note that all fields are required.
I have read and agree to abide by the rules of the mailing list.
293
294
Chapter 10: Adding JavaScript to Your Forms
Listing 10.4
continued
Note these important points about the source code: • Perhaps the most notable change between the ColdFusion source code and the code actually delivered to the browser is the addition of a large <script> block. This block contains the JavaScript code that enforces completion of the required fields. • ColdFusion converted the tag to its HTML equivalent . This conversion must happen because if the tag itself is sent to the browser, the browser will ignore it. Also, note that ColdFusion adds an onSubmit event handler to the tag; it triggers the JavaScript when the user clicks the submit button. • ColdFusion also converted the tag to a <select> tag and the tags to their HTML equivalent tags. The required attribute of the and tags tells ColdFusion to drop in JavaScript to make those fields required. By default, required has a value of no, but setting it to yes compels ColdFusion to add the JavaScript. The message attribute specifies the corrective feedback to show the users if they don’t complete a required field. The feedback message is displayed in a JavaScript alert box as shown in Figure 10.3. TIP You should always set a value for the message attribute, even though it is technically not required. ColdFusion’s default feedback message (see Figure 10.4) is not as specific as you can be if you write the message yourself.
The primary advantage of using client-side enforcement of required fields is that you save your server from having to do the enforcement work, thus reducing the load on your server and increasing its performance. and its related tags make the JavaScript easy to implement, and users never leave the form page until the form is filled out completely, meaning that they won’t have to use the Back button and run the risk of returning to a blank form. The only drawback to the JavaScript that ColdFusion generates is that it can flag the missing required fields one at a time instead of telling the user about all the missing fields in a single message. As you’ll see in the last section of this chapter, you can overcome this drawback by writing custom JavaScript that is specific to the form.
Making Fields Required
295
Figure 10.3 JavaScript can notify users of an incomplete form submission before the form data is passed along to the server.
Figure 10.4 ColdFusion uses the form field’s name to construct a generic default feedback message.
296
Chapter 10: Adding JavaScript to Your Forms
Example: Using Server-Side and Client-Side Enforcement Together As beneficial as JavaScript is, not all users can appreciate the benefits because they have disabled JavaScript on their browsers or because they’re using a browser that does not support JavaScript. To make sure that these users have their required fields filled in as well, you can combine the server-side and client-side approaches as shown in Listing 10.5. Listing 10.5
Combining Server-Side and Client-Side Enforcement of Required Fields
Personal Data Form
300
Chapter 10: Adding JavaScript to Your Forms
Listing 10.6
continued
Personal Data Form
Please enter the information requested below and then click the “Continue” button. All fields are required for the submission to be complete.
Date of Birth:
Social Security Number:
Home Telephone:
Grade Point Average:
Credit Card Number:
Implementing Data Validation
Listing 10.6
301
continued
When ColdFusion processes the code in Listing 10.6, it builds a page that includes JavaScript to perform the various validation tasks you asked for in the validate attributes. If users type in a piece of information that does not conform to the pattern expected by the JavaScript, they will see the corrective feedback you specified in the message attributes. The Grade Point Average field has an additional piece of validation added. Certainly, a person’s GPA should be a floating-point decimal number, and the validate=”float” attribute takes care of that. A valid GPA, however, should also be between 0.0 and 4.0. To make sure that what the user enters falls within this range, you can add the range=”0.0,4.0” attribute to instruct ColdFusion to drop in the necessary JavaScript. TIP Always be sure to indicate the expected format (for example, xxx-xx-xxxx for a Social Security number) in your feedback message. It will help users to know what format they should be using.
CAUTION Don’t use # characters in the data patterns you show in your corrective feedback messages. Remember that the # character has special meaning within your ColdFusion code, and using it to illustrate an expected format (for example, ###-###-#### for a telephone number) will generate an error.
Figure 10.5 shows the feedback message for an improperly formatted Social Security number. Like the JavaScript that enforces required fields, any errors are detected one at a time, so the user may have to view several single error messages before getting all the data in the appropriate format.
302
Chapter 10: Adding JavaScript to Your Forms
Figure 10.5 Data validation feedback messages should always include the expected data format so the user can figure out what corrections to make. NOTE You also can implement server-side data validation by using hidden fields in the form. The approach is very much the same as you saw for server-side enforcement of required fields, except that you can use one of the following suffixes instead of _required:
•
_date
•
_eurodate
•
_time
•
_integer
•
_float
•
_range
You can also combine client-side and server-side approaches so that you implement data validation for the broadest range of users possible.
Example: Using a Regular Expression for Validation ColdFusion’s built-in validation options enable you to implement data validation for many different kinds of input, but what if you’re collecting data that fits a validation pattern that ColdFusion can’t implement for you? For example, a valid e-mail address has a standard pattern to it, but the validate attribute of the tag doesn’t have an e-mail address
Implementing Data Validation
303
option. In such cases, you can still implement validate if you know how to express the pattern as a regular expression. Regular expressions are supported in many different computing languages (Perl, CFML, and JavaScript, among others) as a way of expressing a pattern you’re trying to match. For example, a regular expression to represent an e-mail address might look like the following: [a-zA-Z0-9_\.]+@[a-zA-Z0-9_\.]+\.[a-zA-Z]{2,3}
This ominous-looking expression is fairly easy to understand if you break it down into pieces: • [a-zA-Z0-9_\.]+—The first part of the expression means there is at least one character from the lowercase letters, the uppercase letters, the digits 0 through 9, an underscore, or a period at the start of the e-mail address. The plus sign (+) means “at least one instance,” and the period character has to be escaped with a backslash in front of it because it’s a reserved character in building regular expressions. • @—The single @ character by itself means that there should be an @ immediately after the one or more characters accounted for by the first part of the expression. • [a-zA-Z0-9_\.]+—This part means that, following the @ character, there should be at least one character from the lowercase letters, the uppercase letters, the digits 0 through 9, an underscore, or a period. • \.—This part means that a period should follow the one or more characters accounted for by the piece of the expression before it. Again, the period has to be escaped by the backslash because it is a reserved character in regular expression syntax. • [a-zA-Z]{2,3}—The last part of the expression says that the e-mail address has to end with two or three lowercase or uppercase letters. To implement this regular expression as part of your data validation, you can use a modified version of the tag. Listing 10.7 shows the mailing list sign-up form with the preceding regular expression used to validate what the user enters into the form’s e-mail address field. Listing 10.7
Mailing List Sign-Up Form with Data Validation
Personal Data Wizard -- Step 1 Personal Data Wizard - Step 1
Please complete the information requested below and click the “Next” button.
First Name:
Last Name:
E-Mail:
Using Hidden Form Fields
Listing 11.1
317
continued
Figure 11.1 The first page in the Data Collection Wizard is a standard HTML form with no hidden fields. The form in step one collects three pieces of information, and that data is submitted to the script wizard2.cfm for processing. Listing 11.2 shows the code for wizard2.cfm. Listing 11.2
Step Two of a Data Collection Wizard (wizard2.cfm)
Personal Data Wizard -- Step 3 Personal Data Wizard - Step 3
Using Hidden Form Fields
Listing 11.3
continued
Please complete the information requested below and click the “Finish” button.
Home Phone:
Business Phone:
Cell Phone:
Fax Number:
The form in step three has hidden fields for the data collected in steps one and two, in addition to visible fields that collect the final pieces of
321
322
Chapter 11: Maintaining State Information
information for the record. All this data, regardless of the type of field it resides in, will be submitted to wizard4.cfm, where it will be used to create a new database record. The code for wizard4.cfm appears in Listing 11.4. Listing 11.4
Step Four of a Data Collection Wizard (wizard4.cfm)
326
Chapter 11: Maintaining State Information
Listing 11.5
continued
TepidMail.com Login Welcome to TepidMail.com!
Please log in by entering your username and password below and then clicking the “Login” button.
Username:
Password:
Remember my username on this computer
Using Cookies
327
The form submits the data it collects to a script called processlogin.cfm. In that script, you need to see whether the user checked the Remember My Username check box and, if so, you need to place a cookie that stores the submitted username. Listing 11.6 shows you how to do this. Listing 11.6
Placing a Cookie to Remember a User’s Identity
SELECT * FROM mailUsers WHERE (username = ‘#Form.uname#’) AND (password = ‘#Form.pword#’) TepidMail.com Login
328
Chapter 11: Maintaining State Information
Listing 11.6
continued
Login Successful! Invalid username/password
Please try again.
The statement in Listing 11.6 checks to see whether the form field called rememberMe is defined. If it is, that means that the user checked the check box and wants to be remembered. In this case, the tag places a cookie called username on the user’s browser. The cookie’s value is equal to the value of the submitted form field called uname, and the cookie is set to never expire. Because a mail user now might have the cookie when returning to the login page, you can modify the login page script to use the cookie’s value, if it exists. Listing 11.7 illustrates how to do this. Listing 11.7
Mail Login Form Modified to Use a Cookie Value
Password:
Remember my username on this computer
329
330
Chapter 11: Maintaining State Information
Listing 11.7
continued
The modified login form script contains two additional instructions. The first drops a value attribute into the field if the cookie called username exists. The value attribute is set equal to the value of the cookie, thereby prepopulating the username field with the username stored in the cookie. The second excludes the Remember My Username check box if the cookie already exists.
Example: Tracking a User’s Login Status In the previous example, the processlogin.cfm script checked to see whether the username and password provided matched any of the username/password pairs in the database. If you want to remember the fact that the user provided a valid username and password, you need to record it as state information. Listing 11.8 shows you how to record a user’s login status with a cookie. Listing 11.8
Using a Cookie to Note a User’s Login Status
SELECT * FROM mailUsers WHERE (username = ‘#Form.uname#’) AND (password = ‘#Form.pword#’) TepidMail.com Login Login Successful!
336
Chapter 11: Maintaining State Information
Listing 11.9
continued
Invalid username/password
Using ColdFusion Session Variables
Listing 11.9
337
continued
Please try again.
NOTE The “Remember Me” state information is left in a cookie in this example because most users would want that information to persist over longer periods of time than session variables typically exist.
Example: Limiting Display of a Pop-up Window Suppose that you have content that you want to display in a pop-up window when a user visits your home page. However, being mindful that some users find pop-up windows annoying, you want to present the window only once so that if the user comes back to your home page, the pop-up window will not appear again. You can track whether the user has seen the pop-up window by using a session variable. Listing 11.10 shows you how to accomplish this. Listing 11.10
Tracking Pop-up Window Presentation with Session Variables
Dear cfjobhunter.com Employer: Attached please find a resume with skills that match the Position you have posted on cfjobhunter.com. Thank you for your continued support of cfjobhunter.com! The cfjobhunter.com Team
If you ever have to change the folder where the resumes are stored, the only modification you need to make to the code is in the Application.cfm file. Changing the resumeUploadPath variable there will enable the and tags in these examples to continue to work. The other type of variable you can set up in the Application.cfm file is called an application variable. You define application variables with the tag, but these variables reside in the ColdFusion Application scope rather than the Variables scope. This means that application variables will persist after a request is done processing and that the values of those variables can be accessed by other requests.
Example: Creating a Basic Application.cfm File
347
To be able to declare application variables, you need to have a tag in your Application.cfm file, as in this example:
You can name the application however you like, but the name should not exceed 64 characters. ColdFusion uses this name to distinguish between application variables from different applications, so make sure the name you give your application is different from any others that currently exist on the server. You also can specify a timeout period for application variables in the tag by using the applicationtimeout attribute. By default, application variables will time out after two days. You can set this variable to a different value as follows:
The CreateTimeSpan() function take four parameters: a number of days, hours, minutes, and seconds. As it is used in the preceding example, it specifies a time span of 1 day, 12 hours, 0 minutes, and 0 seconds before an application variable times out. Application variables have a default timeout period that is set in the ColdFusion Administrator. You can specify a maximum timeout period though the Administrator as well. You do so on the Administrator’s Memory Variables page, shown in Figure 12.2. NOTE You also can specify default and maximum timeouts for session variables on the same page as your application variables.
Application variables are appropriate for information that needs to be tracked across all users of the application. For example, suppose you want to monitor how many people are logged in to the site at any given time. In that case, you can use the following Application.cfm file:
Example: Creating a Basic Application.cfm File
Figure 12.3 tions.
351
Client variables can reside in any one of a number of loca-
The sessionmanagement and clientmanagement attributes are set to yes to activate ColdFusion’s session and client management features. You also can reset a session variable’s timeout period by using the sessiontimeout attribute together with the CreateTimeSpan() function:
The tag in this example specifies that client variables should be stored in a browser cookie. Client variables have much longer life spans than session variables. By default, ColdFusion will keep client variables around permanently as long as the user who owns them visits your site every 90 days. ColdFusion will automatically eliminate client variables belonging to a user who hasn’t visited your site in the past 90 days in an effort to keep the amount of storage space used by client variables from becoming unruly. You can set the client variable storage period to a different value in the ColdFusion Administrator. Figure 12.4 shows the specifics for storing client variables in
Example: Creating a Basic Application.cfm File
353
the cfjobhunter data source. To change the storage period, you simply enter a different number of days in the field near the top of the screen and click the Submit Changes button.
Figure 12.4 Client variables are user-specific but stored over longer time spans than session variables. Client variables are well-suited to storing long-term information about a user. A good example is the user’s preferences on a customized site. Suppose users of cfjobhunter.com can choose the background and foreground colors for pages generated by the site. Then in the script that processes the user preferences, you would issue commands like the following to set values for the client variables:
NOTE Recall that the # character must be escaped when used within a CFML tag.
You could then refer to these values in each tag to implement the preferences:
354
Chapter 12: Using the ColdFusion Application Framework
NOTE You don’t need to use when reading and writing client variables because they are not stored in a shared memory space like application and session variables.
So far you have seen three different kinds of variables that are available to you through the ColdFusion application framework, and how or when you would use each kind might not be clear. The following list provides a quick summary of each class of variables and appropriate uses for them: • Application variables—These variables are stored in shared memory and must therefore be locked when you reference them. They are for storing global, application-wide information that needs to persist over a time span usually measured in days. Examples: Number of people currently logged in to the application, number of times users have used a particular function of the site. • Session variables—These variables are also stored in shared memory and should therefore be locked when referencing them. They store user-specific information that needs to be available over relatively short time spans that are typically measured in minutes. Examples: Tracking a user’s login status or the contents of her shopping cart. • Client variables—These variables are not stored in shared memory, so you don’t need to lock the Client scope when you reference them. You can store client variables in a data source, browser cookies, or your System Registry. They store user-specific information that needs to persist over relatively long time spans. Examples: A user’s customization preferences or a set of search parameters he uses frequently. You’re not limited to using only one of these kinds of variables within your applications, so feel free to pick the type of variable that’s best suited to the task you’re faced with.
Making Sure a User Is Logged In The only uses of Application.cfm you’ve seen so far are related to the different classes of variables available through the application framework. You can do much more with an Application.cfm file though. Recall that the code in the Application.cfm file is executed in advance of the code in the template that you requested. This means you can deploy standard code that must be processed for every page in your Application.cfm file. Suppose you have a set of pages that you want to protect from users who have not
Example: Creating a Basic Application.cfm File
355
properly logged in to the cfjobhunter.com site, and you’re tracking user logins by means of a cookie named loggedIn. You can modify the Application.cfm code as follows to implement the page protection:
The additional instruction checks to see whether a cookie named loggedIn exists and, if it doesn’t, the user is redirected to a login page before the code for the protected template can be processed. A user who has logged in properly will have the cookie, and the redirect will not occur, allowing that user to proceed to the protected page.
356
Chapter 12: Using the ColdFusion Application Framework
CAUTION You can find yourself in a bit of a catch-22 when you implement this kind of page protection because you can end up protecting the ColdFusion script that logs the user in. For example, suppose a user goes to the login page and submits username and password data. Before the ColdFusion script can run to process the username/password pair, the Application.cfm code would see that the user doesn’t have the login cookie and redirect him right back to the login page! One solution to this problem is to change the code in your Application.cfm file so that it doesn’t check for the cookie if the user is trying to run the login script. If the name of your login script is processlogin.cfm, you would need to modify the code as follows:
This change would prevent the redirect from happening if the user was requesting the processlogin.cfm script, regardless of whether he had the login cookie. Another approach to solving the problem involves putting the login form and the processing script in their own subfolder with their own Application.cfm file that doesn’t check for the existence of the login cookie.
Deploying a Standard Look and Feel One other good use of an Application.cfm file is to deploy standard blocks of HTML code that support the look and feel of your site. You can accomplish this by putting the standard code in a file and then dropping in the contents of that file by means of a tag. Listing 12.1 shows the finalized Application.cfm file that includes the standard header. Listing 12.1
A Finished Application.cfm File for cfjobhunter.com
NOTE If you’re going to deploy a standard page header through the Application.cfm file, make sure you do so by means of a tag. Putting HTML code directly into the Application.cfm file is not considered good coding style.
Example: Responding to Application Errors As a new developer, you’ve very likely encountered a screen like the one in Figure 12.5. This is the standard ColdFusion error message page. It contains a wealth of good information for the developer, but end users can easily be overwhelmed and frustrated by the page. For this reason, it’s a good idea to build a custom error page into your applications that notifies the users of the error in a more friendly way. The tag is another feature of the ColdFusion application framework that gives you a way to handle errors much more gracefully. Using the tag, you can create two major types of custom error responses based on what value you choose for the type attribute of the tag. The first type is for type=”exception” in which you direct ColdFusion to process and display a custom error page that can be built from both CFML and HTML code. The second is for type=”request” in which you direct ColdFusion to a custom error page that contains only HTML code. The
358
Chapter 12: Using the ColdFusion Application Framework
type=”exception” error page will kick in for most errors. However, if the error is so serious that ColdFusion cannot process the CFML code in the type=”exception” error page or if an error occurs while processing the CFML code in the type=”exception” error page, the type=”request” error page will be invoked. The next two sections demonstrate how to create each type of custom error response.
Figure 12.5 The infamous “Error Occurred While Processing Request” screen is not a friendly way to let end users know about an application error. NOTE You also can set the type attribute of the tag to validation (for checking the validity of data the user entered on a form) or monitor (for logging of exceptions that you catch yourself with and ).
Creating a Custom Exception Error Page When an exception occurs, you want to accomplish two primary objectives with your custom error page: • Inform the end users of the error in a nonthreatening way and give them a set of “next steps” they can take to try to recover from the exception. • Capture as much information about the error as you can and send it to an administrator or developer to troubleshoot the error.
Example: Responding to Application Errors
359
You can accomplish the first objective easily enough by constructing a page that has the same look and feel as the application and tells users that an error has happened, preventing the application from processing their requests. The second objective may seem to present the bigger challenge, but fortunately ColdFusion captures a great deal of information about each error that occurs and makes it available to you through the Error variable scope. The different error variables you can use include the following: • Error.template—This variable tells you the name of the ColdFusion script that was being processed when the error occurred. • Error.diagnostics—This variable provides you with ColdFusion’s explanation of what went wrong, the line number in the template where the offending code that caused the error can be found, and an explanation of what may have caused the error. This is the same information that ColdFusion presents on the standard “Error Occurred While Processing Request” page. • Error.datetime—This variable notes the date and time that the error occurred. • Error.HTTPreferer—This variable indicates the page that the user was on prior to the page where the error occurred. This information gives you an idea of how the user reached the problem page. • Error.querystring—This variable captures data passed on the query string, if there was any. • Error.browser—This variable tells you the kind of browser the user was using and what operating system the browser is running on. This information is taken from the CGI variable called HTTP_USER_AGENT. • Error.remoteaddress—This variable tells you the IP address of the end user’s machine. • Error.mailto—This variable contains the e-mail address of the system or site administrator. It can be a global setting specified in the ColdFusion Administrator, or it can be set up using the mailto attribute of the tag. • Error.generatedcontent—This variable contains all the HTML code generated for the dynamic page up until the error occurred. You can use any or all of these error variables in your custom exception error page. Listing 12.2 shows one example of a custom exception error page that uses many of these variables.
360
Chapter 12: Using the ColdFusion Application Framework
Listing 12.2
A Custom Exception Error Page for cfjobhunter.com
We’re sorry!
362
Chapter 12: Using the ColdFusion Application Framework
Listing 12.3
continued
Error!
We’re sorry! An error has occurred which prevents us from processing your request. You were trying to process the file #Error.template# at #Error.DateTime#. Please click the “Report Error” button below to notify the development team of the error and they will work hard to correct the problem.
Note that references to the error variables are enclosed in # signs, but the tag cannot be explicitly used within the script. The code in Listing 12.3 satisfies the first objective to gently inform the user of the error. However, accomplishing the second objective is impossible here because you can’t use CFML tags. Specifically, you can’t put a tag into this script, so what you see in Listing 12.3 is the next best thing. The error variables are written into hidden form fields whose values can be passed along to a second script (errormail.cfm), which generates the e-mail to the site administrator. Listing 12.4 shows one way to write the errormail.cfm script. Listing 12.4
Sending Error Data Captured by the Custom Request Error Page (errormail.cfm)
364
Chapter 12: Using the ColdFusion Application Framework
Listing 12.5
continued
For the code in the OnRequestEnd.cfm file to be processed for a requested template, it must be located in the same folder as the Application.cfm file that runs for the requested template. NOTE On UNIX and Linux systems, you need to spell OnRequestEnd.cfm with uppercase O, R, and E, as you have seen it written in this section. You can use lowercase letters on the Windows platform because its file system is not case sensitive. For ease of migration between Windows and UNIX/Linux platforms, consistently using the uppercase letters is best.
What’s Next In this chapter, you read about the features of the ColdFusion application framework and how you can use them to bring many individual scripts together to work as an application. You learned about the Application.cfm file and the critical role it plays in the application framework. You saw that you can set up application variables and enable session and client variables in the Application.cfm file. Because the code in an Application.cfm file is processed before any template located in the same folder, you saw that you could use Application.cfm to deploy a standard page header and any special processing that needs to happen for each page generated. Next, you learned about the tag and how it can be used to detect errors and redirect the users to friendly pages that notify them of the error. Finally, you saw how the OnRequestEnd.cfm file can be used to implement page footers and other code that should be executed at the end of each request. The ColdFusion application framework is a sometimes-overlooked feature that can significantly contribute to a high-end Web site or application. One other hidden gem that’s available on your ColdFusion server is Verity—a search engine that you can use together with ColdFusion to make all content on your site searchable. You’ll learn about Verity in the next chapter.
13 Creating a Search Engine with Verity ColdFusion makes it easy to search content stored in a database, but what if you need to make your static content searchable? ColdFusion can help you with that task, too, thanks to the Verity search engine, which comes bundled with ColdFusion. Verity allows you to perform rapid, free-text searches by means of a ColdFusion tag. The results of the search are stored in a construct that is similar to a query recordset, so you need only hand off those results to the tag to have them displayed on a Web page. In this chapter, you’ll learn how to • Set up and maintain Verity collections, both through the ColdFusion Administrator and programmatically through CFML tags • Set up search interfaces that enable users to search content on your site • Index data from a database and learn why doing so is advantageous NOTE The Verity search engine is available as a standalone, off-the-shelf product as well. For more information, visit http://www.verity.com/.
370
Chapter 13: Creating a Search Engine with Verity
Setting Up a Verity Collection The first step in setting up a Verity search on your site is to create at least one Verity collection. A collection is a set of files that Verity creates to summarize the content on your site. When a user conducts a keyword search on your site, the keyword will be looked up in the collections he or she is searching, and any documents in which the keyword occurs will be considered a match. Matching documents are ranked according to how frequently the keyword shows up in each document. You normally create Verity collections through the ColdFusion Administrator, but you also can create and manage your collections through CFML instructions as well. The next two sections show you how to implement both approaches.
Managing Collections Through the ColdFusion Administrator If you log in to the Administrator and then click the Verity Collections link in the left frame, you’ll be taken to the page shown in Figure 13.1.
Figure 13.1 The ColdFusion Administrator includes a page that helps you to manage your Verity collections. On the upper part of the Verity Collections page, you can indicate the name of the new collection you want to create. To create a collection, follow these steps:
Setting Up a Verity Collection
371
1. Provide a name for the new collection in the Name field. 2. Specify the path where the Verity collection should be stored. The path defaults to a value such as c:\cfusion\verity\collections on Windows machines, and normally, this is a perfectly good place to keep the files that make up the collection. You are welcome to store your collections at other locations in your file system as well. 3. Choose a language filter for the collection. Verity can create collections for content in more than a dozen languages, including English, German, French, Spanish, Danish, Italian, Dutch, and Norwegian. 4. Indicate whether you want to create a new collection or map an existing collection. Normally, you want to create a new collection, so the default choice of Create a Collection is fine. Mapping a collection refers to setting up a reference to a Verity collection that already exists but was not set up through the ColdFusion Administrator. 5. Click the Submit Changes button to create the collection. After you create the collection, it will show up in the list of Connected Verity Collections on the lower half of the Verity Collections page. From here, you can select a collection and perform a number of operations on it, including • Index—Indexing refers to putting content into the collection by examining the documents that make up your site and summarizing their contents. • Repair—If a Verity collection becomes corrupted, you can perform a repair operation on it to try to get it back to normal. In the event that the repair does not help, you will likely have to delete the collection and re-create it from scratch. • Optimize—Verity collections can become fragmented over the course of frequent updates, so it’s important to optimize the collection regularly. Optimizing your collection can lead to faster search performance by structuring the files that make up the collection in the most efficient and compact way possible. • Purge—Purging refers to emptying the contents of the collection. After a purge operation, the collection still exists, but there is nothing in it. • Delete—A delete operation completely removes the collection from your server.
372
Chapter 13: Creating a Search Engine with Verity
If you’re creating a collection for the first time, you’ll very likely want to index some content right after you create it. To create an index, select the new collection from the list of connected collections and then click the Index button. You’ll then see a screen like the one shown in Figure 13.2.
Figure 13.2 The indexing process begins with your directing the indexer to the files that make up your site. You indicate the kinds of files you want included in the indexing process by specifying a comma-delimited list of their extensions. You’re given a starter list that includes extensions for HTML and CFML documents, but you can expand the list far beyond that. The following list shows some of the different file types that Verity can index: • Plain text • ANSI and ASCII text • Rich Text Format (RTF) • Microsoft Word • Microsoft Wordpad • Microsoft Write • Adobe Framemaker
Setting Up a Verity Collection
373
• Adobe Acrobat PDF • WordPerfect • Microsoft Excel • Lotus 1-2-3 • Corel Quattro Pro • Microsoft PowerPoint • Lotus Freelance To index any of the preceding file types, you simply add the type’s file extension to the list. Next, you need to specify the directory path to the files. A Browse Server button allows you to scan the server’s file system and choose the desired path by means of a Java applet. The indexer will look only at files in the specified folder. If you want the indexer to process content in subfolders below the specified folder, make sure you check the box labeled Recursively Index Subdirectories. As the files you select are indexed, the names of the files are stored as part of the collection. When you present search results to your users, however, you need to know the URL of the file so that you can build a hyperlink that points to the file. To assist with this task, you need to specify the Return URL as part of the indexing setup. The Return URL is a prefix that can be added to the filename to form a valid URL that points to the file. For example, suppose you specified an indexing directory path of c:\inetpub\ wwwroot\. This is the root directory of your Web server, so the Return URL would be the Web address that points to that directory—for example, http://www.mysite.com/. If you choose to recursively index subdirectories, the subdirectory paths will be stored along with the filenames and will be automatically appended to the Return URL to form valid URLs that point into subdirectories of your root directory. Finally, you can choose a language filter for the indexing process and then click the Submit Changes button to begin indexing. Depending on how much content you’re indexing, the process could take a minute or two. When the indexing is complete, you will be taken back to the Verity Collections page. At this point, your collection is indexed and can now be searched.
Managing Collections Through CFML Instructions The preceding section showed you how to create and index a collection through the ColdFusion Administrator. The Administrator provides an easy and convenient way to set up and manage Verity collections, provided that
374
Chapter 13: Creating a Search Engine with Verity
you have access to the Administrator. In some development teams, developers do not have direct access to the Administrator, in which case they need a different way to work with Verity collections. Developers in this situation can use the and tags instead. always takes the collection and action attributes. collection specifies what collection you want to work with, and action indicates what you want to do to the collection. You can set action equal to
any of the following values: • create—Creates a new collection. • optimize—Optimizes an existing collection. • repair—Repairs an existing collection. • map—Creates a mapping to an existing collection not created through ColdFusion. • delete—Eliminates a collection. CAUTION Be sure to lock the Verity collection during an optimize or repair operation. Locking it prevents corruption of the collection by preventing others from accessing it while you are. For example, you can lock the collection like this:
If you create a collection using , you can subsequently index it by using the tag. also takes collection and action attributes, although actions are different from those for . The following are actions you can take with : • update—Indexes the collection after it’s created and is used for incremental additions to the collection thereafter. • delete—Removes an item from the collection. • purge—Empties the collection. • pefresh—Empties the collection and re-indexes it. You can use and to replicate much of the functionality found in the ColdFusion Administrator. Listings 13.1 and 13.2 show how to programmatically create and index a collection using CFML tags. Listing 13.1 is simply an HTML form that collects the data necessary to set up and index the collection. The form is shown in Figure 13.3.
Setting Up a Verity Collection
Listing 13.1
HTML Form to Gather Collection Information
Collection Name:
Collection Location:
Directory Path to Content:
375
376
Chapter 13: Creating a Search Engine with Verity
Listing 13.1
continued
File Extensions:
Return URL:
Index Subdirectories:
Yes No
Listing 13.2 shows the code that takes the collection setup information and performs the necessary operations to create and index the collection. Listing 13.2
Creating and Indexing a New Verity Collection
Collection created!
The collection named #Form.collName# has been created and indexed.
After you create the collection, you can continue to manage it by using and . For example, to add a new document to the collection, you could use the following instruction:
NOTE operations on collections that have been put into production should be locked to prevent
corruption of the collection. ✔ To learn how to schedule templates to run automatically, see “Scheduling ColdFusion Templates” in Chapter 1.
378
Chapter 13: Creating a Search Engine with Verity
Figure 13.3 You can develop your own interface to manage Verity collections in the event that you don’t have access to the ColdFusion Administrator. You can develop scripts to handle other collection management tasks as well. For example, you might set up the following short script to run on a regular basis through the Scheduled Tasks feature of the ColdFusion Administrator:
That way, your collection would be automatically refreshed on a regular basis.
Making Your Collection Searchable When an indexed collection exists,you’re free to allow users to conduct searches against it. Searching a Verity collection involves using the tag. returns a set of results that are structurally similar to results returned by a tag. As you’ll see in this section, you can feed the results directly into a tag to present the search findings to the user quickly and easily.
Making Your Collection Searchable
379
All you really need to start a Verity search is a keyword to search for, but the tag can handle much more than that. The example in this section demonstrates how robust the tag and the results it returns are. To begin, consider the HTML form shown in Figure 13.4. This form allows users to enter a comma-delimited list of keywords, as well as choose which collections they want to search and the maximum number of records they want returned. The code for this page is shown in Listing 13.3. Listing 13.3
Verity Search Interface Form
Making Your Collection Searchable
Listing 13.4
continued
#Title# #URL#
SELECT articleID, articleTitle, articleBody, articleSummary, articleAuthor FROM articles Collection indexed!
Indexing Data in a Database
Listing 13.5
387
continued
Journal articles from the data source articles have been indexed and are now searchable by using the Verity collection called articleSearch.
The tag in Listing 13.5 is of type custom, meaning that you will use it to index database data. The query attribute specifies the name of the query that contains the data to be indexed. The remaining attributes are all mapped to different fields in the database. The key attribute is generally mapped to the database table’s primary key field—in this case, articleID. The title and body attributes are mapped to the articleTitle and articleBody fields, respectively. The custom1 and custom2 attributes allow you to specify two other fields to include in the index. Here, the custom fields are articleSummary and articleAuthor, meaning you could search the collection by these fields as well. After you create and index the collection, you can still search it by using . The search results will contain key, title, body, custom1, and custom2 values that you can use to construct your results page. Listing 13.6 shows an example. Listing 13.6
Presenting Results from Searching Indexed Database Data
a href=”showArticle.cfm?articleID=#Key#”>#Title#
#ReplaceNoCase(Custom1,Form.keyword,
What’s Next
Listing 13.6
389
continued
“” & Form.keyword & “”)>#
No articles found matching your keyword: #Form.keyword#.
Because you’re not searching actual documents, the hyperlink you set up in the search results must point to a ColdFusion script that displays the article whose articleID value is passed to it on the query string. The article’s primary key value is stored in the Key field of the indexed data, so you need only drop its value onto the end of the query string to set up the link.
What’s Next This chapter showed you how to add a search engine to your site by using the Verity search engine that comes bundled with ColdFusion. You saw how to create and maintain Verity collections, how to set up an interface that allows people to conduct searches, and how to present search results to users. Additionally, you saw how to index data from a database and make that data searchable through Verity as well. This capability is advantageous when you’re searching through databases that have long text fields because performing a search with the SQL LIKE operator is much more processor intensive than performing a free-text search with Verity. Now that you’ve surveyed many of CFML’s beneficial features, it’s time to put some of them to work. The next three chapters present case studies showing how you can use ColdFusion to develop useful applications. The next chapter focuses on setting up a corporate directory, similar to what you might find on a company’s intranet site.
390
Chapter 13: Creating a Search Engine with Verity
14 Case Study: Corporate Intranet Directory Now that you’ve worked through 13 chapters of basic ColdFusion concepts, it’s time to see how to combine those concepts to produce useful Web applications. This chapter and the next two are dedicated to ColdFusion case studies in which you will see how to build a ColdFusion application from start to finish. Corporate directories are very common applications found on company intranets. A corporate directory allows any employee to look up another employee’s contact information. Additionally, someone needs to maintain the employee data behind the directory, so it’s reasonable to expect that there should be some administrative features that enable the appointed employee to do necessary maintenance. The administrative functions should not be publicly available and, even more than that, they should be password-protected to keep unauthorized users from changing employee information. You will learn how to do all of these things over the course of this case study. Specifically, in this chapter, you’ll learn how to • Examine the relational database that supports the corporate directory • Create a search interface that allows a user to search on all or part of an employee’s last name or to search by department • Create a login function for an administrative user • Build administrative functions that allow an administrative user to add, edit, or delete employees
392
Chapter 14: Case Study: Corporate Intranet Directory
Designing the Database The relational database for the corporate directory case study is fairly simple. It is made up of two tables named Employees and Departments. Both tables and the relationship between them are shown in Figure 14.1.
Figure 14.1 The DepartmentID foreign key field in the Employees table relates employees to their respective departments. The Employees table contains fields for all the basic information you need to store about a given employee—name, address, Social Security number, and so on. The department an employee is assigned to is specified by means of the foreign key DepartmentID, which associates an employee with a department found in the Departments table. NOTE The corporate directory database has been developed in Microsoft Access so that you can download a copy of the database from the Que Web site. Use of Access is fine for demonstration and prototyping purposes, but production Web applications should work with true client/server databases such as Microsoft SQL Server or Oracle because these databases are built to withstand a multiuser environment while preserving data integrity.
The database has been populated with 30 employee records, with employees assigned to more than 10 departments. The database, as well as the scripts you’ll develop next, are completely scalable to larger numbers of employees and departments.
Creating the Search Interface
393
Creating the Search Interface The public face of the corporate directory application is the search interface that all employees can use to look up fellow employees. The interface developed here will allow a user to search by last name or by department, but you can adapt the concepts to search on other fields as well. Listing 14.1 shows the code for the script that generates the initial page of the search function. Listing 14.1
search.cfm—Initial Search Page
SELECT DepartmentID, DepartmentName FROM Departments ORDER BY DepartmentName XYZ Manufacturing Employee Directory XYZ Manufacturing Employee Directory
394
Chapter 14: Case Study: Corporate Intranet Directory
Listing 14.1
continued
Search By Last Name
Enter all or part of an employee’s last name below and click the “Search” button.
#DepartmentName# SELECT EmployeeID, FirstName, LastName FROM Employees WHERE (DepartmentID = #ListGetAt(Form.departmentID,1)#) AND (Deleted = 0) ORDER BY LastName, FirstName
Creating the Search Interface
Listing 14.2
continued
#qSearchResults.RecordCount# records found matching your namedepartment search for ’#Form.searchName#’ ’#ListGetAt(Form.departmentID,2)#’
397
398
Chapter 14: Case Study: Corporate Intranet Directory
Listing 14.2
continued
. Please click a name for more information.
SELECT DepartmentID, DepartmentName FROM Departments ORDER BY DepartmentName
No records found!
Please try another search:
Search By Name
Enter all or part of an employee’s last name below and click the “Search” button.
Creating the Search Interface
Listing 14.2
399
continued
Search By Department
Select a department from the list below and click the “Search” button to see all employees from that department.
The initial tag figures out which search was requested by testing for the existence of the submit buttons. If the user wants to search by last name, the button named byName would have been clicked and Form.byName would therefore exist during the processing of the script. Similarly, if the user had wanted to search by department, Form.byDept would be defined. For each of these possibilities, there is a tag to perform the appropriate query. Note the use of the SQL LIKE operator in the search by last name. This is what allows the user to key in all or part of the last name. For example, a user who enters the letter C into the search field will see the results shown in Figure 14.2. Each matching name is hyperlinked to a detail page that will show complete information for that person. TIP Use of the LIKE operator also allows the user to leave the field blank to call up a listing of all employees in the database.
If the user wants to search by department, the tag uses the DepartmentID passed to the script from the form on the previous page. Recall though that the values passed from the drop-down list are in the form of a comma-delimited list containing both the department name and
400
Chapter 14: Case Study: Corporate Intranet Directory
primary key value. This is why you have to use the ListGetAt() function to extract the primary key value from the list. The primary key value is the first item in the list, so the appropriate function call is ListGetAt(Form.departmentID,1).
Figure 14.2 Searching on a single letter brings up all employees whose last names begin with that letter. You should note these three important points about the beginning of the script: • Deleted employees are excluded from the search by use of the Deleted = 0 condition in each WHERE clause. • Both tags have the same value for the name attribute, so regardless of which query was done, the results are stored in the query object called qSearchResults. • If the user tries to come directly to searchresults.cfm without submitting any form data to it, neither of the submit buttons will exist, and the tag you see will redirect the user back to the search page (search.cfm). The next step is to determine whether any records were retrieved by the query. This is done using the second you see in Listing 14.2. If qSearchResults.Record is zero, the condition in the is interpreted as
Creating the Search Interface
401
a Boolean FALSE and ColdFusion processes what follows the tag. In this case, ColdFusion generates a page that informs the user that no records were found and allows the user to try another search. If qSearchResults.RecordCount is greater than zero, the condition in the is interpreted as a Boolean TRUE and ColdFusion processes the code between the and tags. This code tells the user how many records were found during the search and then outputs a bulleted list of the matching employee names. As noted earlier, each name is hyperlinked to a script that will show all contact information for that employee. A considerable amount of conditional logic goes into building the statement that tells the user how many records were found. The different tags you see there handle the following tasks: • Making sure that the word record is used for a single record retrieved and that records is used for more than one record retrieved. • Indicating whether the search was by name or by department. • Restating the name or department the user searched on. When restating the department, the department name is extracted from the dropdown list value passed to the script. Because this value is in the form of a comma-delimited list, you can use the ListGetAt() function to extract the name of the target department. Storing the department name in the list saves you from having to do another query to figure out the name of the selected department. The hyperlinks on each of the employee names point to a script called employeedetail.cfm. It is that script’s job to figure out whose name was clicked and to present the detailed information about that person. To help the script in making that determination, you need to embed the employee’s EmployeeID value into the hyperlink as a query string variable. Listing 14.3 shows you how ColdFusion uses that query string value to retrieve the information for the correct employee. Listing 14.3
employeedetail.cfm—Displays All Contact Information for the Selected Employee
To add, update, or remove employees, please login below.
Username:
Password:
406
Chapter 14: Case Study: Corporate Intranet Directory
Listing 14.4
continued
Listing 14.4 uses the ColdFusion and tags to incorporate JavaScript into the resulting page. The JavaScript code makes sure that the user enters both a username and a password. Figure 14.4 illustrates the kind of message displayed when the user fails to include one of these pieces of information.
Figure 14.4 JavaScript alert boxes notify the user when a form has not been filled out completely. The username and password are submitted to a script called processadminlogin.cfm (see Listing 14.5). The script uses a statement to determine whether the username/password combination is acceptable. If it is, the tag places a cookie on the user’s browser to indicate a successful login, and then ColdFusion delivers a page with links to the different administrative functions. If the username/password combination is not valid, the user is told this and is given the opportunity to try logging in again.
Creating the Administrator Login
Listing 14.5
processadminlogin.cfm—Accepts or Rejects Username and Password Provided
Creating the Administrative Functions The Human Resources department employee tasked with maintaining the employee database will need three different administrative functions, which include the abilities to • Add a new hire to the database • Change an existing employee’s information, perhaps due to an address change or a promotion • Delete an employee who has left the company This section shows you how to write the scripts to support these functions. Recall from Chapter 5, “Interacting with Databases: Inserting, Updating, and Deleting,” that adding a new record to a database is a two-step process. Listing 14.7 shows you the ColdFusion code for the first step in the process—providing a form that the user can use to enter the data for the new record. Listing 14.7
addnewemployeeform.cfm—Presents a Form to Collect New Employee Data
First Name:
Last Name:
411
412
Chapter 14: Case Study: Corporate Intranet Directory
Listing 14.7
continued
Department:
#DepartmentName#
Title:
Social Security Number:
Salary:
Office Location:
Telephone Extension:
Creating the Administrative Functions
Listing 14.7
413
continued
The , , and tags are used in combination to incorporate JavaScript into the resulting HTML page (see Figure 14.6). The JavaScript ColdFusion makes each field a required field and, in the cases of the new employee’s Social Security number and salary, checks to make sure the data entered into those fields is in a valid format. The list of departments is dynamically generated based on the information retrieved from the database by the instruction near the beginning of the script. After the user completes necessary information, the form data is submitted to the script called addnewemployee.cfm. Listing 14.8 displays the code used to add the submitted information to the database. Listing 14.8
#Form.fName# #Form.lName# has been added to the employee database.
Administration Home Page
The command you see in Listing 14.8 builds the new employee’s e-mail address based on first and last name information provided on the data entry form. The expression Left(Form.fName,1) extracts the first letter
Creating the Administrative Functions
415
of the person’s first name. This information is then concatenated with the person’s last name. Because a person’s last name might have a space in it (De Soto, for example), the Replace() function is used to replace any spaces in Form.lName with the empty string before the concatenation. Finally, the string @xyz.com is added to the end of the e-mail address, and then the entire string is converted to lowercase letters with the Lcase() function.
Figure 14.6 ColdFusion writes JavaScript that makes sure the data fields are filled out correctly. TIP You can use the Replace() function to replace other undesirable e-mail address characters such as dashes or apostrophes. What constitutes an unacceptable e-mail address character varies from one mail system to another, so be sure to consult with your mail server administrator to find out which characters you should exclude.
After the e-mail address is constructed, the tag handles the creation of the new record by executing an SQL INSERT statement. Note the use of the Now() function to provide the values for the DateEntered and DateLastModified fields. Also note that the Deleted field is initially set to 0, meaning that the new employee should not be considered as being deleted. When the new record is added, the user receives a confirmation of the addition and is then provided with a link back to the administration home page. Listing 14.9 shows the code for the main administration page, which is a
416
Chapter 14: Case Study: Corporate Intranet Directory
simple set of hyperlinks pointing to the initial pages of each admin function. Even though it is purely an HTML page, you should still save the code in a .cfm file so that the password protection afforded to the other scripts applies to the administration menu page as well. Listing 14.9
adminmenu.cfm—Provides Links to the Add, Edit, and Delete Functions
SELECT EmployeeID, FirstName, LastName FROM Employees WHERE Deleted = 0 ORDER BY LastName, FirstName XYZ Manufacturing Employee Database XYZ Manufacturing Employee Database
Please choose the employee whose record you wish to edit and then click the “Edit Employee” button.
Chapter 14: Case Study: Corporate Intranet Directory
Figure 14.7 The editing process begins with the user selecting an employee record to edit. The second step in the editing process requires you to retrieve all data for the selected employee and present it to the user in the context of an HTML form. This way, the user can make changes to any information that is out of date. Listing 14.11 shows the ColdFusion code that produces the edit form. Listing 14.11
editform.cfm—Displays Selected Employee’s Data in Form Fields
#DepartmentName#
Creating the Administrative Functions
Listing 14.11
continued
Title:
Social Security Number:
Salary:
Office Location:
Telephone Extension:
E-mail Address:
421
422
Chapter 14: Case Study: Corporate Intranet Directory
Listing 14.11
continued
The first retrieves the selected employee’s data based on the primary key value passed in the form field named employeeID. The second retrieves the names and primary key values of the different departments so that ColdFusion can construct a drop-down list of departments. The , , and tags are used in the edit form so that the page delivered to the browser will include JavaScript that enforces required fields and provides data validation for the salary and Social Security number values. Each tag uses the value attribute to prepopulate the corresponding form field with a piece of data from the database. The drop-down list of departments requires some slightly different handling because you cannot prepopulate it with a value like you can with the text fields. You can, however, preselect one of the options in the drop-down list by including the selected attribute inside the tag corresponding to the option you want to preselect. The trick is to determine which tag should get the selected attribute as the tag is generating them. The tag you see in Listing 14.11 handles this by looking for a DepartmentID value that matches the DepartmentID in the employee’s record. When it finds a match, it drops in the selected attribute so that the employee’s department comes up preselected on the form. The final point to note about the edit form is the use of the hidden field to pass the selected employee’s EmployeeID value on to the final step in the process. This primary key value is needed to restrict the effect of your SQL UPDATE statement to just the selected employee’s record. Figure 14.8 shows the finished form. Note that the hidden field does not explicitly show up onscreen, but it is still a valid part of the form.
Creating the Administrative Functions
423
Figure 14.8 The edit form displays the selected employee’s information in a way that allows the user to easily make changes. The third and final step of the editing process is to take the data submitted from the edit form and use it to update the employee’s record. Listing 14.12 demonstrates how this is done. Listing 14.12
updateemployee.cfm—Updates Employee’s Record with Data Submitted from Edit Form
SELECT EmployeeID, FirstName, LastName FROM Employees WHERE Deleted = 0
Creating the Administrative Functions
Listing 14.13
425
continued
ORDER BY LastName, FirstName XYZ Manufacturing Employee Database XYZ Manufacturing Employee Database
Please choose the employee whose record you wish to delete and then click the “Delete Employee” button.
The script in Listing 14.13 is almost the same as the script you saw in Listing 14.10. In essence, they both do the same thing—present a list of active employees that the user can choose from. The difference in Listing 14.13 is the use of JavaScript to confirm that the user wants to proceed with the delete operation (see Figure 14.9). This is accomplished by the onSubmit event handler in the tag. NOTE The JavaScript you see in Listing 14.13 was not written by ColdFusion. It’s beneficial to know some JavaScript yourself so that you’re not limited to using only the JavaScript that ColdFusion knows.
426
Chapter 14: Case Study: Corporate Intranet Directory
Figure 14.9 The JavaScript confirm() method is useful when asking users to confirm that they want to proceed. If the user clicks the OK button in the JavaScript confirm pop-up box, the primary key of the selected employee is submitted to the final script deleteemployee.cfm. Listing 14.14 shows the code for this script. The first does a logical delete of the employee’s record by setting the Deleted field to 1 (or TRUE), and the second query retrieves the employee’s first and last names so that they can be used to provide a confirmation message to the user. NOTE If you use a DELETE query instead of doing a logical delete, you would need to retrieve the selected employee’s first and last names prior to deleting the record. Listing 14.14
deleteemployee.cfm—Performs a Logical Delete of an Employee’s Record
New ColdFusion Developers Conference Home Page Welcome!
The New ColdFusion Developers Conference is the perfect opportunity to advance your knowledge of dynamic Web development with ColdFusion and to network with your fellow developers.
If you have already registered and need to view your schedule or change your registration information, please log in below. Otherwise, please complete the registration process.
Registering an Attendee
Listing 15.1
continued
Username:
Password:
Remember my username on this computer.
435
436
Chapter 15: Case Study: Conference Registration Site
Listing 15.1
continued
Figure 15.2 The conference home page directs new visitors to register and returning visitors to log in. The home page script uses and tags to make sure that a returning user provides both a username and a password. Note that the field named uname uses the value of the cookie called ConferenceUserName. Because this cookie will not exist if the user did not check the “Remember Me” check box, the tag near the beginning of the script provides a default value for the cookie so that the username field will show up empty initially. Users who choose to begin the registration process will move on to the page you see in Figure 15.3. This is the first step of the process in which the user provides basic contact information and chooses a username and password. All the form fields, with the exception of the second address line, are required thanks to JavaScript built into the form by and tags. The code that generates this page is shown in Listing 15.2.
Registering an Attendee
Listing 15.2
register1.cfm—The First Step in the Conference Registration Process
Registering an Attendee
Listing 15.3
continued
<script type=”text/javascript”> New ColdFusion Developers Conference Registration Page Registration
Thank you for registering, #Form.fName#! Your conference username and password are #Form.uname# and #Form.pw1#, respectively. You will need your username and password whenever you log into the site to check your schedule or change your registration information.
To complete the registration process, please choose the workshop you’d like to attend for each of the four conference sessions. Workshop enrollment is limited to 50 people on a first-come, first-served basis. If a workshop you want is full, you will be placed on a waiting list.
#SessionDay# #SessionTime#
Registering an Attendee
Listing 15.3
continued
SELECT AttendeeID, DateRegistered FROM Registrations WHERE (WorkshopID = #Evaluate(“Form.session” & sID)#) AND (Deleted = 0) ORDER BY DateRegistered SELECT Email, FirstName FROM Attendees WHERE AttendeeID = #Cookie.AttendeeID#
#ListGetAt(workshopList,sID)#
Registered Registered Waiting List
Your conference username and password are #Username# and #Password#, respectively. You may change your contact information, review your schedule, or make changes to your schedule by logging into your administration page from the conference home page.
Best wishes for an enjoyable conference!
New ColdFusion Developers Conference Registration Page
451
452
Chapter 15: Case Study: Conference Registration Site
Listing 15.4
continued
Registration
Thank you! You will receive an e-mail confirming your registration shortly. Please print a copy of this page for your records as well.
Listing 15.5 continued #qLogin.FirstName#’s Administration Menu
Please choose one of the options below:
Edit My Contact
455
456
Chapter 15: Case Study: Conference Registration Site
Listing 15.5 continued Information
Show My Schedule
Change My Schedule
Login Failed!
Please try again:
Username:
Password:
Remember my username on this computer.
Supporting a Returning Attendee
457
Listing 15.5 continued
Note in Listing 15.5 that the attendee administration functions are located in a subfolder called useradmin. The scripts in this subfolder are protected by the Application.cfm script you see in Listing 15.6. The script checks to see whether the user has the AttendeeID cookie. A user who does not have the cookie is redirected back to the conference home page by the tag you see in the listing. Listing 15.6
Application.cfm—Secures the Attendee Admin Functions
New ColdFusion Developers Conference User Admin #Cookie.AttendeeName#’s Administration Menu
Please choose one of the options below:
Edit My Contact Information
Show My Schedule
Change My Schedule
Supporting a Returning Attendee
459
Figure 15.8 The menu of attendee administration options should be presented only to attendees who have logged in. The first of the three attendee administration functions allows attendees to make changes to their contact information. Clicking the hypertext Edit My Contact Information invokes the script named editcontactinfo.cfm shown in Listing 15.8. The script retrieves the attendee’s current contact information in the database by using the primary key value stored in the AttendeeID cookie. That information is then used to prepopulate a form (see Figure 15.9) so that the attendee can see the data and also make any necessary changes to it. and tags build in JavaScript that enforces the required fields. Listing 15.8
editcontactinfo.cfm—Presents Current Contact Information for Editing
UPDATE Attendees SET FirstName=’#Form.fName#’, LastName=’#Form.lName#’, Title=’#Form.title#’, Company=’#Form.company#’, Address1=’#Form.address1#’, Address2=’#Form.address2#’, City=’#Form.city#’, State=’#Form.state#’, ZipCode=’#Form.zip#’, Phone=’#phone#’, Fax=’#fax#’, Email=’#Form.email#’, DateLastModified=#Now()# WHERE AttendeeID = #Cookie.AttendeeID# New ColdFusion Developers Conference User Admin Contact information updated!
Supporting a Returning Attendee
Listing 15.9
465
continued
Your contact information has been updated as follows:
The second attendee administration function displays the attendee’s current workshop schedule. This operation is handled by the script named displayschedule.cfm that is shown in Listing 15.10. The first query in the script retrieves information about the workshops the attendee has chosen, including session day and time. Note that this script requires a fairly complicated query that involves the joining of the Workshops, Sessions, and Registrations tables. Next, you need to find out how many people are signed up for each of the workshops retrieved by the query qGetSchedule. This operation is handled by the tag that immediately follows the query qGetSchedule. With all this information in hand, the tag generates table rows, one for each session, showing the chosen workshop for that session and whether the attendee is registered or has been wait listed. The status determination is made by the tag you see in the second
of each table row. In each case, uses results from one of the attendee count queries performed by earlier in the script. Figure 15.10 shows the resulting page. Listing 15.10
displayschedule.cfm—Shows Current Workshop Schedule
SELECT AttendeeID, DateRegistered FROM Registrations WHERE (WorkshopID = #WorkshopID#) AND (Deleted = 0) ORDER BY DateRegistered New ColdFusion Developers Conference User Admin
Supporting a Returning Attendee
Listing 15.10
continued
#Cookie.AttendeeName#’s Schedule
Date/Time
Status
Workshop Information
SELECT Workshops.*, Sessions.SessionDay, Sessions.SessionTime FROM Workshops, Sessions WHERE Workshops.SessionID = Sessions.SessionID ORDER BY Workshops.SessionID
SELECT WorkshopID FROM Registrations WHERE (AttendeeID = #Cookie.AttendeeID#) AND (Deleted = 0)
474
Chapter 15: Case Study: Conference Registration Site
Listing 15.12
continued
SELECT WorkshopID FROM Workshops WHERE (SessionID = #sID#) AND (WorkshopID #Evaluate(“Form.session” & sID)#) INSERT
Supporting a Returning Attendee
Listing 15.12
continued
INTO Registrations (AttendeeID, WorkshopID, DateRegistered, Deleted) VALUES (#Cookie.AttendeeID#, #Evaluate(“Form.session” & sID)#, #Now()#, 0) SELECT AttendeeID, DateRegistered FROM Registrations WHERE (WorkshopID = #WorkshopID#) AND (Deleted = 0) ORDER BY DateRegistered
475
476
Chapter 15: Case Study: Conference Registration Site
Listing 15.12
continued
New ColdFusion Developers Conference User Admin Change Your Schedule
Your schedule has been changed to the following:
Date/Time
Status
Workshop Information
SELECT AttendeeID, WorkshopID, DateRegistered FROM Registrations
Providing an Administrative Report
Listing 15.13
continued
WHERE Deleted = 0
479
480
Chapter 15: Case Study: Conference Registration Site
Listing 15.13
continued
#qGetWorkshops.WorkshopName#
50 #qGetRegStats.RecordCount#
488
Chapter 16: Case Study: Online Store
Listing 16.1
continued
Allowing Customers to Shop
489
The tag enables the use of session variables and sets the timeout period for these variables to 30 minutes by using the CreateTimeSpan() function. Next, the data source name is set up as a variable so that queries can be written as follows: SELECT ProductID, ProductName FROM Products ORDER BY ProductName
TIP Setting up the data source name in the Application.cfm file makes it easy to redirect your entire application to a new data source if needed. For example, you might develop and test the application using a test database, but when the application is ready for the production environment, you need to switch to a production database. If you’ve set up the data source as a variable in the Application.cfm file, making the switch is just a matter of changing the file.
Finally, the Application.cfm file checks for the existence of arrays named Session.arrProducts and Session.arrQuantities. If these arrays do not exist, ColdFusion creates them. This is the equivalent to giving the customer an empty shopping cart upon entering the store. CAUTION Failure to use the tag when reading data from and writing data to the session scope can lead to memory corruption on your ColdFusion server. Always remember to make judicious use of when working with the session and application scopes!
The first order of business for customers just entering the store is to let them pick a product of interest. This is handled by the catalog.cfm script you see in Listing 16.2. The tag retrieves all product names and primary key values from the Products table, and the tag generates the options in the drop-down list from which customers can choose products. Figure 16.2 shows the resulting page. Listing 16.2
catalog.cfm—Displays Products in a Drop-Down List
<select name=”product” size=”1”> #ProductName#
Allowing Customers to Shop
491
Figure 16.2 Customers choose products from a dynamically generated drop-down list. When a customer chooses a product and clicks the submit button, the choice is submitted to the script named productdetail.cfm shown in Listing 16.3. The primary job of this script is to retrieve all available detail about the selected product and build an HTML page from the detailed information. Listing 16.3
productdetail.cfm—Displays Detailed Information About a Selected Product
SELECT * FROM Products WHERE ProductID = #Form.product#
Allowing Customers to Shop
Listing 16.3
continued
#ProductName# #DollarFormat(ProductPrice)#
#ProductDescription#
493
494
Chapter 16: Case Study: Online Store
Listing 16.3
continued
The script first checks to see whether a form field called checkout exists. This may seem odd because there was no form field named checkout on the previous page (catalog.cfm). However, there will be a submit button named checkout on the subsequent page (addtocart.cfm) that the customer can click to move on to the checkout line. The form on the next page submits back to productdetail.cfm, so that is why you have to check for it here. If the form field called checkout does exist, the tag redirects the customer to checkout.cfm, which is the first step in the checkout process. If there is no form field named checkout, the tag retrieves the selected product’s record, and the tag is used to drop information about the product onto the finished page. Note that the value of the ProductImage database field can be dropped into an tag so that a photo of the product appears on the page as well (see Figure 16.3). The product detail page uses and tags to incorporate JavaScript that makes sure the user has chosen a valid quantity. The name and primary key value of the product are built into the form as hidden fields. The detail page form can have as many as three submit buttons. The first, named add, is the one customers use to add the product to their shopping carts. The second, named catalog, will return the customers to the catalog.cfm page. The you see near the end of the script checks to see whether there is anything currently in a customer’s shopping cart and, if there is, includes a submit button named checkout, which will send the
Allowing Customers to Shop
495
customer on to the checkout line if clicked. Regardless of the submit button used, the form submits to the addtocart.cfm script shown in Listing 16.4.
Figure 16.3 The detail page is the place where you convince the user to buy the selected product. Listing 16.4
addtocart.cfm—Adds a New Product to the Customer’s Shopping Cart
Allowing Customers to Shop
Listing 16.4
continued
We have added #Form.quantity# #Form.ProductName# s to your shopping cart. Please choose another furniture piece to examine or proceed to the checkout counter.
Product ID
Product Name
Quantity
Unit Price
Extended Price
Grand Total:
#DollarFormat(total)#
The first order of business in the script is to see whether a form field named continue exists. This field refers to the submit button named continue you see later in the script. If the customer clicked that submit button, the tag redirects to the next step in the checkout process (customerinfo.cfm). Next, the script checks to see whether a form field called update exists. This field corresponds to the submit button named update further down the script. The script presents the contents of the customer’s shopping cart in such a way that the quantities can be changed to different values or to zero
506
Chapter 16: Case Study: Online Store
to drop the product from the cart (see Figure 16.5). Customers who change one or more quantities need to click the submit button named update for the changes to take hold.
Figure 16.5 Customers get one final chance to change the contents of their shopping carts before completing the purchase. If the submit button named update has been clicked, the statement that checks for it will execute code that updates the contents of the cart. This is done by looping through the form fields where the quantities are specified. All these fields start with the letters qty followed by the array index in Session.arrQuantities to which they correspond. The loop first checks each quantity to see whether it has been set equal to zero. If so, the value of the loop index is added to a list called deleteList. The indexes in deleteList get deleted after the loop has run to completion because deleting products from the shopping cart while the loop is running will produce an error message when the loop continues to try processing array elements when there is nothing left in the arrays. If the quantity has not been set to zero, the loop then checks to see whether the quantity is not equal to what it has stored in the Session.arrQuantities array for that index. If the two values are unequal, Session.arrQuantities is changed to have the value of the new quantity.
Completing the Sale
507
After the loop runs its course, you then need to check deleteList to see whether there’s anything to be deleted. The following the loop uses the ListLen() function to see whether there are any values in deleteList and, if there are, a second takes care of removing the necessary ProductID values and quantities from Session.arrProducts and Session.arrQuantities. With the shopping cart now updated, the script can now generate the table that summarizes the cart’s contents. After initializing a variable to track the total cost of the purchase, the script uses another tag to generate each row of the table. The product’s name and price have to be queried from the database during each loop iteration, but the ProductID and quantity do not because they can be taken directly from the shopping cart arrays. Note that the quantities are written into a form field so that the customer can change them if desired. and tags add JavaScript that makes sure that each quantity field is filled in with a valid integer value. After the customer finalizes the contents of the shopping cart, the submit button named continue moves the customer on to the last two steps in the checkout process. These steps are discussed in the next section.
Completing the Sale To finish the customer’s purchase, you need to find out where to send the merchandise and how he or she plans to pay for it. The collection of shipping and other contact information is handled by the form you see in Figure 16.6. The form is generated by the customerinfo.cfm script in Listing 16.6. Listing 16.6
customerinfo.cfm—Collects Customer Information
UPDATE Customers SET CardType=’#Form.ccType#’, CardNumber=’#Form.ccNumber#’, CardExpires=’#Form.ccExpires#’, CardName=’#Form.ccName#’, DateLastModified = #Now()# WHERE CustomerID = #Form.CustomerID# Purchase Approved!
Your credit card transaction has been approved. You can expect your order to arrive within 10-14 days. Thank you for shopping at OnlineFurniture.com!
517
518
Chapter 16: Case Study: Online Store
Listing 16.8
continued
We’re sorry!
Your credit card transaction was not approved. Please contact our Customer Service Department for further assistance.
Once the order is started, the next step is to submit the credit card information provided by the customer to get approval on the purchase. Many services will do the credit card processing for you, and many ColdFusion custom tags have been developed to make the submissions to these services. One such tag is the tag, which submits the credit card information to Cybercash (which is currently owned by VeriSign) for processing and approval. The completesale.cfm script in Listing 16.8 uses the tag to pass the price of the purchase, the credit card number and expiration date, and the customer’s address and ZIP Code. Cybercash returns to ColdFusion a message that is stored in a query object named qReturnMessage. By looking at the status field in qReturnMessage, you can make a determination as to the success or failure of the transaction. The that follows the tag examines qReturnMessage.status to see whether it contains the string “success”. If it does, the order’s PurchaseApproved field is set to TRUE, and then a tag inserts new records into the OrderLineItems table. Each new record contains a ProductID and corresponding quantity, as well as the OrderID of the order it is part of. Finally, the script uses a second tag to notify the user about the success or failure of the credit card transaction. NOTE You must set up ColdFusion custom tags such as in the ColdFusion Administrator (see Figure 16.8) before you can use them.
What’s Next
519
Figure 16.8 ColdFusion custom tags can be written in C++ or Java and must be configured in the ColdFusion Administrator before use.
What’s Next This chapter showed you how to build an electronic commerce site using a session variable–based shopping cart. You saw how to set up a catalog that allows customers to browse through the products you have for sale. You learned how to let customers specify the quantities for products they want and how to add that information to their shopping carts. You constructed a checkout page where customers finalize the contents of their carts by changing quantities or removing items. Finally, you collected shipping and credit card information from your customers and submitted the purchase to a merchant services provider for processing. This is also the final chapter in the book. You will find two appendices just beyond this chapter that can help jog your memory when you’re trying to recall a certain attribute of a CFML tag or the proper syntax of a CFML function. Appendix A, “ColdFusion Markup Language Tag Reference,” summarizes the tags discussed in the book and their attributes and syntax. Appendix B, “ColdFusion Markup Language Functions,” does the same for the CFML functions you learned about throughout the book.
520
Chapter 16: Case Study: Online Store
What remains for you to do now is to thoughtfully adapt the concepts you have learned in this book to new programming challenges you encounter as a ColdFusion developer. Remember that this book has been written for the purpose of sharing useful examples that illustrate important ColdFusion development concepts, not to provide a “cookbook” with steps that you can simply copy to solve problems. Each programming problem is unique and requires that you dedicate fresh thinking to its solution. You won’t have a lot of value as a ColdFusion developer if the only problems you can “solve” are the ones that already have their solutions published in a book. Make it your goal to develop a strong command of ColdFusion development concepts and CFML while always leveraging lessons learned from the past so that you’re not reinventing the wheel. If you do this, you will find the path to becoming a top-notch ColdFusion developer to be personally satisfying and professionally rewarding. We wish you the best on that journey!
Appendix A ColdFusion Markup Language Tag Reference How This Reference Is Organized This appendix provides details on how to use each of the ColdFusion Markup Language (CFML) tags discussed in this book. The tags appear in alphabetical order, and each tag’s entry presents an overview of the tag, its syntax, a description of the tag’s attributes, and an example of how to use the tag.
Overview: is a standalone CFML tag that halts the processing of a ColdFusion script. Any HTML code generated before is encountered is delivered to the browser. Optionally, you can use the showError
attribute to display an error message to users, telling them why processing has stopped. Syntax:
Attributes: The optional showError attribute is set to display the text of a message to the users, explaining why processing has been terminated. Example:
524
Appendix A
Overview: is used in an Application.cfm file to give the ColdFusion application a unique name and to activate client and session variables for the application, if those features are needed. You also can control where client variables are stored and the timeout values for application and session variables.
Syntax:
Attributes: • name—Provides a unique name for the application. • clientmanagement—Enables the use of client variables when set to “yes”. The default value is “no”. • clientstorage—Specifies where client variables are to be stored. Can be set to “cookies”, “registry”, or the name of an ODBC data source set up through the ColdFusion Administrator’s Client Variables page. • setclientcookies—Stores the CFID and CFTOKEN values used to support client and session tracking in browser cookies when the default value of “yes” is used. If you set this attribute to “no”, you must pass the values of CFID and CFTOKEN through query strings as you move from page to page. • sessionmanagement—Enables the use of session variables when set to “yes”. The default value is “no”. • sessiontimeout—Specifies how long an inactive session can exist before timing out. The value is set using the CreateTimeSpan() function. • applicationtimeout—Specifies how long an inactive application can exist before timing out. The value is set using the CreateTimeSpan() function. • setdomaincookies—Makes the CFID and CFTOKEN cookies available to all servers within your domain (for example, www.yourcompany.com and store.yourcompany.com) when set to “yes”. The default value is “no”.
Appendix A
525
Example:
NOTE Timeout values for application and session variables cannot exceed the absolute maximums set up in the ColdFusion Administrator.
Overview: lets you programmatically manage Verity collections. The action attribute determines the behavior of the tag and can be set to “create”, “repair”, “optimize”, “map”, or “delete”.
Syntax:
or
or
or
or
Attributes: • action—Indicates the action you want to take on the nominated collection. • collection—Specifies the collection you want to manage. • path—Specifies the path to the location in the file system where the new collection should be stored when you use action=”create”. When you use action=”map”, path indicates the path to the location of the existing collection that you’re aliasing. • language—Sets a language filter for the collection.
526
Appendix A
Examples: To create a new collection:
To optimize an existing collection:
NOTE Collections must be exclusively locked with the tag before you repair or optimize them.
Overview: places a cookie on the user’s browser. Each cookie must have a name and a value, and you can optionally provide cookie expiration information.
Syntax:
Attributes: • name—Indicates the cookie’s name. • value—Indicates the cookie’s value. • expires— Specifies when the cookie should expire. Can be set to a specific date (“12/31/02”), a number of days (“30”), “NEVER”, or “NOW” (using “NOW” has the effect of deleting the cookie). If no expires attribute appears, the cookie is a “session cookie” that expires when the user’s browser is shut down. • secure—Indicates that you want to place the cookie over a Secure Sockets Layer (SSL) connection when set to “yes”. The cookie will not be placed if the browser does not support SSL. • domain—Optionally specifies the domain for which the cookie is valid. • path—Optionally specifies the path on the server for which the cookie is valid. Requires the concurrent use of the domain attribute.
Appendix A
527
Examples: To create a cookie with an expiration date (the cookie will be written to the user’s hard drive when the browser is shut down):
To create a cookie with no expiration date (the cookie will be eliminated when the browser is shut down) :
Overview: can assist you in debugging a ColdFusion application by display-
ing the contents of a ColdFusion variable. The variable can be a simple variable, query data, an array, a structure, or a WDDX packet. Syntax:
Attributes: The required var attribute is set equal to the name of the variable whose contents you want displayed in the browser. Example: SELECT * FROM Customers
Overview: redirects the user to an error-handling template when a
ColdFusion processing error occurs. Generally, the error template is more user-friendly than the standard “Error Occurred While Processing Request” screen that ColdFusion uses by default. When the tag is invoked, error variables with the prefix “Error.” are created to help you determine the nature of the error. Syntax:
528
Appendix A
Attributes: • type—Specifies what type of error the tag should respond to. Can be set to “request” for general processing errors, “validation” for serverside data validation errors, “monitor” for monitoring exception handling with /, and “exception” for dealing with unhandled exception conditions. • template—Provides the URL of the template that should be invoked when an error occurs. • mailto—Optionally used to provide the e-mail address of the application or system administrator. • exception—Indicates what kind of exception you want the tag to respond to. Used only when type is set to “monitor” or “exception”. Examples:
or
or
Overview: manipulates files in the ColdFusion server’s file system. You also
can use it to help upload a file posted as part of an HTML form submission. The behavior of the tag is determined by the value of its action attribute. Syntax:
or
or
or
Appendix A
529
or
or
or
or
Attributes: • action—Specifies the file action you want to take. Can be set to “read”, “readbinary”, “write”, “append”, “copy”, “move”, “delete”, “rename”, or “upload”. • file—Indicates the path to the target file for read, readbinary, write, append, and delete actions. • variable—Names the variable that should store the data read in from a file. • output—Specifies the content to be written to a file during write (creating a new file) or append (adding to an existing file) operations. • mode—Sets permissions for files being written or uploaded to a Unix/Linux server. This attribute is ignored by ColdFusion running in a Windows environment. • addnewline—Adds a newline character after the content ColdFusion has written to the file when set to “yes”. • attributes—Specifies a list of file attributes (for example, readonly, archive, system, normal). • source—Specifies the location of the source file for copy, move, and rename actions. • destination—Specifies the storage location for the file produced by a copy, move, rename, or upload operation.
530
Appendix A
• filefield—Specifies the name of the field used to upload the file. • nameconflict—Tells what ColdFusion should do if a naming conflict occurs between the file being uploaded and a file already in the destination directory. Can be set to “overwrite”, “makeunique” (ColdFusion decides on a unique name for the uploaded file), “skip” (ColdFusion does not save the uploaded file), or “error” (ColdFusion produces an error message detailing the name conflict). • accept—Specifies a list of acceptable file MIME types for uploading. Examples: To upload a file:
To write content to a new file:
To append content to an existing file:
CAUTION The tag should be locked with the tag whenever there is a risk that another user or program might be seeking concurrent access to the file.
Overview: lets you create a JavaScript-enabled HTML form in which ColdFusion provides the JavaScript code. is a wrapper for the tags
that make up the fields in the form and will be converted into an equivalent tag before the generated page is delivered to the browser. is used with and , which are discussed later in this appendix. Syntax:
Appendix A
531
... form field tags ...
Attributes: • name—Gives the form a unique name. Note that this name is meaningful only to the JavaScript code, not to ColdFusion. • action—Provides the URL of the ColdFusion script that will process the submitted form data. • method—Specifies which HTTP method (get or post) is to be used when submitting the form data. • enctype—Indicates which form data encoding approach to use. You need to set this value to “multipart/form-data” if you’re creating a form that lets a user upload a file to your server. • target—Denotes the name of the frame or window where the results of the form submission should be directed. Example: First Name: Last Name: E-Mail:
Overview: implements conditional logic within your ColdFusion scripts. ColdFusion evaluates a Boolean expression located inside the tag and then takes action depending on whether the condition is TRUE or FALSE. can be extended with multiple tags to test conditions
532
Appendix A
beyond the one located in the tag and with a tag to provide code to be processed if none of the conditions tested in the or tags prove to be TRUE. Syntax: code to process if Boolean expression has a value of True
or code to process if Boolean expression has a value of True code to process if Boolean expression has a value of False
or code to process if Boolean code to process if Boolean code to process if Boolean ... code to process if none of
expression 1 has a value of True expression 2 has a value of True expression 3 has a value of True
the Boolean expressions evaluates to True
Attributes: None. Examples: To create a simple if-then rule: You can register to vote!
To create an if-then-else rule:
You are currently logged in.
To test several possibilities:
Appendix A
533
Invalid user type!
TIP When testing a condition with several possible outcomes, you can make your code more efficient by putting your most likely outcome in the tag and progressively less likely outcomes in subsequent tags. This technique makes your scripts perform better because ColdFusion will jump out of the when it finds a condition that is TRUE and has processed the associated code. If you put the most likely outcome first, ColdFusion will find the TRUE condition more quickly and not have to hunt any further through the statement.
Overview: incorporates content from a separate file into the script cur-
rently being processed. The code in the included file can be HTML, CFML, or a combination of the two. This makes the tag ideal for modularizing blocks of standard HTML or ColdFusion code and deploying them from single files rather than copying them into each individual page. It also makes code maintenance much less work-intensive because you’ll need to edit only the included file, not each page. Syntax:
Attributes: The template attribute is set equal to the URL of the included file. The URL can be a relative path. Example: Welcome to our Online Store!
534
Appendix A
... code for the main content of the page ...
Overview: helps you to manage content stored inside a Verity collection. You can use to populate the collection initially, to incrementally add
items to or remove items from the index, to completely refresh the index, or to purge the index for repopulation. The behavior of the tag is determined by the value of its action attribute. Syntax:
or
or
or
or
or
Appendix A
535
Attributes: • action—Indicates the action you want to take on the target collection. Valid actions include “update”, “refresh”, “purge”, and “delete”. • collection—Supplies the name of the collection you want to manage. • type—Indicates what kind of indexing you want to do. Possible values include “path”, meaning you will provide a path to an entire directory of content to be indexed; “file”, meaning you will provide the location of a single file to add to or delete from the index; or “custom”, meaning that you want to index data from a database. • key—Provides the path to the target file when type is set to “file”. If type is set to “custom”, key is set equal to the name of a database field that uniquely identifies the record. Generally, this means the primary key field. • path—Supplies the path to the directory where the content to be indexed can be found when type is set to “path”. • URLpath—Provides a prefix that Verity can combine with a filename to create a valid URL for the file. • extensions—Provides a comma-delimited list of the different file extensions you want indexed. • recurse—Indicates that you want to recursively index subdirectories of the directory specified in the path attribute when set to “yes”. • language—Indicates a language filter to use during indexing. • query—Specifies the name of a query containing data to be indexed. This attribute is used only when type is set to “custom”. • title—Specifies the name of a database field whose value is to act as a title for the record being indexed. • body—Specifies the name of a database field whose value is to act as the body of the record being indexed. • custom1,custom2—Allow you to select two other database fields whose values should be indexed. NOTE When you’re indexing data from a database, make sure that the title, body, custom1, and custom2 attributes of the tag are set to names of databases fields that you want to be searchable. Only data in the fields indicated by these attributes can be searched.
536
Appendix A
Examples: To index content in the Web server’s root directory:
To clear out the collection and rebuild it:
To add a new document to your collection:
To index data from a database: SELECT * FROM Resumes
NOTE All tags should be locked to prevent corruption of data in the collection.
Overview: creates form fields rigged with JavaScript that performs required
field and data validation tasks. The tag lets you create JavaScript-enabled text and password fields, radio buttons, and check boxes.
Appendix A
537
Syntax:
or
Attributes: • type—Specifies the type of input field. Possible values are “text”, “password”, “checkbox”, and “radio”. • name—Provides a unique name for the form field. • value—Specifies the value to be associated with the field. Optional for type=”text” and type=”password”. • size—Indicates the size of a type=”text” or type=”password” field. • maxlength—Limits the number of characters that can be entered into a type=”text” or type=”password” field. • required—Builds JavaScript into the resulting HTML page that makes the field required if set to “yes”. The JavaScript will prevent the form from being submitted until the required field is completed. • range—Sets beginning and ending values in a range of numbers. If this attribute is used, ColdFusion will write JavaScript into the resulting HTML page to make sure that the value entered by the user falls inside the range. • validate—Writes data validation JavaScript into the resulting HTML form that checks what the user typed to make sure it fits the general pattern for that specified class of information if set. Possible values include date, eurodate, time, float, integer, telephone, zipcode, creditcard, social_security_number, and regular_expression. • pattern—Provides the regular expression used for the validation if validate is set to “regular_expression”. • message—Provides a corrective feedback message to show the user in the event of an error. Feedback messages show up in JavaScript alert boxes.
538
Appendix A
Example:
First Name:
Last Name:
Title:
Company:
Telephone:
Fax:
E-mail Address:
Appendix A
539
TIP ColdFusion’s default feedback messages are not very specific, so you should always be sure to provide detailed feedback in every message attribute.
NOTE can be used only inside a tag.
Overview: creates a new database record based on data submitted through an HTML form. The names of your form fields and database fields must match exactly for to work correctly.
Syntax:
Attributes: • datasource—Indicates the name of the data source where the record should be created. This attribute is required unless dbtype is set to “dynamic”. In that case, ColdFusion determines the data source by examining the connectstring attribute. • dbtype—Specifies the database driver type (ODBC, OLE DB, and so on). You can set dbtype to “dynamic” if you want to specify the connection string yourself. • connectstring—Provides a connection string for initiating contact with an ODBC data source. • tablename—Specifies the name of the table where the record is to be created.
540
Appendix A
• tableowner—Provides the name of the table owner, if the target database supports the concept of table ownership. • tablequalifier—Supplies the qualifier value, if you need to provide a qualifier. The need for table qualifiers varies from one database to another. For example, the qualifier for an SQL Server database table is the name of the database itself. • formfields—Provides a comma-delimited list of form fields whose values should be used in creating the new record. If this attribute does not appear, ColdFusion attempts to use all submitted form fields. • username—Supplies the username for logging in to a passwordprotected database. The value of this attribute overrides any username set up in the Data Sources section of the ColdFusion Administrator. • password—Supplies the password for logging in to a passwordprotected database. The value of this attribute overrides any password set up in the Data Sources section of the ColdFusion Administrator. Example:
Overview: redirects the user to another page. The redirect page can be
one on your server or one from another server. You may optionally ask ColdFusion to append CFID and CFTOKEN data to the redirect URL. Syntax:
Attributes: • url—Specifies the URL of the page to which the browser is redirected. • addtoken—Appends a query string to the redirect URL that includes client variable tracking information (CFID and CFTOKEN) when client management is enabled and addtoken is set to “yes”. Example:
Appendix A
541
CAUTION Don’t use on a page where you also use . The redirect will take precedence, and the cookie won’t be written. If you need to place a cookie and a redirect in the same script, try using the tag for the redirect instead.
Overview: locks a shared resource to prevent corruption of data stored in the
resource. The following are commonly locked in the ColdFusion environment: • Variables in the Application, Session, and Server scopes • Verity collections (, tags) • Files ( tag) • CFX tags and other objects Syntax: ... code to be locked ...
or ... code to be locked ...
Attributes: • type—Specifies the type of lock you want to use. “exclusive” locks are typically used for operations that modify the locked resource, and “readonly” locks are used when reading from the resource but not changing it. • scope—Indicates which variable scope you want to lock. Possible values are “application”, “session”, and “server”. • name—Provides a name for the lock. You should not use the name attribute when you’re locking one of the three variable scopes handled by the scope attribute. Use name for locking files, Verity collections, and other resources that are not shared variable scopes. • timeout—Specifies how long to wait for a lock.
542
Appendix A
Examples: To lock the session scope when creating a new session variable:
To lock the session scope when reading a session variable’s value: #Session.loginName#
To lock a file when appending data to it:
Overview: lets you create your own text-based log files. Whenever you need to make an entry in the log file, the tag can handle that task for you.
Syntax:
Attributes: • text—Provides the text of the message to be written to the log file. • log—Writes to application.log or scheduler.log, respectively, if set to “application” or “scheduler”. If you’re not writing to one of these logs, use the file attribute to indicate the log file you want to write to. • file—Supplies the name of the log file in which you want to make an entry. If the log filename is database.log, you would set file=”database”. The “.log” part is understood because ColdFusion requires that all log filenames end in .log. • type—Indicates the severity of the log entry. Possible values are “Information”, “Warning”, “Error”, and “Fatal Information”. • thread—Specifies whether you want the thread ID included in the log entry. • date—Specifies whether you want the date included in the log entry.
Appendix A
543
• time—Specifies whether you want the time included in the log entry. • application—Specifies whether you want the application’s name (from the tag) included in the log entry. Example: No records found!
Overview: iteratively processes a block of code. ColdFusion can implement
the standard “for” and “while” loops available in most programming languages, in addition to some other types of loops specific to ColdFusion. The code that is executed iteratively—called the body of the loop—can be made up of HTML, CFML, or a combination of the two. Syntax: ... code to be executed iteratively ...
or ... code to be executed iteratively ...
or ... code to be executed iteratively ...
or ... code to be executed iteratively ...
or ... code to be executed iteratively ...
544
Appendix A
Attributes: The first class of loop you see in the preceding syntax is called an index loop. It is analogous to “for” loops used in other languages. A ColdFusion index loop takes the following attributes: • from—Supplies the initial value of the loop index variable. • to—Supplies the final value of the loop index variable. • index—Names a variable used to hold the value of the loop counter. The index variable is initially equal to the value in the from attribute, and the loop terminates when the index variable is equal to the value of the to attribute. • step—Indicates by how much the index variable should increase (positive values) or decrease (negative values) after each iteration of the loop. The default value is 1. The second loop in the syntax list is called a conditional loop. ColdFusion conditional loops are equivalent to while loops supported by other languages. The loop takes only the condition attribute, which is set equal to some Boolean expression. The loop continues to iterate as long as the associated Boolean expression has a value of TRUE. CAUTION When you’re setting up a conditional loop, make sure that your condition will eventually take on a value of FALSE. Otherwise, you will have an infinite loop, which may put your server at risk.
The third type of loop enables ColdFusion to execute the body of the loop once for each item in a list. Looping over a list requires the use of two attributes: • list—Supplies the list to loop over. • index—Provides the name of an index variable. The index variable takes on the values of the list items one at a time as ColdFusion works its way through the list. The fourth kind of loop in the preceding syntax list allows ColdFusion to execute the body of the loop once for each record returned in the query. Looping over a query object requires you to provide only the name of the query object in the query attribute. NOTE If you loop over a query object that contains no records, the body of the loop will be executed zero times.
Appendix A
545
The final class of loop you see here loops over a ColdFusion structure or a COM object. This kind of loop requires two attributes: • collection—Specifies the structure or COM object to loop over. • item—Provides a name by which you can reference each name/value pairing in the structure or COM object. Examples: To create a for loop: #monthArray[i]#
To create a while loop: #x#
To loop over a list: I enjoy #musicType# music.
To loop over a query: SELECT productName, productPrice FROM products ORDER BY productPrice DESC #productName# costs #DollarFormat(productPrice)#.
To loop over a structure: Here’s what’s in your session object:
546
Appendix A
#i# has the value #session[i]#
Overview: generates an e-mail message and sends it out by means of an
SMTP server configured to work with ColdFusion. Syntax: ... body of message ...
Attributes: • to—Specifies a comma-delimited list of primary recipient addresses. • from—Provides a from address for the message. Replies to the message will go to the from address. • subject—Provides a short description of the subject of the message. • cc—Specifies a comma-delimited list of carbon copy recipient addresses. • bcc—Specifies a comma-delimited list of blind carbon copy recipient addresses. • type—Sends messages formatted with HTML code when type is set to “HTML”. • server—Specifies the domain name service (DNS) name or IP address of the SMTP server to use to send out the message. If no server is specified, ColdFusion uses the one configured on the Mail Server page of the ColdFusion Administrator. • port—Specifies the TCP/IP port for the nominated server. SMTP traffic is normally handled on port 25. This is the default setting in the ColdFusion Administrator, so it’s very likely that you’ll never need to set this attribute.
Appendix A
547
• mimeattach—Specifies the location of a file to attach to the message. You can attach only a single file when using the mimeattach attribute. If you have multiple files to attach to a message, use the tag instead. • mailerID—Indicates the name of the mailer application. The default value is “ColdFusion Application Server”. • query—Specifies the name of a query object containing data to be used to generate the mail messages. ColdFusion will generate one e-mail message for each record in the query object. • maxrows—Puts a limit on the number of messages generated when using the query attribute. • group—Indicates the name of the query column by which data should be grouped. • groupcasesensitive—Specifies whether grouping values should be case sensitive. The default value is “yes”. Examples: To send a message based on form data: #Form.messageBody#
To send mail to a specific department in a company: SELECT firstName, salary, emailAddress FROM employees WHERE department = ‘Accounting’ Dear #firstName#: In order to cut costs, we are forced to reduce your salary to #DollarFormat(Evaluate(salary * 0.75))#. This represents a 25% decrease in your pay. As a fellow bean counter, I know you appreciate the need for cutting expenses. Thank you in advance for your support of this program.
548
Appendix A
Sincerely, Accounting Management
Overview: specifies a file to attach to an outgoing e-mail message or
adds a custom SMTP header to the outgoing message. The two uses are not mutually exclusive; you just need to use a separate tag for each purpose. has be to used inside a tag. Attempting to use a tag when not in the context of a tag will result in
an error. Syntax: ... body of the message ...
Attributes: • file—Specifies the complete path to the file you want to attach to the mail message. • name—Indicates the name of the SMTP mail header you want to apply. Must be used in conjunction with the value attribute. • value—Provides a value for the SMTP mail header. Must be used in conjunction with the name attribute. Example: Dear Sir or Madam: I am interested in the ColdFusion Developer position you advertised on your Web site. Attached please find a copy of my resume in Microsoft Word format. Thank you for your consideration.
Appendix A
549
Overview: incorporates a value in ColdFusion’s memory into the Web page that ColdFusion is building. The name of the quantity in memory must be inside the tag and must also be enclosed in # signs.
Syntax: ... output block ...
Attributes: • query—Specifies a query to use to generate output. One output block will be generated for each record returned in the query. • startrow—Indicates which record in the query should be output first. The default value is 1. • maxrows—Limits the number of database records processed when outputting data from a query. • group—Specifies a database field by which the query data should be grouped in the output. • groupcasesensitive—Specifies whether the output grouping should be case sensitive. The default value is “yes”. Examples: To output data stored in variables or derived from function calls: Hello, #name#!
Today is #DateFormat(Now(),”mmmm d, yyyy”)#.
To output grouped data from a query: SELECT pubTitle, pubType FROM publications ORDER BY pubType, pubTitle
Please choose the publications you would like from the list below.
Overview: establishes a default value for a parameter in the event that the
value cannot be derived elsewhere. This capability can be useful, for example, when you’re processing a radio button field on an HTML form. If no radio button from the set is chosen, no name and value are passed to the server for that set. In this case, can provide a default value for the form field so that ColdFusion doesn’t throw an error telling you that the form field is undefined. Syntax:
Attributes: • name—Specifies the name of the parameter for which you want to set the default value. • default—Provides a default value for the named parameter. • type—Indicates the data type you want to test for. If the named variable does not have the specified data type, ColdFusion produces an error message.
Appendix A
551
Examples: To set a default value:
To test a variable’s data type:
Overview: retrieves e-mail messages from a POP3 server. Depending on the value of its action attribute, will retrieve just the mail headers or
entire mail messages, or it will delete a specific message. Syntax:
or
or
Attributes: • action—Indicates which POP3 action you want to take. Possible values include “GetHeaderOnly”, “GetAll”, and “Delete”. • name—Provides a name for the query object that holds the downloaded mail information. • server—Supplies the domain name service (DNS) name or IP address of the POP3 server. • username—Provides the username for the mailbox you’re logging in to. • password—Provides the password for the mailbox you’re logging in to. • messagenumber—Indicates which message you want to download or delete.
552
Appendix A
• attachmentpath—Specifies where to store downloaded attachment files when action is set to “GetAll”. If no attachment path is given, attachments are not downloaded. • generateuniquefilenames—Specifies whether you want ColdFusion to generate unique names for the attachment files it downloads. The default value is “no”. Examples: To download the mail headers:
To download an entire message:
To delete a message:
Overview: passes Structured Query Language (SQL) commands to databases. The SQL command is located between and . The tag’s attributes determine which database you want to com-
municate with and how that communication occurs. Syntax:
Attributes: • datasource—Names the data source to which the SQL command will be passed. The datasource attribute is not necessary if dbtype is set to “dynamic” or “query”.
Appendix A
553
• name—Provides a name for the query object that holds the query results. • dbtype—Specifies the type of database driver in use. The default value is “ODBC”. You can set this attribute to “dynamic”, in which case you need to provide connection information through the connectstring attribute, or “query”, which allows you to query the results in an existing query object. • dbserver—Provides the name of the computer that acts as the database server, if needed. • dbname—Provides the name of the database you’re querying. • connectstring—Supplies details about how to connect to the database when dbtype is set to dynamic. • username—Provides the username for logging in to a passwordprotected database. • password—Provides the password for logging in to a passwordprotected database. • maxrows—Limits the number of rows that can be returned. • blockfactor—Determines how many rows are retrieved from the database at a time. Possible values range from the default of 1 to a maximum of 100. • cachedafter—Provides a date after which query data is taken from the cache instead of being re-retrieved from the database. • cachedwithin—Provides a span of time over which to cache the results of the query. The value is specified with the CreateTimeSpan() function. • timeout—Specifies the number of milliseconds to wait before throwing a timeout error. • debug—Appends the SQL command and number of records returned to the bottom of the finished HTML page, if present. Example: SELECT * FROM Customers WHERE State = ‘CA’ ORDER BY City
554
Appendix A
Overview: conducts a search against one or more Verity collections and returns the search results in a query object.
Syntax:
Attributes: • name—Supplies a name for the query object that holds the search results. • collection—Specifies a Verity collection or comma-delimited list of Verity collections to search. • type—Prompts Verity to use its STEM, ANY, and wildcard operators, if set to “simple”. If set to “explicit”, all Verity operators need to be explicitly named to be used. The default value is “simple”. • criteria—Specifies a keyword or comma-delimited list of keywords to search for. If the keyword data is all uppercase or all lowercase, the search is not considered case sensitive. Otherwise, searches are case sensitive. • maxrows—Limits the number of results returned by the search. • startrow—Indicates which result should be the first to be printed when outputting results. The default value is 1. • external—Specifies whether the collections to be searched are external (not created through the Verity Collections page on the ColdFusion Administrator). All the collections you name in the collection attribute need to be external if this attribute is set to “yes”. • language—Specifies a language filter to use for the search. Example:
Appendix A
555
Overview: is used inside a tag to generate a select list that is rigged with JavaScript. You can optionally use to dynamically generate the tags that make up the list.
Syntax: Option 1 Option 2 Option 3
or
Attributes: • name—Provides a unique name for the select list. • size—Specifies the number of options to display in the list at any given time. If size is set to “1” and multiple to “no”, you’ll have a drop-down list. Otherwise, you’ll have a scrolling list. • multiple—Specifies whether the user should be able to select multiple items from the list. • required—Incorporates JavaScript into the resulting HTML page that checks to see whether the user made a choice from the list if set to “yes”. • message—Provides corrective feedback to the user in the event that no choice was made. • query—Names the query containing the data to be used to dynamically generate the tags of the list. • display—Names the database field whose value should be displayed to the user in each option. • value—Names the database field whose value should be set as the value attribute of each tag.
556
Appendix A
• selected—Specifies the value in the select list that should be preselected, if any. Examples: To make the select list required: ColdFusion JavaScript XML
To dynamically generate the options in a select list: SELECT stateName, stateAbbreviation FROM states ORDER BY stateName
Overview: establishes the value of a variable. Each variable must have a
name and a value, and both are specified in the tag. Syntax:
Attributes: None. Example:
Appendix A
557
Overview: , together with its related tags and , provide another way to implement conditional logic by establishing blocks of code to be processed for each possible value of an expression.
Syntax: ... code to process for value1 ... ... code to process for value2 or value3 ... ... code to process for value4 ... ... ... code to process if none of the cases above apply ...
Attributes: The tag takes the expression attribute, which is set equal to the expression you want to evaluate. The tag takes the value attribute, which is set to a comma-delimited list of the possible expression values to associate with the case’s block of code. The tag does not take any attributes. Example:
Ugh! Another work day!
Hooray! It’s the weekend!
TGIF!
558
Appendix A
Overview: updates a record in a database based on data submitted through an HTML form. The names of the form fields and the database fields must match exactly for to work properly.
Syntax:
Attributes: • datasource—Indicates the name of the data source where the record to be updated resides. This attribute is required unless dbtype is set to “dynamic”. In that case, the data source is determined by examining the connectstring attribute. • dbtype—Specifies the database driver type (ODBC, OLE DB, and so on). dbtype can be set to “dynamic” if you want to specify the connection string yourself. • connectstring—Provides a connection string for initiating contact with an ODBC data source. • tablename—Specifies the name of the table where the record to be updated resides. • tableowner—If the target database supports the concept of table ownership, you can use this attribute to provide the name of the owner. • tablequalifier—The need for table qualifiers varies from one database to another. For example, the qualifier for an SQL Server database table is the name of the database itself. If you need to provide a qualifier, you can use this attribute to supply the qualifier value. • formfields—Provides a comma-delimited list of form fields whose values should be used in the update. If this attribute does not appear, ColdFusion attempts to use all submitted form fields. • username—Supplies the username for logging in to a passwordprotected database. The value of this attribute overrides any username set up in the Data Sources section of the ColdFusion Administrator.
Appendix A
559
• password—Supplies the password for logging in to a passwordprotected database. The value of this attribute overrides any password set up in the Data Sources section of the ColdFusion Administrator. Example:
CAUTION The primary key value of the record to be updated must be part of the submitted form. Otherwise, ColdFusion won’t know which record to update. The primary key value is usually embedded in the form as a hidden field.
Appendix B ColdFusion Markup Language Functions How This Reference Is Organized This appendix contains examples showing how to use each ColdFusion Markup Language (CFML) function discussed in the book. Because there are more than 200 CFML functions, the functions have been grouped together under the following classes: • String functions • List functions • Array functions • Structure functions • Mathematical functions • Date/Time functions • Formatting functions • Decision functions Note that although the appendix does cover a large number of functions, it is not comprehensive. For a complete listing of CFML functions, consult your ColdFusion documentation.
String Functions CFML comes with a wealth of functions that make string manipulation simple. In fact, CFML string functions comprise one of the largest classes of CFML functions. The following list summarizes some of the more commonly used string functions:
562
Appendix B
• Asc(string)—Returns the ASCII numeric value of the first character of string. For example: The ASCII value of “a” is #Asc(“a”)#.
• Chr(value)—Returns the character with the ASCII value equal to value. value must therefore be an integer between 0 and 255. The following example shows how to use the Chr() function to generate a carriage return-line feed character:
564
Appendix B
• Mid(string,start,num_chars)—Extracts num_chars characters from string, starting at position start. The output from the following example would be 555: The middle part of your phone number is Mid(phoneNumber,4,3)#
• Replace(string1,string2,string3,scope)—Replaces occurrences of string2 in string1 with string3. scope controls how many replacements should be made (“one” or “all”). For example:
• Trim(string)—Removes all whitespace characters from either end of string. For example:
• StructCount(structure)—Returns the number of keys in the specified structure. In the following example, the output of the function would be 5: There are #StructCount(strColors)# key-value pairs in strColors.
Appendix B
571
• StructDelete(structure,key)—Removes a key-value pair from the specified structure. To remove the key sky and its associated value blue, you would use the following command:
• StructFind(structure,key)—Returns the value associated with the specified key. In the following example, the output would be green: #StructFind(strColors,”grass”)#
• StructInsert(structure,key,value)—Adds the specified key-value pair to a structure. StructInsert() was used at the start of this section to initialize the structure used throughout these examples:
• StructIsEmpty(structure)—Returns TRUE if the specified structure has no key-value pairs or FALSE if the structure has at least one key-value pair. The output from the following code would be NO, the string representation of the Boolean value FALSE: #StructIsEmpty(strColors)#
• StructKeyArray(structure)—Returns an array of all keys in the specified structure. For example:
• StructKeyExists(structure,key)—Returns TRUE if the specified key is in the structure and FALSE if it is not. The output from the following code would be YES, the string representation of the Boolean value TRUE: #StructKeyExists(strColors,”stop sign”)#
• StructKeyList(structure,delimiter)—Returns a delimited list of the keys in the specified structure. A comma is used as the delimiter if none is specified. For example:
• StructNew()—Initializes a new structure. The structure is initially empty. StructNew() was used at the start of this section to create the strColors structure:
572
Appendix B
• StructUpdate(structure,key,new_value)—Assigns a new value to a key in the specified structure. Because not all grapes are purple, you could arguably make the following update to the strColors structure:
Mathematical Functions You may not need to do much mathematical computation as part of your ColdFusion applications, but CFML includes a large library of math functions for you to use when the need arises. Some of them include the following: • Abs(number)—Returns the absolute value of number. The output from the following example would be 7: #Abs(-7)#
• Ceiling(number)—Returns the closest integer bigger than number. The following example would output the value 3: #Ceiling(2.01)#
• DecrementValue(number)—Subtracts one from the value of number. In the following example, the function would return 9: #DecrementValue(10)#
• IncrementValue(number)—Adds one to the value of number. The following code would return the value 11: #IncrementValue(10)#
• Int(number)—Returns the closest integer smaller than number. The following example would print the value 5: #Int(5.89)#
• Log(number)—Returns the natural logarithm (base e where e is approximately 2.718) of number. The following code would return a value of approximately 4.605: #Log(100)#
• Log10(number)—Returns the base-10 logarithm of number. The following code would return a value of 2: #Log10(100)#
• Max(number1,number2)—Returns the larger of number1 and number2. The following example would return the value 5: #Max(-3,5)#
Appendix B
573
• Min(number1,number2)—Returns the smaller of number1 and number2. The following example would return the value -3: #Min(-3,5)#
• pi()—Returns the value of the constant pi, 3.14159265358979. pi represents the ratio of the circumference of a circle to its diameter. For example:
• Rand()—Returns a random number between 0 and 1. For best results, use Rand() only after you have seeded the random number generator with Randomize(). For example:
• Randomize(seed)—Activates ColdFusion’s random number generation algorithm with the starter value seed. Returns TRUE if successful. Many developers use a value from the system clock to seed the random number generator as shown in the following example:
• RandRange(number1,number2)—Returns a random number between number1 and number2. For best results, use RandRange() only after you have seeded the random number generator with Randomize(). For example:
• Round(number)—Rounds number to the closest integer. The following code would output the value 9: #Round(9.49)#
• Sgn(number)—Returns -1 if number is negative, 0 if number is zero, and 1 if number is positive. The output from the following example would be -1: #Sgn(-4)#
• Sqr(number)—Returns the positive square root of number, where number is positive or zero. In the following example, the output would be 3: #Sqr(9)#
TIP To get the other square root of a number, multiply the positive square root by -1.
574
Appendix B
Date/Time Functions Handling date and time variables can be somewhat tricky, especially when you’re doing SQL calls, in which case they have to be in a format that ODBC can interpret correctly. CFML supports a number of functions that operate on date and time variables. The following list provides a sampling of these functions. If you specify a year quantity less than 100, it is interpreted as a twentieth century value. • CreateDateTime(year,month,day,hour,minute,second)—Creates a date/time variable with the value corresponding to the year, month, day, hour, minute, and second information provided. For example, to specify 12 noon on July 4, you would write
• CreateODBCDateTime(year,month,day,hour,minute,second)—Creates a date/time variable in ODBC format with the value corresponding to the year, month, day, hour, minute, and second information provided. You should use ODBC-formatted dates in your SQL statements. The ODBC-formatted output from the following code would be {ts 200207-04 12:00:00}: #independenceDay#
• DateCompare(datetime1,datetime2)—Compares datetime1 and datetime2 and returns -1 if datetime1 occurs before datetime2, 0 if datetime1 equals datetime2, and 1 if datetime1 occurs after datetime2. The output from the following code would be -1: #DateCompare(christmas,newYearsDay)>#
• Day(date)—Returns the day of the month (1–31) on which that date falls. For example: The current day of the month is #Day(Now())#.
• Hour(date)—Returns the hour (0–23) specified by date. For example: The current hour on the system clock is #Hour(Now())#.
• IsDate(“date”)—Returns TRUE if date is a valid date/time variable or FALSE if date is not. The following sample code would print a value of YES, the string equivalent of a Boolean value of TRUE: #IsDate(“September 29, 2002”)#
Appendix B
575
• IsLeapYear(year)—Returns TRUE if year is a leap year or FALSE if year is not. The following sample code would print a value of NO, the string equivalent of a Boolean value of FALSE: #IsLeapYear(2002)#
• Minute(date)—Returns the value of the minutes (0–59) specification in the variable date. For example: The current number of minutes on the system clock is #Minute(Now())#.
• Month(date)—Returns the numeric value of the month (1–12) in the variable date. For example: The current month is #Month(Now())#.
• Now()—Returns the current system date and time in ODBC format. For example: The current date and time is #Now()#.
TIP The Now() function makes it easy for you to time stamp database fields such as DateEntered or LastUpdated.
• ParseDateTime(string)—Converts the string string to a valid date/time variable in ODBC format. For example: Your birthday in ODBC format is #ParseDateTime(Form.birthday)#.
• Second(date)—Returns the value of the seconds (0–59) specification in the variable date. For example: The number of seconds on the system clock is #Second(Now())#.
• Week(date)—Returns the numerical week of the year (1–53) during which date occurs. For example: Christmas occurs during week number #Week(“December 25, 2002”)#.
• Year(date)—Returns the value of the year specification in the variable date. For example: The current year on the system clock is #Year(Now())#.
Formatting Functions ColdFusion can do some of the preparatory work that must be completed before displaying a value. The following are some of the more popular CFML formatting functions:
576
Appendix B
• DateFormat(date,mask)—Formats date according to the specified mask. A mask of “mm/dd/yy”, for example, would yield a date in the form 11/30/02. For example: #DateFormat(Now(),”mm/dd/yy”)#
• DollarFormat(number)—Returns number formatted as a dollar amount with a dollar sign, decimal point, and commas where necessary. For example: The price for this item is #DollarFormat(price)#.
• HTMLEditFormat(HTMLcode)—Removes reserved characters within the string HTMLcode and replaces them with their escaped values. The less than sign (
