User Guide

Manuals Brands Macromedia Manuals Other COLDFUSION 5-DEVELOPING APPLICATIONS

Macromedia® Incorporated

Developing

ColdFusion

Applications

MacroMedia ColdFusion

Summary of content (438 pages)

PAGE 1

Developing ColdFusion Applications MacroMedia ColdFusion® 5 Macromedia® Incorporated
PAGE 2

Copyright Notice © 1999–2001 Macromedia Incorporated. All rights reserved. This book, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Macromedia, Incorporated.
PAGE 3

Contents About This Book ............................... xv Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi Developer Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii About ColdFusion Documentation . . . . . . . . . . . . . . . .
PAGE 4

iv Contents Working with Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 About variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Adding more variables to the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Development Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Chapter 3 Querying a Database ....
PAGE 5

v Using HTML tables to display query results . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting individual data items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing pattern matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filtering data based on multiple conditions . . . . . . . . . . . . . . . . . . . . . . . . . . Creating table joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 6

vi Contents Data entry form notes and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Creating an action page to insert data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Updating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Creating an update form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Creating an action page to update data . . . . . . . . .
PAGE 7

vii Input Validation with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Handling failed validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Example: validating an e-mail address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Building Tree Controls with cftree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Grouping output from a query . . . . . . . . . . . . . . . . . . .
PAGE 8

viii Contents Where is data accessible? High-level data exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Executing Custom Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tag instance data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modes of execution . . . . . . . . . .
PAGE 9

ix Client, Session, Application, and Server scope variables . . . . . . . . . . . . . . 214 Custom error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Web server security integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Mapping an Application Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Processing Application.cfm and OnRequestEnd.cfm . . . . . . . . . . . . . . . . .
PAGE 10

x Contents Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 11

xi Using Query Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Simple query expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Explicit query expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Composing search expressions . . . . . . . . . . . . . . . . .
PAGE 12

xii Contents Evaluating the Results of a File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Moving, Renaming, Copying, and Deleting Server Files . . . . . . . . . . . . . . . . . . . . 326 Reading, Writing, and Appending to a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Reading a text file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Writing a text file . . . . . . . . . . . . . . . . . . . . . .
PAGE 13

xiii Authenticating users in Application.cfm . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Checking for authentication and authorization . . . . . . . . . . . . . . . . . . . . . 365 Chapter 20 Using cfobject to Invoke Component Objects 367 . Component Object Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About CORBA . . . . . .
PAGE 14

xiv Contents ZipBrowser Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Approaches to Debugging Java CFXs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Outputting debug information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Using the debugging classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Developing CFX Tags in C++. . . . . . . . . . . .
PAGE 15

About This Book Developing ColdFusion Applications describes the process of developing Web applications using ColdFusion. In the first eight chapters, you can follow the instructions presented to learn how to create basic ColdFusion applications. Then, chapters nine through 19 cover various topics of interest in enhancing your applications. Finally, chapters 20 through 23 explain how to extend ColdFusion’s capabilities.
PAGE 16

xvi About This Book Intended Audience Developing ColdFusion Applications is intended for Web application programmers who are learning ColdFusion orwish to extended their ColdFusion programming knowledge. It provides a solid grouding in the tools that ColdFusion provides to develop Web applications. The initial chapters provide e instructions for creating a basic ColdFusion application and are intended for those who are new to ColdFusion.
PAGE 17

Developer Resources xvii Benefit Feature Description Enhanced performance Core engine tuning Take advantage of dramatically improved server performance and reduced memory usage to deliver faster, more scalable applications. Incremental page delivery Improve response time by delivering page output to users as it is built. Wire protocol database drivers Deliver high-performance ODBC connectivity using new drivers.
PAGE 18

xviii About This Book designed to give you quick access to the entire range of online resources, as the following table describes. Resource Description URL Macromedia Web General information about Macromedia www.macromedia.com/ site products and services Information on ColdFusion Detailed product information on ColdFusion and related topics www.coldfusion.com/products/coldfusion/ Technical Support Professional support programs that Macromedia offers. www.coldfusion.
PAGE 19

About ColdFusion Documentation xix Printed and online documentation set The ColdFusion documentation set consists of the following titles.
PAGE 20

xx About This Book Getting Answers One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion developer communities on the ColdFusion Forums. Other developers on the forum can help you figure out how to do just about anything with ColdFusion. The search facility can also help you search messages from the previous 12 months, allowing you to learn how others have solved a problem that you might be facing.
PAGE 21

Chapter 1 Introduction to ColdFusion This chapter explains the difference between creating static Web pages with HTML and creating dynamic applications with ColdFusion. It also describes what ColdFusion is and how it works. Contents • A Quick Web Overview................................................................................................ 2 • Before You Begin ......................................................................................................... 3 • What is ColdFusion?.......
PAGE 22

2 Chapter 1 Introduction to ColdFusion A Quick Web Overview Over the last few years, the Web changed from being simply a collection of static HTML pages to an application development platform. Rather than offering a space where organizations can merely advertise goods and services, similar to traditional yellow pages directories, companies conduct business ranging from e-commerce to managing internal business processes.
PAGE 23

Before You Begin 3 Before You Begin Before you begin using ColdFusion to create your Web applications, you should be familiar with HTML, relational database design and management, and Structured Query Language (SQL). HTML You will find that ColdFusion tags (CFML) are similar in syntax to HTML tags, yet, unlike HTML, they enable you to create dynamic Web pages. You should understand how to create a basic HTML page, put information into tables, gather data in forms, and create links.
PAGE 24

4 Chapter 1 Introduction to ColdFusion What is ColdFusion? ColdFusion lets you create page-based Web applications using ColdFusion Markup Language (CFML), the tag-based language you use to create server-side scripts that dynamically control data integration; application logic; and user interface generation. ColdFusion Web applications can contain XML, HTML, and other client technologies such as CSS and JavaScript.
PAGE 25

ColdFusion Features and Components 5 ColdFusion Features and Components ColdFusion provides a comprehensive set of features and components for developing and managing your Web applications. Using the ColdFusion components, you can enhance the speed and ease of development, dynamically deploy your applications, integrate new and legacy technologies, and build secure applications.
PAGE 26

6 Chapter 1 Introduction to ColdFusion Benefits Features Open integration • Database connectivity using native database drivers (Enterprise Edition only), ODBC, or OLE DB • Embedded support for full-text indexing and searching • Standards-based integration with directory, mail, HTTP, FTP, and file servers • Connectivity to distributed object technologies, including CORBA (Enterprise Edition only), COM (Windows Enterprise Edition only), Java objects and EJBs • Open extensibility with C/C++ and Java Secur
PAGE 27

ColdFusion Features and Components 7 data input and format data output. They can contain ColdFusion (CFML) tags, HTML tags, CFScript, JavaScript, and anything else that you can normally embed in an ordinary HTML page. You can easily access data sources, such as relational databases, from your application pages. The default file extension used for ColdFusion application pages is cfm.
PAGE 28

8 Chapter 1 Introduction to ColdFusion How ColdFusion Server Works Regardless of which ColdFusion Server you have installed, ColdFusion application pages are processed on the server at runtime, each time they are requested by a browser. A page request happens when you click a Web site link to open a Web page in your browser.
PAGE 29

Chapter 2 Writing Your First ColdFusion Application This chapter guides you through the ColdFusion development process as you create a ColdFusion application page, save it, and view it in a browser. Contents • The Development Process........................................................................................ 10 • Working with ColdFusion Application Pages.......................................................... 10 • Working with Variables ......................................................
PAGE 30

10 Chapter 2 Writing Your First ColdFusion Application The Development Process Whether you are creating a static HTML page or a ColdFusion application page, you follow the same iterative process: 1 Write some code. 2 Save the code to a document or page. 3 View the page in a browser. 4 Modify the page. 5 Save the page again. 6 View it in a browser.
PAGE 31

Working with ColdFusion Application Pages 11 I’d like to talk to someone in #Department#. Saving application pages Instead of saving pages with an htm or html file extension, you save ColdFusion application pages with a cfm or cfml extension. By default, the Web server knows to pass a page that contains a cfm extension to the ColdFusion Server when it is requested by a browser.
PAGE 32

12 Chapter 2 Writing Your First ColdFusion Application Compare the code that was returned to the browser with what you originally created. Notice that the ColdFusion comments and CFML tags are processed, but do not appear in the HTML file that is returned to the browser.
PAGE 33

Working with Variables 13 Working with Variables A Web application page is different from a static Web page because it can publish data dynamically. This involves creating, manipulating, and outputting variables. A variable stores data that you can use in applications. As with other programming languages, you set variables in ColdFusion to store data that you want to access later. You reference a range of variables to perform different types of application processing.
PAGE 34

14 Chapter 2 Writing Your First ColdFusion Application you can write: I’d like to talk to someone in #Variables.Department#. Some variable scopes, such as the local scope, do not require the scope identifier prefix, while others do. However, it is good programming practice to use prefixes for most or all scopes. This helps to better identify each variable’s use and can prevent multiple uses of the same name. This book uses the scope prefix for all variables except for local variables.
PAGE 35

Working with Variables 15 CFML code Results I’d like to talk to someone in #Department#. ColdFusion replaces the variable Department with its value. The HTML page displays: I’d like to talk to someone in Sales. The department name spelled backward is Reverse(Department). ColdFusion sees Reverse(Department) as text and displays it unchanged. The HTML page displays: The department name spelled backward is Reverse(Department).
PAGE 36

16 Chapter 2 Writing Your First ColdFusion Application 4 View the page in your Web browser by entering the following URL: http://127.0.0.1/myapps/calldept.cfm. Development Considerations The same development rules that apply for any programming environment apply to ColdFusion. You should also follow the same programming conventions that you would with any other language: • Comment your code as you go.
PAGE 37

Chapter 3 Querying a Database This chapter describes how to retrieve data from a database, work with query data, and enable debugging in ColdFusion applications. You will learn how to use the ColdFusion Administrator to set up a data source and enable debugging, use the cfquery tag to query a data source, and use the cfoutput tag to output the query results to a Web page. Contents • Publishing Dynamic Data.........................................................................................
PAGE 38

18 Chapter 3 Querying a Database Publishing Dynamic Data A Web application page is different from a static Web page because it can publish data dynamically. This can involve querying databases, connecting to LDAP or mail servers, and leveraging COM, DCOM, CORBA, or Java objects to retrieve, update, insert, and delete data at runtime—as your users interact with pages in their browsers.
PAGE 39

Understanding Database Basics 19 Understanding Database Basics You do not need a thorough knowledge of databases to develop a data-driven ColdFusion application, but you need to know some basic concepts and techniques. A database is a structure for storing information. Databases are organized in tables, which are collections of related items. For example, a table might contain the names, street addresses, and phone numbers of individuals. Think of a table as a grid of columns and rows.
PAGE 40

20 Chapter 3 Querying a Database Database design guidelines From this basic description, a few database design rules emerge: • Each record should contain a unique identifier, known as the primary key. This can be an employee ID, a part number, or a customer number. The primary key is typically the column used to maintain each record’s unique identity among the tables in a relational database.
PAGE 41

Accessing Data Sources • • • • • • • • • 21 Borland dBase-compliant databases Microsoft Excel worksheet data ranges Borland Paradox Databases Informix databases Progress databases Oracle 8 databases Centura SQLBase databases Sybase ASE databases Delimited text files You can also use any additional ODBC drivers that are installed on your system. On UNIX, look in the ODBC page of the ColdFusion Administrator for a list of available ODBC drivers.
PAGE 42

22 Chapter 3 Querying a Database Adding data sources You use the ColdFusion Administrator to add data sources to the ColdFusion Administrator. When you add a data source, you assign it a name so that you can reference it within tags such as cfquery on application pages to query databases. During a query, the data source tells ColdFusion which database to connect to and what parameters to use for the connection.
PAGE 43

Accessing Data Sources 23 4 Name the data source CompanyInfo. 5 On Windows Select Microsoft Access Driver (*.mdb) from the drop-down box to describe the ODBC driver. On UNIX, select the Merant Dbase/FoxPro driver. 6 Click Add. 7 In the Database File field, enter the full path of the database. (You can also use the Browse button to locate the file.). On Windows specify the path to the company.mdb file, typically C:\CFusion\database\Company.mdb.
PAGE 44

24 Chapter 3 Querying a Database Adding data source notes and considerations When adding data sources to ColdFusion Server, keep these guidelines in mind: • Data source names should be all one word and begin with a letter. • Data source names can contain only letters, numbers, and the underscore. • Data source names should not contain special characters. • Although data source names are not case-sensitive, you should use a consistent capitalization scheme.
PAGE 45

Retrieving Data 25 Retrieving Data You can query databases to retrieve data at runtime. The retrieved data, called the result set, is stored on that page as a query object. When retrieving data from a database, perform the following tasks: • Use the cfquery tag on a page to tell ColdFusion how to connect to a database. • Write SQL commands inside the cfquery block to specify the data that you want to retrieve from the database.
PAGE 46

26 Chapter 3 Querying a Database • When referencing text literals in SQL, use single quotes (’). For example, Select * from mytable WHERE FirstName=’Russ’ selects every record from mytable in which the first name is Russ. Writing SQL In between the begin and end cfquery tags, write the SQL that you want the database to execute. For example, to retrieve data from a database: • Write a SELECT statement that lists the fields or columns that you want to select for the query.
PAGE 47

Writing SQL 27 Statement clauses Use the following keywords to refine SQL statements: Keyword Description FROM Names the data tables for the operation WHERE Sets one or more conditions for the operation ORDER BY Sorts the result set in the specified order GROUP BY Groups the result set by the specified select list items Operators The following basic operators specify conditions and perform logical and numeric functions: Operator Description AND Both conditions must be met OR At least one co
PAGE 48

28 Chapter 3 Querying a Database • Some DBMS vendors use nonstandard SQL syntax (known as a dialect) in their products. ColdFusion does not validate the SQL in a cfquery, so you are free to use any syntax that is supported by your data source. Check your DBMS documentation for nonstandard SQL usage. Building Queries As discussed earlier in this chapter, you build queries using the cfquery tag and SQL. To query the table: 1 Create a new application page in ColdFusion Studio.
PAGE 49

Building Queries 29 Reviewing the code The query you just created retrieves data from the CompanyInfo database.
PAGE 50

30 Chapter 3 Querying a Database Outputting Query Data After you define a query on a page, you can use the cfoutput tag with the query attribute to specify the query object that contains the data you want to output to a page. When you use the query attribute: • ColdFusion loops over all the code contained within the cfoutput block, once for each row returned from a database. • You must reference specific column names within the cfoutput block to output the data to the page.
PAGE 51

Outputting Query Data 31 You now display the results of the query on the page. The following table describes the code and its function: Code Description Display information retrieved in the EmpList query. Display information for each record in the query, until you run out of records. #FirstName#, #LastName#, #Salary#, #Contract# Display the value of the FirstName, LastName, Salary, Contract fields of each record, separated by commas and spaces.
PAGE 52

32 Chapter 3 Querying a Database Getting Information About Query Results Each time you query a database with the cfquery tag, you get not only the data itself, but also query properties, as described in the following table: Property Description RecordCount The total number of records returned by the query. ColumnList A comma-delimited list of the query columns. CurrentRow The current row of the query being processed by cfoutput. To output query data on your page: 1 Return to emplist.
PAGE 53

Getting Information About Query Results 33 You now display the number of records retrieved in the query. The following table describes the code and its function: Code Description Display what follows The query returned Display the text “The query returned” #EmpList.RecordCount# Display the number of records retrieved in the EmpList query records Display the text “records” End the cfoutput block.
PAGE 54

34 Chapter 3 Querying a Database Using Query Results in Queries ColdFusion allows you to use the results of a previous query in any cfquery tag that returns row data to ColdFusion. You can query a database once and use the results in several dependent queries. Queries generated from other queries are often referred to as query of queries.
PAGE 55

Using Query Results in Queries 35 Boolean predicates: Aggregate functions: LIKE NOT LIKE IN NOT IN BETWEEN NOT BETWEEN AND OR Count([DISTINCT][*] expr) Sum([DISTINCT] expr) Avg([DISTINCT] expr) Max(expr) Min(expr) You cannot nest aggregate functions. Comparison operators: <= >= = < > <> You can also do the following tasks: • Use the results of one or two queries in your SQL statement. • Generate computed columns.
PAGE 56

36 Chapter 3 Querying a Database To use the results of a query in a query: 1 Create a new application page in ColdFusion Studio.
PAGE 57

Using Query Results in Queries 37 Reviewing the code The page retrieves the entire Employee table from the CompanyInfo database. A second query selects only the three columns to display for employees with the specified last name. The following table describes the code and its function: Code Description cfset ListNameSearch = "Jones" Set the last name to use in the second query. In a complete application, this information comes from user interaction.
PAGE 58

38 Chapter 3 Querying a Database
PAGE 59

Chapter 4 Retrieving and Formatting Data This chapter explains how to select the data to display in a dynamic Web page. It also describes how to populate an HTML table with query results and how to use ColdFusion functions to format and manipulate data. Contents • Using Forms to Specify the Data to Retrieve........................................................... 40 • Working with Action Pages .......................................................................................
PAGE 60

40 Chapter 4 Retrieving and Formatting Data Using Forms to Specify the Data to Retrieve In the examples in previous chapters, you have retrieved all of the records from a table. However, there are many instances when you want to retrieve data based on certain criteria. For example, you might want to see records for everyone in a particular department, everyone in a particular town whose last name is Smith, or books by a certain author.
PAGE 61

Using Forms to Specify the Data to Retrieve 41
Form controls Within the form, you describe the form controls needed to gather and submit user input. There are a variety of form controls types available. You choose form control input types based on the type of input the user should provide.
PAGE 62

42 Chapter 4 Retrieving and Formatting Data Control Code Reset button Submit button Use the following procedure to create a sample form. To create a form 1 Create a new application page, using ColdFusion Studio. 2 Edit the page so that it appears as follows: Input form
Contractor? Yes
3 Save the page as formpage.cfm within the myapps directory under your Web root directory. 4 View the form in a browser. The form appears in the browser.
PAGE 64

44 Chapter 4 Retrieving and Formatting Data Code Description Create a drop-down list box named City and populate it with the values “Arlington,” “Boston,” “Cambridge,” “Minneapolis,” and “Seattle.
PAGE 65

Working with Action Pages 45 Working with Action Pages A ColdFusion action page is just like any other application page except that you can use the form variables that are passed to it from an associated form. The following sections describe how to create effective action pages. Processing form variables on action pages The action page gets a form variable for every form control that contains a value when the form is submitted.
PAGE 66

46 Chapter 4 Retrieving and Formatting Data However, instead of putting the LastName directly in the SQL WHERE clause, you can use the text that the user entered in the form for comparison: SELECT FirstName, LastName, Salary FROM Employee WHERE LastName="#Form.LastName#" For more information on Dynamic SQL, see “Dynamic SQL” on page 96. Creating action pages Use the following procedure to create an action page for cormpage.cfm.
PAGE 67

Working with Action Pages 47 This time an error occurs because the check box does not pass a variable to the action page. Reviewing the code The following table describes the highlighted code and its function: Code Description Query the data source CompanyInfo and name the query GetEmployees. SELECT FirstName, LastName, Salary FROM Employee WHERE LastName=’#Form.
PAGE 68

48 Chapter 4 Retrieving and Formatting Data The argument passed to the IsDefined function must always be enclosed in double quotes. For more information on the IsDefined function, see the CFML Reference. If you attempt to evaluate a variable that you did not define, ColdFusion cannot process the page and displays an error message. To help diagnose such problems, use the interactive debugger in ColdFusion Studio or turn on debugging in the ColdFusion Administrator.
PAGE 69

Working with Queries and Data 49 Working with Queries and Data The ability to generate and display query data is one of the most important and flexible features of ColdFusion. The following sections further your understanding of using queries and displaying their results. Some of these tools are effective for presenting any data, not just query results. Using HTML tables to display query results You displayed each row of data from the Employee table, but the information was unformatted.

PAGE 70

50 Chapter 4 Retrieving and Formatting Data 3 Save the page as actionpage.cfm within the myapps directory. 4 View formpage.cfm in your browser. 5 Enter Smith in the Last Name text box and submit the form. 6 The records that match the criteria specified in the form appear in a table. Reviewing the code The following table describes the highlighted code and its function: Code Description

Put data into a table.

PAGE 71

Working with Queries and Data 51 Performing pattern matching Use the SQL LIKE operator and SQL wildcard strings in a SQL WHERE clause when you want to compare a value against a character string field so that the query returns database information based on commonalities. This technique is known as pattern matching and is often used to query databases.

PAGE 72

52 Chapter 4 Retrieving and Formatting Data Creating table joins Many times, the data that you want to retrieve is maintained in multiple tables. For example, in the database that you are working with: • Department information is maintained in the Departmt table. This includes department ID numbers. • Employee information is maintained in the Employee table. This also includes department ID numbers.

PAGE 73

Working with Queries and Data 53 The following action page allows users to search for employees by department, last name, or both. To build a more flexible search interface: 1 2 Open the page actionpage.cfm in ColdFusion Studio. Modify the page so that it appears as follows: Retrieving Employee Data Based on Criteia from Form SELECT Departmt.Dept_Name, Employee.FirstName, Employee.LastName, Employee.

PAGE 74

54 Chapter 4 Retrieving and Formatting Data Reviewing the code The following table describes the highlighted code and its function: Code Description SELECT Departmt.Dept_Name, Employee.FirstName, Employee.LastName, Employee.StartDate, Employee.Salary FROM Departmt, Employee WHERE Departmt.Dept_ID = Employee.Dept_ID Retrieve the fields listed from the Departmt and Employee tables, joining the tables based on the Dept_ID field in each table. AND Departmt.

PAGE 75

Returning Results to the User 55 Returning Results to the User When you return your results to the user, you must make sure that your pages respond to the user’s needs and are appropriate for the type and amount of information. In particular you must consider the following situations: • When there are no query results • When you want to return partial results If there are no query results Your code must accommodate the cases where a query does not return any records.

PAGE 76

56 Chapter 4 Retrieving and Formatting Data AND Employee.LastName = ’#Form.LastName#’ No records match your search criteria.
Please go back to the form and try again.

PAGE 77

Returning Results to the User 57 When you flush data, make sure that a sufficient amount of information is available, because some browsers might not respond if you flush only a very small amount. Similarly, if you use an interval attribute, set it for a reasonable size, such as a few hundred bytes or more but not many thousands of bytes. Caution After you use the cfflush tag on a page, any CFML function or tag on the page that modifies the HTML header causes an error.

PAGE 78

58 Chapter 4 Retrieving and Formatting Data Reviewing the code The following table describes the code and its function: Code Description

We are sure you will agree it was worth the short wait!

Send the HTML header and all HTML output to the cfflush tag to the user. This displays the explanatory paragraph and H2 tag contents. Flush additional data to the user every time at least ten bytes are available.

PAGE 79

Chapter 5 Graphing Data This chapter explains how to use the cfgraph tag to display graphs. It illustrates ways that you can graph data and gives you the tools you need to create effective graphs. The cfgraph tag requires the JRun server and the Macromedia Generator server, which install with ColdFusion. Contents • Creating a Graph ....................................................................................................... 60 • Graphing Data ....................................................

PAGE 80

60 Chapter 5 Graphing Data Creating a Graph The cfgraph tag provides five graph types. A large number of attributes let you customize the graph appearance to meet your needs.

PAGE 81

Creating a Graph 61 Creating a basic graph You use the following cfgraph attributes to create a basic graph: Attribute Description type Must be one of the following values: bar, horizontalbar, pie, or line. (An area graph is a kind of line graph.) query The query containing the data. valueColumn The query column containing the values to be graphed. itemColumn (Optional) The query column containing the description for this data point.

PAGE 82

62 Chapter 5 Graphing Data Graphing Data One of the most important considerations when you graph data is the way you supply the data to the cfgraph tag. You can supply data in several ways: • Provide all the data in a single query. • Specify individual data points using cfgraphdata tags. • Combine data from a query with additional data points from cfgraphdata tags. Note The cfgraph tag graphs numeric data only.

PAGE 83

Graphing Data 63 Attribute Description URL (Optional) Works only with bar, horizontal bar, and pie charts in Flash file format. A static prefix for all data point URLs. When the user clicks a bar or pie wedge, the page links to a URL created by appending the data from the data point’s URLColumn value. Use this attribute to specify a string that is part of all links on a chart, such as http://www.mycompany.com/myapp/salary_info/chart_details/.

PAGE 84

64 Chapter 5 Graphing Data SELECT Dept_Name, AVG(Salary) AS AvgByDept FROM GetSalaries GROUP BY Dept_Name

PAGE 85

Graphing Data 65 Reviewing the code The following table describes the code and its function: Code Description SELECT Departmt.Dept_Name, Employee.Salary FROM Departmt, Employee WHERE Departmt.Dept_ID = Employee.Dept_ID Query the CompanyInfo database to get the Dept_Name and Salary for each employee. Because the Dept_Name is in the Departmt table and the Salary is in the Employee table, you need a table join in the WHERE clause.

PAGE 86

66 Chapter 5 Graphing Data This pie chart displays the income values of four departments. Each cfgraph tag specifies a department’s income and the corresponding item description for the legend. The values are specified by individual ColdFusion variables. The title “Income by Department” appears above the chart. The cfgraphdata tag lets you specify the following information about a data point: Attribute Description value The data value to be graphed.

PAGE 87

Controlling Graph Appearance 67 Controlling Graph Appearance The cfgraph tag allows you to customize the appearance of your graph in many ways. Common graph characteristics You can optionally specify the following characteristics on all types of graphs: Graph characteristic Attributes used Description Title title titleFont The title to display on the graph and the font to use. File Type fileFormat Whether to send the graph to the user as a jpeg or Flash (.swf) file. Flash is the default format.

PAGE 88

68 Chapter 5 Graphing Data Setting bar and horizontal bar chart characteristics You can specify the following additional characteristics for bar and horizontal bar charts: Graph characteristic Attributes used Description Value labels showValueLabel valueLabelFont valueLabelSize valueLocation Labels that display the numeric value being graphed. By default, value labels are on. You can turn them off or have them display when the user points to the bar (Flash file format only).

PAGE 89

Controlling Graph Appearance Graph characteristic 69 Attributes used Description Data point colors colorList A comma-separated list of colors to use for each bar. You can use any of the 256 standard Web colors and any valid Web color name notation (for example, blue or ##FF33CC). You must use double pound signs with hexadecimal color notation. These colors replace the standard system-defined colors. If you specify fewer colors than data points, the colors repeat.

PAGE 90

70 Chapter 5 Graphing Data 4 Return to your browser and enter the following URL to view graphdata.cfm: http://127.0.0.1/myapps/graphdata.cfm Reviewing the code The following table describes the highlighted code and its function: Code Description title = "Average Salary by Department" Put a title above the graph. depth = 10 Give the graph 10 pixels of 3D "depth" shadow. scaleTo = 100000 Set the maximum value of the vertical axis to 100000. The minimum value is the default, 0.

PAGE 91

Controlling Graph Appearance 71 Setting pie chart characteristics You can specify the following additional characteristics for pie charts: Graph characteristic Attributes used Description Value labels showValueLabel valueLabelFont valueLabelSize valueLocation Labels that display the numeric value being graphed. Value labels are on by default. You can turn them off or have them display when the user points to the bar (Flash file format only).

PAGE 92

72 Chapter 5 Graphing Data Example: adding a pie chart The example in the following procedure adds a pie chart to the page. To create a pie chart: 1 Open graphdata.cfm in ColdFusion Studio. 2 Edit the DeptSalaries query and the cfloop code so that they appear as follows: SELECT Departmt.Dept_Name, Employee.StartDate, Employee.Salary FROM Departmt, Employee WHERE Departmt.Dept_ID = Employee.Dept_ID 3 Add the following code before the html tag:

Department:
Training
Sales
Marketing
HR

Contractor? Yes

PAGE 104

84 Chapter 6 Making Variables Dynamic Creating Dynamic Check Boxes and Multiple-Selection List Boxes When an HTML form contains either a list of check boxes with the same name or a multiple-selection list box (that is, where users can select multiple items from the list), the user’s entries are made available as a comma-delimited list with the selected values. These lists can be very useful for a wide range of inputs.

PAGE 105

Creating Dynamic Check Boxes and Multiple-Selection List Boxes 85 The user sees the name of the department, but the value attribute of each check box is a number that corresponds to the underlying database primary key for the department’s record. If the user checks the Marketing and Sales items, the value of the SelectedDept form field is "2,4" and you use the SelectedDepts in the following SQL statement: SELECT * FROM Departmt WHERE Dept_ID IN ( #Form.

PAGE 106

86 Chapter 6 Making Variables Dynamic Note In SQL, all strings must be surrounded in single quotes. The ListQualify function returns a list with the specified qualifying character (here, a single quote) around each item in the list.

PAGE 107

Creating Dynamic Check Boxes and Multiple-Selection List Boxes 87 Searching string values Suppose you want the user to select departments from a multiple selection list box. The database search field is a string field.

PAGE 108

88 Chapter 6 Making Variables Dynamic Ensuring that Variables Exist The sample code in the previous sections is incomplete. Either the form or the action page should make sure that the SelectDepts variable has a value before it is used in the SQL Select statement. Otherwise, users who do not select any department get an error message.

PAGE 109

Ensuring that Variables Exist 89 For example, the following series of cfparam tags indicates that this page expects two form variables named StartRow and RowsToFetch: If the page with these tags is called without either one of the form variables, an error occurs and the page stops processing.

PAGE 110

90 Chapter 6 Making Variables Dynamic Validating Data Types It is often not sufficient that input data merely exists; it must also have the right format. For example, a date field must have data in a date format. A salary field must have data in a numeric or currency format. There are many ways to ensure the validity of data, including the following methods: • Using the cfparam tag with the type attribute to validate any variable.

PAGE 111

Validating Data Types 91 If the variable is not in a valid date format, an error occurs and the page stops processing. Validating form field data types One limitation of standard HTML forms is that you cannot validate that users input the type or range of data you expect. ColdFusion enables you to do several types of data validation by adding hidden fields to forms.

PAGE 112

92 Chapter 6 Making Variables Dynamic Using a single page for both the form and action provides the opportunity to illustrate the use of the IsDefined function to check that data exists. This way, the form does not show any results until you submit the input. To validate the data that users enter in the insert form: 1 Create a new page in ColdFusion Studio.

PAGE 113

Validating Data Types 93 3 Save the file as datatest.cfm. 4 View the file in your browser, omit a field or enter invalid data, and click the Submit button. When the user submits the form, ColdFusion scans the form fields to find any validation rules you specified. The rules are then used to analyze the user’s input. If any of the input rules are violated, ColdFusion sends an error message to the user that explains the problem.

PAGE 114

94 Chapter 6 Making Variables Dynamic Code Description Salary:
Create a text box called Salary in which users can enter their salary. Make it exactly ten characters wide. Start Date is: #DateFormat(Form.StartDate)#
Salary is: #DollarFormat(Form.Salary)# Output the values of the StartDate and Salary form fields only if they are defined.

PAGE 115

Validating Data Types 95 The following example shows the use of cfqueryparam when valid input is given in the Course_ID variable used as a query parameter. To see what happens when you use invalid data, substitute a text string such as “test” for the integer 12 in the cfset statement. Note that this example uses the cfsnippets database that is provided with ColdFusion, not the CompanyInfo database used in most of this book.

PAGE 116

96 Chapter 6 Making Variables Dynamic Code Description WHERE Course_ID= Only select rows where the Course_ID column equals the value of Course_ID CFML local variable. Validate that the variable value is an integer and, if appropriate for the database driver, use a bind parameter to associate the value with the SQL statement.

PAGE 117

Dynamic SQL 97 Creating the input form First, you need to create an input form, which asks for information about several fields in the Employee table. To search for data based on only the fields the user enters in the form, you use cfif statements in the SQL statement. To create the input form: 1 Create a new application page in ColdFusion Studio.

PAGE 118

98 Chapter 6 Making Variables Dynamic Creating the action page After you create the input form, you can create the action page to process the user’s request. This action page determines where the user entered search criteria and searches based only on those criteria. To create the action page: 1 Create a new application page in ColdFusion Studio.

PAGE 119

Dynamic SQL 99

#FirstName#

#LastName#

#DollarFormat(Salary)#

#Contract#

3 Save the page as getemp.cfm. 4 Open the file askemp.cfm in your browser and enter criteria into any fields, then submit the form. 5 Verify that the results meet the criteria you specify. Reviewing the code The action page getemp.cfm builds a SQL statement dynamically based on what the user enters in the form page AskEmp.cfm.

PAGE 120

100 Chapter 6 Making Variables Dynamic CFML Code Description Employee.Contract = ‘Yes' AND Employee.Contract = 'No' AND If the user selected the Contractor check box, get data for the employees who are contractors; otherwise, get data for employees who are not contractors. The isdefined function test for the existence of the Form.Contract variable is needed because the variable only exists if they select the Contractor box.
PAGE 121

Chapter 7 Updating Your Database This chapter describes how to insert, update, and delete data in a database with ColdFusion. Contents • Inserting Data .......................................................................................................... 102 • Updating Data ......................................................................................................... 106 • Deleting Data.........................................................................................................
PAGE 122

102 Chapter 7 Updating Your Database Inserting Data You usually use two application pages to insert data into a database: • An insert form • An insert action page You can create an insert form with standard HTML form tags or with cfform tags (see “Creating Forms with the cfform Tag” on page 136). When the user submits the form, form variables are passed to a ColdFusion action page that performs an insert operation (and whatever else is called for) on the specified data source.
PAGE 123

Inserting Data 103 3 Save the file as insertform.cfm in the myapps directory. 4 View insertform.cfm in a browser. Data entry form notes and considerations If you use the cfinsert tag in the action page to insert the data into the database, you should follow these rules for creating the form page: • You only need to create HTML form fields for the database fields into which you want to insert data.
PAGE 124

104 Chapter 7 Updating Your Database 3 Save the page as insertaction.cfm. 4 View insertform.cfm in a browser, enter values, and click the Submit button. 5 The data is inserted into the Employee table and the message displays. Reviewing the code The following table describes the code and its function: Code Description
PAGE 125

Inserting Data 105 Creating an insert action page with cfquery For more complex inserts from a form submittal you can use a SQL INSERT statement in a cfquery tag instead of a cfinsert tag. The SQL INSERT statement is more flexible because you can insert information selectively or use functions within the statement. To create an insert page with cfquery: 1 Rename (or delete) the insertaction.cfm page that you created in the previous section. 2 Create a new application page in ColdFusion Studio.
PAGE 126

106 Chapter 7 Updating Your Database Reviewing the code The following table describes the highlighted code and its function: Code Description INSERT INTO Employee VALUES (’#Form.Emp_ID#’, ’#Form.FirstName#’, ’#Form.LastName#’, ’#Form.Dept_ID#’, ’#Form.StartDate#’, ’#Form.Salary#’, ’#Form.Contract#’) Use a cfquery tag to insert a new row into the Employee table of the CompanyInfo Database. Specify each form field to be added.
PAGE 127

Updating Data 107 To create an update form: 1 Create a new page in ColdFusion Studio. 2 Edit the page so that it appears as follows: SELECT * FROM Employee WHERE Emp_ID = #URL.Emp_ID# Update Form
PAGE 128
108 Chapter 7 Updating Your Database Reviewing the code The following table describes the code and its function: Code Description SELECT * FROM Employee WHERE Emp_ID = #URL.Emp_ID# Query the CompanyInfo data source and return the records in which the employee ID matches what was entered in the URL that called this page.
PAGE 129

Updating Data 109 Creating an action page to update data You can create an action page to update data with either the cfupdate tag or cfquery with the UPDATE statement. Creating an update action page with cfupdate The cfupdate tag is the easiest way to handle simple updates from a front end form. The cfupdate tag has an almost identical syntax to the cfinsert tag. To use cfupdate, you must include the field or fields that make up the primary key in your form submittal.
PAGE 130

110 Chapter 7 Updating Your Database Reviewing the code The following table describes the code and its function: Code Description If the user clears the Contractor check box, no value gets passed to the action page. Also, the database field must have a value of Yes or No. Test the Form.contract variable and set it to No if it is not defined and Yes if it is defined.
PAGE 131

Updating Data 111
Employee Updated
You have updated the information for #Form.FirstName# #Form.LastName# in the Employees database. 3 Save the page. 4 View updateform.cfm in a browser by specifying the page URL and an Employee ID, for example, http://localhost/myapps/updateform.cfm?Emp_ID=3. Enter new values in any of the fields, and click Submit. 5 The data is updated into the Employee table and the message displays.
PAGE 132

112 Chapter 7 Updating Your Database Deleting Data You use a cfquery tag with a SQL DELETE statement to delete data from a database. Deleting a single record To delete a single record, use the table’s primary key in the WHERE condition of a SQL DELETE statement. In the example, the Emp_ID field is the primary key, so the SQL Delete statement is as follows: DELETE FROM Employee WHERE Emp_ID = #Form.Emp_ID# You often want to see the data before you delete it.
PAGE 133

Deleting Data 113 8 View deleteform.cfm a browser by specifying the page URL and an Employee ID, for example, http://localhost/myapps/updateform.cfm?Emp_ID=3. and click the Submit button. The employee is deleted from the Employee table and the message displays. Reviewing the code The following table describes the code and its function: Code Description DELETE FROM Employee WHERE Emp_ID = #Form.
PAGE 134

114 Chapter 7 Updating Your Database
PAGE 135

Chapter 8 Handling Complex Data with Structures ColdFusion supports dynamic multidimensional arrays. This chapter explains the basics of creating and handling arrays. It also provides several examples showing how arrays can enhance your ColdFusion application code. ColdFusion also supports structures for managing lists of key-value pairs. This chapter explains the basics of creating and working with structures. Contents • About Arrays ......................................................................
PAGE 136

116 Chapter 8 Handling Complex Data with Structures About Arrays Traditionally, an array is a tabular structure used to hold data, much like a spreadsheet table with clearly defined limits and dimensions. A two-dimensional (2D) array is like a simple table. In ColdFusion, you typically use arrays to temporarily store data. For example, if your site allows users to order goods online, you can store their shopping cart contents in an array.
PAGE 137

About Arrays 117 ColdFusion dynamic 2D array A ColdFusion 2D array is actually a one-dimensional array that contains a series of additional 1D arrays. Each of the arrays that make up a row can expand and contract independently of any other column. The following terms will help you understand subsequent discussions of ColdFusion arrays: • Array dimension The relative complexity of the array structure.
PAGE 138

118 Chapter 8 Handling Complex Data with Structures Basic Array Techniques To use arrays in ColdFusion, as in other languages, you need to first declare the array, specifying its dimension. Once it is declared, you can add array elements, which you can then reference by index. As an example, suppose you declare a 1D array called "firstname": At first, the array firstname holds no data and is of an unspecified length.
PAGE 139

Basic Array Techniques 119 Creating multidimensional arrays ColdFusion supports dynamic multidimensional arrays. When you declare an array with the ArrayNew function, you can specify up to three dimensions.
PAGE 140

120 Chapter 8 Handling Complex Data with Structures PAGE 152
132 Chapter 8 Handling Complex Data with Structures Example file addemployee.cfm Error. No employee data was passed.
PAGE 153

Structure Functions 133

Employee Department

#person# #Departments[person]#

Structure Functions Use the following functions to create and manage structures in ColdFusion applications: Function Description IsStruct Re
PAGE 154

134 Chapter 8 Handling Complex Data with Structures Note that in all cases, except StructDelete, an exception is thrown if the referenced key or structure does not exist. For more information on these functions, see the CFML Reference.
PAGE 155

Chapter 9 Building Dynamic Forms This chapter shows you how to use the cfform tag to enrich your forms with sophisticated graphical controls, including several Java applet-based controls. You can use these controls without writing a line of Java code. Contents • Creating Forms with the cfform Tag ...................................................................... 136 • Input Validation with cfform Controls ..................................................................
PAGE 156

136 Chapter 9 Building Dynamic Forms Creating Forms with the cfform Tag You already learned how to use HTML forms to gather user input (see “Using Forms to Specify the Data to Retrieve” on page 40). This chapter shows you how to use the cfform tag to create dynamic forms in CFML.
PAGE 157

Creating Forms with the cfform Tag 137 cfform controls The following table describes the controls ColdFusion controls you use in forms created using cfform: Control Description cfgrid A Java applet-based control that creates a data grid you can populate from a query or by defining the contents of individual cells. You can also use grids to insert, update, and delete records from a data source. cfslider A Java applet-based control that defines a slider.
PAGE 158

138 Chapter 9 Building Dynamic Forms Usage notes • In cftree, the preservedata attribute causes the tree to expand the tree to the previously selected element. For this to work correctly, you must also set the completePath attribute to True. • The preservedata attribute has no effect on cfgrid. If you populate the control from a query, you should update the data source with the new data (typically by using cfgridupdate) before redisplaying the grid. The grid then displays the updated database information.
PAGE 159

Input Validation with cfform Controls 139 Input Validation with cfform Controls The cfinput and cftextinput tags include the validate attributes which allows you to specify a valid data entry type for the control. You can validate user entries on the following data types. Data type Description Date Verifies US date entry in the form mm/dd/yyyy (where the year can have one through four digits).
PAGE 160

140 Chapter 9 Building Dynamic Forms Validating with regular expressions You can use regular expressions to match and validate the text that users enter in cfinput and cftextinput tags. Ordinary characters are combined with special characters to define the match pattern. The validation succeeds only if the user input matches the pattern. Regular expressions allow you to check input text for a wide variety of conditions.
PAGE 161

Input Validation with cfform Controls 141 • If the first character of a set of characters in bracket is the caret (^), the expression matches any character except those in the set. It does not match the empty string. For example: [^akm] matches any character except "a", "k", or "m". The caret loses its special meaning if it is not the first character of the set. • You can make regular expressions case insensitive by substituting individual characters with character sets, for example, [Nn][Ii][Cc][Kk].
PAGE 162

142 Chapter 9 Building Dynamic Forms • A one-character regular expression or grouped subexpression followed by a plus (+) matches one or more occurrences of the regular expression. For example, [a-z]+ matches one or more lowercase characters. • A one-character regular expression or grouped subexpression followed by a question mark (?) matches zero or one occurrences of the regular expression. For example, xy?z matches either "xyz" or "xz".
PAGE 163

Input Validation with cfform Controls 143 Expression examples The following examples show some regular expressions and describe what they match: Expression Description [\?&]value= Any string containing a URL parameter value. ^[A-Z]:(\\[A-Z0-9_]+)+$ An uppercase DOS/Windows directory path that is not the root of a drive and has only letters, numbers, and underscores in its text. ^(\+|-)?[1-9][0-9]*$ An integer that does not begin with a zero and has an optional sign. ^(\+|-)?[1-9][0-9]*(\.
PAGE 164

144 Chapter 9 Building Dynamic Forms Input Validation with JavaScript In addition to native ColdFusion input validation using the validate attribute of the cfinput and cftextinput tags, the following tags support the onvalidate attribute, which allows you to specify a JavaScript function to handle your cfform input validation: • cfgrid • cfinput • cfslider • cftextinput • cftree ColdFusion passes the following JavaScript objects to the JavaScript function you specify in the onvalidate attribute: • form_ob
PAGE 165

Input Validation with JavaScript To use JavaScript to validate form data: 1 Create a new file in ColdFusion Studio. 2 Edit the page so that it appears as follows: JavaScript Validation JavaScript code to test for valid entry in the text box.
PAGE 167

Building Tree Controls with cftree 147 Building Tree Controls with cftree The cftree form lets you display hierarchical information in a space-saving collapsible tree populated from data source queries. To build a tree control with cftree, you use individual cftreeitem tags to populate the control. You can specify one of six built-in icons to represent individual items in the tree control, or supply a URL to your own gif image.
PAGE 168

148 Chapter 9 Building Dynamic Forms Grouping output from a query In a query that you display using a cftree control, you might want to organize your employees by the department. In this case, you separate column names with commas in the cftreeitem value attribute. To organize the tree based on ordered results of a query: 1 Open a new file named tree2.cfm in ColdFusion Studio.
PAGE 169

Building Tree Controls with cftree 149 Reviewing the code The following table describes the highlight code and its function: Code Description ORDER BY Dept_ID Order the query results by department.
PAGE 170

150 Chapter 9 Building Dynamic Forms Structuring Tree Controls Tree controls built with cftree can be very complex. Knowing how to specify the relationship between multiple cftreeitem entries will help you handle even the most complex of cftree constructs.
PAGE 171

Structuring Tree Controls 151 parent="Divisions" img="folder">
PAGE 172

152 Chapter 9 Building Dynamic Forms Embedding URLs in a cftree The href attribute in the cftreeitem tag allows you to designate tree items as links. To use this feature in a cftree, you simply define the destination of the link in the href attribute of cftreeitem. The URL for the link can be a relative URL or an absolute URL as in the following examples. To embed links in a cftree: 1 Open a new file named tree3.cfm in ColdFusion Studio.
PAGE 173

Creating Data Grids with cfgrid 153 Specifying the tree item in the URL When a user clicks on a tree item to link to a URL the cftreeItemKey variable, which identifies the selected value, is appended to the URL in the form: http://myserver.com?cftreeitemkey =selected_value Automatically passing the name of the selected tree item as part of the URL makes it easy to implement a basic "drill down" application that displays additional information based on the selection.
PAGE 174

154 Chapter 9 Building Dynamic Forms Populating a grid from a query To populate a grid from a query: 1 Open a new file named grid1.cfm in ColdFusion Studio. 2 Edit the file so that it appears as follows: SELECT * FROM Employee PAGE 175
Creating an Updateable Grid 155 Note If you specify a cfgrid tag with a query attribute defined and no corresponding cfgriditem attributes the grid contains all the columns in the query. Creating an Updateable Grid You can build grids to allow users to edit data within them. Users can edit individual cell data, as well as insert, update, or delete rows. To enable grid editing, you specify selectmode="edit" in the cfgrid tag and enable the insert or delete attributes in cfgrid.
PAGE 176

156 Chapter 9 Building Dynamic Forms Controlling cell contents The cfgridcolumn type, value, valuesDisplay, and valuesDelimiter attributes let you control the data that a user can enter into a cfgrid cell in the following ways: • By default, a cell is an editable text field. • Use the type attribute to require numeric or string data, to make the fields check boxes, or to display an image. • Use the values attribute to specify a drop-down list of values from which the user can chose.
PAGE 177

Creating an Updateable Grid 157 The value of change_index increments for each row that changes, and does not indicate the specific row number. When the user updates data or inserts or deletes rows, the action page gets one array for each changed column, plus the RowStatsus.Action array. The action page does not get arrays for unchanged columns.
PAGE 178

158 Chapter 9 Building Dynamic Forms To make the grid editable: 1 Open the file grid1.cfm in ColdFusion Studio. 2 Edit the file so that it appears as follows: SELECT * FROM Employee PAGE 179
Creating an Updateable Grid 159 Reviewing the code The following table describes the code and its function: Code Description Populate a cfgrid control with data from the empdata query. Selecting a grid cell enables you to edit it. Rows can be inserted and deleted. The grid is 300 X 250 pixels and has 10 pixels of space above and below it.
PAGE 180

160 Chapter 9 Building Dynamic Forms To update the data source with cfgridupdate 1 Open a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: 3 Save the file as handle_grid.cfm. 4 View grid2.cfm in your browser, make changes to the grid, and then submit them.
PAGE 181

Creating an Updateable Grid 161
DELETE FROM Employee WHERE Emp_ID=#Form.employee_grid.original.Emp_ID [Counter]# UPDATE Employee SET LastName=’#Form.employee_grid.LastName[Counter]#’, Dept_ID=#Form.employee_grid.
PAGE 182

162 Chapter 9 Building Dynamic Forms Reviewing the code The following table describes the code and its function: Code Description If there is an array of edit types, then the table needs changing. Otherwise, do nothing. Loop through the remaining code once for each row to be changed.
PAGE 183

Creating an Updateable Grid 163 Code Description Otherwise, if the action is to insert a row, generate a SQL INSERT query to insert the Employee’s last name and department ID from the grid row into the database. The Insert operation assumes that the DBMS automatically increments the Emp_ID primary key.
PAGE 184

164 Chapter 9 Building Dynamic Forms Building Slider Bar Controls You can use the cfslider control to create a slider control and define a wide range of formatting options for slider label text, label font name, size, boldface, italics, and color, as well as slider scale increments, range, positioning, tick marks, and behavior. Slider bars are useful because they are highly visual and users cannot enter invalid values. To create a slider control: 1 Create a new file in ColdFusion Studio.
PAGE 185

Building Text Entry Boxes 165 Building Text Entry Boxes The cftextinput tag is similar to the HTML input=text tag. With cftextinput, however, you can also specify font and alignment options, as well as enable input validation methods using either a JavaScript or the validate attribute. The following example shows a basic cftextinput control. This example validates a date entry, which means that a user must enter a valid date in the form mm/dd/yy (the year can be up to four digits).
PAGE 186

166 Chapter 9 Building Dynamic Forms Building Drop-Down List Boxes The drop-down list box that you can create with cfselect is similar to the HTML select tag. However, cfselect gives you more control over user inputs, provides error handling, and, most importantly, allows you to automatically populate the selection list from a query.
PAGE 187

Embedding Java Applets 167 Embedding Java Applets The cfapplet tag allows you to embed Java applets in a cfform. To use cfapplet, you must first register your Java applet using the ColdFusion Administrator Java Applets page (under Extensions on the Server tab). In the Administrator, you define the interface to the applet, encapsulating it so that each invocation of the cfapplet tag is very simple.
PAGE 188

168 Chapter 9 Building Dynamic Forms Applet registration fields The following table explains the applet registration fields: Field Description Codebase Enter the base URL of the applet: the directory that contains the applet components. The applet class files must be located within the Web browser root directory. Example: http://servername/classes Code This is the name of the file that contains the compiled applet. The filename is relative to the code base URL. The *.
PAGE 189

Embedding Java Applets 169 Using cfapplet to embed an applet After you register an applet, you can use the cfapplet tag to place the applet in a ColdFusion page. The cfapplet tag has two required attributes: appletsource and name.
PAGE 190

170 Chapter 9 Building Dynamic Forms To reference a Java applet return value in your application page: 1 Specify the name of the method in the Add/Registered Java Applet page of the ColdFusion Administrator. 2 Specify the method name in the name attribute of the cfapplet tag when you code your cfform. When your page executes the applet, a form variable is created with the name that you specified. If you do not specify a method, no form variable is created.
PAGE 191

Chapter 10 Reusing Code This chapter describes how to reuse common code with cfinclude, and create custom CFML tags that encapsulate common code. Contents • Ways to Reuse Code ................................................................................................ 172 • Reusing Common Code with cfinclude................................................................. 172 • Using Custom Tags..................................................................................................
PAGE 192

172 Chapter 10 Reusing Code Ways to Reuse Code ColdFusion provides several different ways to reuse code. These ways include the following techniques: • If you are using ColdFusion Studio, you can write code snippets, which you can copy into pages. • You use the cfinclude tag to include a ColdFusion page in another page. Included pages behave just as though you typed the included code directly into the calling page. • You can create custom CFML tags.
PAGE 193

Using Custom Tags 6 173 Include the header.cfm file in this page: 7 View askemp.cfm in a browser, then submit the form so that you display getemp.cfm. The header should appear on both pages. Note The file header.cfm must be in the same directory where you saved askemp.cfm and getemp.cfm (or a subdirectory). If it is not, make sure it is in a directory that has a mapping defined in ColdFusion Administrator, or move it to the appropriate directory.
PAGE 194

174 Chapter 10 Reusing Code Using existing custom tags Before creating a custom tag in CFML, you should review the Custom Tag section of the ColdFusion Developer Exchange. Tags are grouped in several broad categories and are downloadable as freeware, shareware, or commercial software. You can quickly view each tag’s syntax and usage information. The Gallery contains a wealth of background information on custom tags and an online discussion forum for tag topics.
PAGE 195

Using Custom Tags 175 Custom tag pages also have access to system data structure called thisTag. The thisTag structure contains information about the tag and its execution environment. The thisTag variable is described in “Executing Custom Tags,” on page 185. Using tag attributes Custom tag attribute values are passed from the calling page to the custom tag page as name-value pairs. CFML custom tags support required and optional attributes. Attributes are defined as name-value pairs.
PAGE 196

176 Chapter 10 Reusing Code Passing values to and from custom tags Because custom tags are individual ColdFusion pages, variables and other data are not automatically shared between a custom tag and the calling page. To pass data from the calling page to the custom tag, specify attribute name-value pairs in the custom tag, just as you do for normal HTML and CFML tags. In the custom tag you use the Attributes scope to access these variables.
PAGE 197

Using Custom Tags 177 Passing custom tag attributes via CFML structures You can use the reserved attribute attributecollection to pass attributes to custom tags. Attributecollection must reference a structure that contains the attribute names as the keys and the attribute values as the values. You can freely mix attributecollection with other attributes when you call a custom tag. The key-value pairs in the structure specified by attributecollection get copied into the called page Attributes scope.
PAGE 198

178 Chapter 10 Reusing Code Custom tag example In this example, we create a custom tag that uses an attribute that is passed to it to set the value of a variable called Doctor on the calling page. To create a custom tag: 1 Create a new application page (the calling page) in ColdFusion Studio.
PAGE 199

Using Custom Tags 179 Reviewing the code The following table describes the code and its function: Code Description In the calling page, create a variable NameYouEntered and assign it the value "Smith." Before you leave this page, you’re #NameYouEntered#.
In the calling page, display the value of the NameYouEntered variable before calling the custom tag.
PAGE 200

180 Chapter 10 Reusing Code Nesting Custom Tags A custom tag can call other custom tags, thereby nesting tags. ColdFusion uses nested tags such as cfgraph and cfgraphdata, cfhttp and cfhttppam, and cftree and cftreeitem. The ability to nest tags allows you to provide similar functionality. The calling tag is known as an ancestor, parent, or base tag, while the tags that ancestor tags call are known as descendant, child, or sub tags.
PAGE 201

Passing Data Between Nested Custom Tags 181 Passing Data Between Nested Custom Tags A key custom tag feature is the ability of collaborating custom tags to exchange complex data without user intervention while encapsulating each tag’s implementation so that others cannot see it.
PAGE 202

182 Chapter 10 Reusing Code The cfassociate tag has the following format:
PAGE 203

Passing Data Between Nested Custom Tags 183 name. By default, the closest ancestor is returned. If there is no ancestor by the given name or if the ancestor does not expose any data (such as CFIF), an exception is thrown. Example: Ancestor data access This example creates two custom tags and a simple page that calls each of the custom tags. The first custom tag calls the second. The second tag reports on its status and provides information about its ancestors.
PAGE 204

184 Chapter 10 Reusing Code Ancestorlist entry #loopcount# n is #ListGetAt(ancestorlist,loopcount)#

I’m running in the context of a CFLOOP tag.
You can also use cfswitch:
PAGE 207

Installing Custom Tags 187 Access to generated content Custom tags can access and modify the generated content of any of its instances using the thisTag.GeneratedContent variable. In this context, the term generated content means the results of processing the body of a given tag. This includes all text and HTML code in the body, the results of evaluating ColdFusion variables, expressions, and functions, and the results generated by descendant tags.
PAGE 208

188 Chapter 10 Reusing Code Managing Custom Tags If you deploy custom tags in a multideveloper environment or distribute your tags publicly, you can use additional ColdFusion capabilities: • An advanced invocation syntax to resolve possible name conflicts • Advanced security • Template encoding Resolving filename conflicts To avoid errors caused by duplicate custom tag filenames, use the cfmodule tag in the calling page.
PAGE 209

Managing Custom Tags 189 Encoding custom tags You can use the command-line utility cfencode to encode any ColdFusion application page. By default, the utility is installed in the /cfusion/bin directory. It is especially useful for securing custom tag code before distributing it. The cfencode tag uses the following syntax: cfencode infile outfile [/r /q] [/h "message"] /v"2" The following table describes the options: Option Description input file Name of the file you want to encode.
PAGE 210

190 Chapter 10 Reusing Code
PAGE 211

Chapter 11 Preventing and Handling Errors ColdFusion includes many tools and techniques for ensuring that your code works properly. These tools include sophisticated debugging and code validation tools, error logging tools, and error handling mechanisms. This chapter describes these tools and presents approaches to troubleshooting common problems. ColdFusion Studio also provides interfaces for debugging application pages and for dynamically validating multiple levels of HTML and CFML code.
PAGE 212

192 Chapter 11 Preventing and Handling Errors Debug Settings in the ColdFusion Administrator ColdFusion can provide important debugging information for every application page requested by a browser. When you enable debugging, the output displays in a block following normal page output. For detailed information on the debugging and logging settings in the ColdFusion Administrator, see Advanced ColdFusion Administration.
PAGE 213

Debug Settings in the ColdFusion Administrator 193 ColdFusion returns the following information: • Database errors, including the ODBC error code, the extended error message returned from the ODBC driver, the name of the data source, and the SQL statement submitted to the database • Syntax error, including the line of the application page file on which the error occurred • System-related errors, such as out of memory conditions, or file or disk access errors You must select the Display the template path i
PAGE 214

194 Chapter 11 Preventing and Handling Errors CFML Code Validation ColdFusion provides two methods of validating your CFML code: • Runtime validation • The CFML Syntax Checker Runtime validation The ColdFusion Application Server features two modes of attribute checking for processing application pages: strict and relaxed. Macromedia recommends that you always use the strictest possible level of CFML validation. To enable strict validation: 1 Open the ColdFusion Administrator Server Settings page.
PAGE 215

Troubleshooting Common Problems 195 Troubleshooting Common Problems The following section describes a few common problems that you might encounter and ways to resolve them. ODBC data source configuration Problem: ODBC driver manager cannot make a connection to the database. Connection errors include problems with the location of files, network connections, and database client library configuration.
PAGE 216

196 Chapter 11 Preventing and Handling Errors Problem: Invalid attribute or value. If you use an invalid attribute or attribute values, ColdFusion returns an error message. To prevent such syntax errors, use the ColdFusion syntax validation tools in ColdFusion Studio. Problem: Mismatched quotes and escape characters. Check strings in attributes and expressions for proper placement of single and double quotes. Color coding in ColdFusion Studio can help you spot improper quote placement.
PAGE 217

Error Handling in ColdFusion 197 Error Handling in ColdFusion By default, ColdFusion generates its own error messages when it encounters errors.
PAGE 218

198 Chapter 11 Preventing and Handling Errors How ColdFusion handles errors The following pseudo-code program illustrates how ColdFusion handles errors. The rest of this expands on this outline: Case missing template error ColdFusion displays either a standard error page or an error page that you specify as the Missing Template Handler in the Administrator Server Settings Missing Template Handler field. Case validation error If cferror in application.
PAGE 219

Generating Custom Error Messages with cferror 199 Generating Custom Error Messages with cferror By default, ColdFusion uses a standard page for most errors. Custom error pages allow you to control the error information that users see. You can specify custom error pages for different types of errors and handle different types of errors in different ways. For example, you can create specific pages to handle errors that could be recoverable, such as request timeouts.
PAGE 220

200 Chapter 11 Preventing and Handling Errors Creating an error application page Error application pages for validation and request errors cannot use ColdFusion tags; they can only use HTML tags. Error application pages for exception and monitor errors can use all of CFML, including tags, expressions, and functions. Even validation and request error pages have access to specific CFML error variables such as Error.Diagnostics (for request errors) and Error.InvalidFields (for validation errors).
PAGE 221

Generating Custom Error Messages with cferror 201 Error type Error variable Description Validation error.validationHeader Text for header of default validation message. error.invalidFields Unordered list of validation errors that occurred. This includes any text that you specify in the value attribute or a hidden tag used to validate form input. error.validationFooter Text for footer of default validation message.
PAGE 222

202 Chapter 11 Preventing and Handling Errors Example of a validation error page The following example shows a custom error page for a validation error: Products - Error
Oops

You failed to correctly complete all the fields in the form. The following problems occurred:
#error.
PAGE 223

Logging Errors 203 We apologize for the inconvenience.
Reviewing the code The following table describes the highlighted code and its function: Code Description
PAGE 224

204 Chapter 11 Preventing and Handling Errors Handling Exceptions in ColdFusion Ordinarily, when ColdFusion encounters an error, it stops processing and displays an error message or error page (as specified by the cferror tag). However, you can use ColdFusion’s exception handling tags to catch and process exceptions in ColdFusion pages.
PAGE 225

Handling Exceptions in ColdFusion 205 Types of recoverable exceptions supported ColdFusion Server supports several types of recoverable exceptions. Use the type attribute in the cfcatch tag to determine which type of exception to catch. You can also use these types as the values of the exception attribute in cferror type=exception tags. You can specify the following basic exception types. For a list of advanced exception types, see the CFML Reference.
PAGE 226

206 Chapter 11 Preventing and Handling Errors Applications can optionally use the cfthrow tag to raise custom exceptions. Such exceptions are caught with any of the following type specifications: • type="custom_exception_type" • type="application" • type="any" The custom_exception_type type designates the name of a user-defined type specified in the cfthrow tag. An exception raised within a cfcatch block cannot be handled by the cftry block that immediately encloses the cfcatch tag.
PAGE 227

Handling Exceptions in ColdFusion 207 The structure at position 1 of the array represents the outermost tag in the stack of tags that were executing when the interpreter detected the exception. The structure at position ArrayLen(cfcatch.tagContext) represents the currently executing tag at the time the interpreter detected the exception. The tagContext structures have the following attributes: • Template The pathname of the application page that contains the tag.
PAGE 228

208 Chapter 11 Preventing and Handling Errors Locking exceptions The following additional information is available for exceptions related to cflock sections: Property variable Description cfcatch.lockName The name of the affected lock. This is set to "anonymous" if the lock name is unknown. cfcatch.lockOperation The operation that failed. This is set to "unknown" if the failed operation is unknown.
PAGE 229

Handling Exceptions in ColdFusion 209 SELECT Dept_ID, FirstName, LastName FROM Employee WHERE Emp_ID=#EmpID# Test cftry/cfcatch
PAGE 230
210 Chapter 11 Preventing and Handling Errors
Other Error: #cfcatch.Type#
- Message: #cfcatch.message#
- Detail: #cfcatch.Detail#
To test the code: 1 Make sure there is no includeme.cfm file and display the page. The cfcatch type="MissingInclude" block displays the error.
PAGE 231

Handling Exceptions in ColdFusion 211 Naming conventions A naming convention for custom exception types follows a convention that is similar to Java class naming conventions: domain name in reverse order, followed by project identifiers, as in this example: The predefined exception types, except for type="Application", are reserved; for example, will be rejected.
PAGE 232

212 Chapter 11 Preventing and Handling Errors
PAGE 233

Chapter 12 Using the Application Framework The ColdFusion Web Application Framework is a powerful tool that you can use to help structure your ColdFusion applications. This chapter describes how to create and use the Application.cfm file, the application page that controls the application framework. Contents • Understanding the Web Application Framework ................................................. 214 • Mapping an Application Framework.................................................................
PAGE 234

214 Chapter 12 Using the Application Framework Understanding the Web Application Framework A ColdFusion application is a collection of application pages that work together. Applications can be as simple as a guest book or as sophisticated as a full Internet commerce system with catalog pages, shopping carts, and reporting. You can combine individual applications to create advanced Web systems.
PAGE 235

Understanding the Web Application Framework 215 Variable Scope Description Application Contains variables that are available to all pages in an application for all clients. Application variables are stored in memory and time out after a period of inactivity or when the server shuts down. You can access the Application scope as a data structure. You must use the Application scope prefix in the variable name. Server Contains variables that are available to all applications in a server and all clients.
PAGE 236

216 Chapter 12 Using the Application Framework Mapping an Application Framework An important step in designing a ColdFusion application is mapping its directory structure. Before you start building the application, establish a root directory for the application. You can store application pages in subdirectories of the root directory. Processing Application.cfm and OnRequestEnd.cfm ColdFusion uses similar but different rules to locate and process Application.cfm and OnRequestEnd. Processing Application.
PAGE 237

Mapping an Application Framework 217 Defining the directory structure Defining a root directory for an application has a number of advantages: • Development The application is easier to develop and maintain because the application page files are well organized. • Portability You can more easily move the application to another server or another part of a server without changing any code in the application page files.
PAGE 238

218 Chapter 12 Using the Application Framework .
PAGE 239

Creating the Application.cfm File 219 Creating the Application.cfm File The special application-wide page called Application.
PAGE 240

220 Chapter 12 Using the Application Framework Example: Application.cfm The following example shows a complete Application.cfm file for the sample Products application: PAGE 241
Managing the Client State 221 Managing the Client State Because the Web is a stateless system, each connection that a browser makes to a Web server is unique to the Web server. However, within an application it is important to be able to keep track of users as they move through the pages within the application. This is the definition of client state management.
PAGE 242

222 Chapter 12 Using the Application Framework About client cookies Both types of variables normally require ColdFusion to store two client identification variables as cookies on the client’s system: • CFID, a sequential client ID • CFToken, a random-number client security token These cookies uniquely identify the client to the ColdFusion Server, which also maintains copies of the variables.
PAGE 243

Configuring and Using Client Variables 223 Configuring and Using Client Variables To use Client variables effectively, you set up the Client variable options and use the variables on your ColdFusion pages. Setting up Client variable options If you want to enable Client variables, you must do so on every page in an application. Because the Application.cfm file is included in all of the application’s pages, you enable client management in the cfapplication tag, at the beginning of Application.cfm.
PAGE 244

224 Chapter 12 Using the Application Framework Consider these additional limitations before implementing cookie storage for Client variables: • Many browsers allow only 20 cookies from a particular host to be set. ColdFusion uses two of these cookies for CFID and CFToken and also creates a cookie named cfglobals to hold global data about the client, such as HitCount, TimeCreated, and LastVisit. This limits you to 17 unique applications per host. • Some browsers set a size limit of 4K bytes per cookie.
PAGE 245

Configuring and Using Client Variables 225 The following example shows how to use the cfparam tag to check for the existence of a client parameter and to set a default value if the parameter does not already exist: Accessing and changing Client variables You use the same syntax to access a Client variable as other types of variables. You can use Client variables anywhere other ColdFusion variables are used.
PAGE 246

226 Chapter 12 Using the Application Framework Getting a list of Client variables To obtain a list of the custom client parameters associated with a particular client, use the GetClientVariablesList function. #GetClientVariablesList()# The GetClientVariablesList function returns a comma-separated list of the names of the Client variables for the current application.
PAGE 247

Configuring and Using Client Variables 227 Exporting the Client variable database If your Client variable database is stored in the Windows system registry and you need to move it to another machine, you can export the registry key that stores your Client variables and take it to your new server. The system tegistry allows you to export and import Registry entries. To export your Client variable database from the registry in Windows: 1 Open the Registry editor.
PAGE 248

228 Chapter 12 Using the Application Framework Using Session Variables Use Session variables when you need the variables for a single site visit or set of requests. For example, you might use Session variables to store a user’s selections in a shopping cart application. (Use Client variables when you need the variable for future visits.) Caution You must use the cflock tag to prevent multiple requests from accessing any Session variable simultaneously. Failure to do so can result in data corruption.
PAGE 249

Using Session Variables 229 The default timeout for Session variables is set to 20 minutes. You can change the timeout on the Memory Variables page of the ColdFusion Administrator Server tab. For more information, see Advanced ColdFusion Administration. You can also set the timeout period for Session variables inside a specific application (thereby overruling the Administrator default setting) by using the cfapplication tag sessionTimeout attribute.
PAGE 250

230 Chapter 12 Using the Application Framework Getting a list of Session variables The variable Session scope is registered as a ColdFusion structure. This lets you use the ColdFusion Structure functions to get a list of Session variables. For example, you can use cfloop with the StructFind function to output a list of Session variables defined for a specific application. To find a list of Client variables, you use the GetClientVariablesList function.
PAGE 251

Using Application Variables 231 variables, they are not useful for client-specific information. To target variables for specific clients, use Session or Client variables. Application variable timeouts Application variables have a specific lifetime. If no clients access the application within the specified timeout period, ColdFusion Server destroys its Application variables. The default timeout period for Application variables is two days.
PAGE 252

232 Chapter 12 Using the Application Framework Using Server Variables Server variables are associated with a single ColdFusion Server. They are available to all applications that run on the server. Use server variables for data that must be accessed across clients and applications. Server variables do not time out, but are lost when the server shuts down. You cannot delete a Server variable. Therefore, you should limit the amount of data you store in Sever variables.
PAGE 253

Locking Code with cflock 233 Locking Code with cflock The cflock tag controls simultaneous access to ColdFusion code. The cflock tag enables you to: • Protect sections of code that access and manipulate shared data such as Session, Application, and Server variables. • Ensure that file updates do not fail because files are open for writing by other applications or ColdFusion tags.
PAGE 254

234 Chapter 12 Using the Application Framework The cflock tag enables you to ensure that concurrently executing requests do not access the same section of code simultaneously and thus manipulate shared data structures, files, or CFXs inconsistently. It is important to remember that cflock protects code sections not variables. Lock types The cflock tag offers two modes of locking, specified by the type attribute: • Exclusive locks (the default lock type) allow only one request to process the locked code.
PAGE 255

Locking Code with cflock 235 You can set the attribute to any of the following values: Scope Meaning Server All code sections with this attribute on the server share a single lock. Application All code sections with this attribute in the same application share a single lock. Session All code sections with this attribute that run in the same session and application share a single lock.
PAGE 256

236 Chapter 12 Using the Application Framework For example, if you want to assign the results of a query to a Session variable, first get the query results using a Variables scope variable in unlocked code. Then, assign the query results to a Session variable inside a locked code section. The following code illustrates this technique: SELECT FirstName, LastName FROM Users WHERE UserID = #request.
PAGE 257

Locking Code with cflock 237 Automatic read locking also adds overhead because ColdFusion must insert read locks and check variable access for locking. However, it can be useful if you already have a site that does not use locking properly. In this case, you must only lock all writes and do not have to add locks around all reads. Single-threading sessions The ColdFusion Administrator also allows you to specify single-threaded sessions.
PAGE 258

238 Chapter 12 Using the Application Framework 5 Unlock the Application scope. 6 Unlock the Session scope. Note You can skip any pair of lock/unlock steps in the preceding list if you do not need to lock a particular scope. For example, you can omit steps 3 and 4 if you do not need to lock the Server scope. Examples of cflock The following examples show how to use cflock in a variety of situations.
PAGE 259

Examples of cflock 239 E-Turtleneck is proud to say that we have sold #application.number# turtlenecks to date. The remaining sample code could appear inside the application page where customers place orders. In this simple example, the Application.cfm page displays the Application.number variable value. Because Application.
PAGE 260

240 Chapter 12 Using the Application Framework

Congratulations! You have just selected the longest wearing, most comfortable turtleneck in the world.
PAGE 261

Examples of cflock 241 Example of synchronizing access to a file system The following example shows how to use cflock to synchronize access to a file system. The cflock tag protects a cffile tag from attempting to append data to a file already open for writing by the same tag executing on another request. Note that if an append operation takes more that 30 seconds, a request waiting to obtain an exclusive lock to this code might time out.
PAGE 262

242 Chapter 12 Using the Application Framework
PAGE 263

Chapter 13 Extending ColdFusion Pages with CFML Scripting ColdFusion offers a server-side scripting language, CFScript, that provides ColdFusion functionality in script syntax. This JavaScript-like language gives developers the same control flow, but without tags. You can also use CFScript to write custom functions that you can use anywhere a ColdFusion expression is allowed. This chapter describes the CFScript language’s functionality and syntax. Contents • About CFScript ...............................
PAGE 264

244 Chapter 13 Extending ColdFusion Pages with CFML Scripting About CFScript The ColdFusion Server-side scripting language, CFScript, offers ColdFusion functionality in script syntax. This JavaScript-like language offers the same control flow, but without tags. CFScript regions are bounded by and tags. You can use ColdFusion expressions, but not CFML tags, inside a CFScript region.
PAGE 265

The CFScript Language 245 The CFScript Language This section explains the syntax of the CFScript language. Comments Comments in CFScript blocks begin with two forward slashes (//) and end at the line end. You can also enclose CFScript comments between /* and */. Note that you cannot nest /* and */ inside other comment lines. Variables Variables can be of any ColdFusion type, such as numbers, strings, arrays, queries, and COM objects. You can read and write variables within the script region.
PAGE 266

246 Chapter 13 Extending ColdFusion Pages with CFML Scripting if-else: if(expr) statement [else statement] ; if(score GT 1) result = "positive"; else result = "negative"; for loop: for (init-expr ; test-expr ; final-expr) statement ; init-expr and final-expr can be one of the following: • A single assignment expression, for example, x=5 or loop=loop+1 • Any ColdFusion expression, for example, SetVariable("a",a+1) • Empty The test-expr can be one of the following: • Any ColdFusion expression, for example,
PAGE 267

The CFScript Language 247 do-while loop: do statement while (expr) ; // Complete do-while loop on a single line a = ArrayNew(1); loop = 1; do {a[loop] = loop + 5; loop = loop + 1;} while (loop LT 10); // Multiline do-while loop a = ArrayNew(1); loop = 1; do { a[loop] = loop + 5; loop = loop + 1; } while (loop LT 10); switch-case: switch (expr) {case constant : statement break ; default : statement } In this syntax, constant must be a constant (that is, not a variable, a function, or other expression).
PAGE 268

248 Chapter 13 Extending ColdFusion Pages with CFML Scripting continue: skip to next loop iteration for ( loop=1; loop LT 10; loop = loop+1) { if(a[loop] EQ 0) continue; a[loop]=1; } break: break out of the current switch statement or loop indx = 0; for( ; ; ) { indx=indx+1; if(Find("key",strings[indx],1)) break; } return, var: See “Defining and Using Custom Functions” on page 250 Reserved words In addition to the names of ColdFusion functions and words reserved by ColdFusion expressions (such as NOT,
PAGE 269

Interaction of CFScript with CFML 249 Interaction of CFScript with CFML You enclose CFScript regions inside and tags. No other CFML tags are allowed inside a cfscript region. ColdFusion generates an error if a cfscript tag block does not contain at least one CFScript statement, and CFScript comments are not considered statements.
PAGE 270

250 Chapter 13 Extending ColdFusion Pages with CFML Scripting Defining and Using Custom Functions You can define custom functions (also known as user-defined functions) and use them in your application pages as you do standard ColdFusion functions. This allows you to create a function for an algorithm or procedure that you use frequently, and then use the function wherever you need the procedure. If you must change the procedure, you change only one piece of code.
PAGE 271

Defining and Using Custom Functions 251 The following two statements are allowed only in function definitions. Each function must have a return statement: var variableName = initialValue; Creates and initializes a variable that is local to the function (function variable). This variable has meaning only inside the function and is not saved between calls to the function. It has precedence in the function body over any variables with the same name that exist in any other scopes.
PAGE 272

252 Chapter 13 Extending ColdFusion Pages with CFML Scripting Each function has a built-in Arguments array containing all arguments passed to the function: the required arguments specified by the function parameters followed by any additional arguments included in the function call. The function can determine the number of arguments passed to it by using the ColdFusion function call ArrayLen(Arguments). The function must retrieve the optional arguments by using the Arguments array.
PAGE 273

Defining and Using Custom Functions 253 used elsewhere in your application. If a function must use a variable from another scope that has the same name as a function variable, just prefix the external variable with its scope identifier, such as Variables or Form. For example, if you use the variable name x for a function scope (var) variable and for a Variables scope (local) variable in the body of a page that calls the function, the two variables are independent of each other.
PAGE 274

254 Chapter 13 Extending ColdFusion Pages with CFML Scripting Return DollarFormat(totalInterest); } You could use the TotalInterest function in a cfoutput tag of a form’s action page as follows: Loan amount: #Form.Principal#
Annual percentage rate: #Form.AnnualPercent#
Loan duration: #Form.Months# months
TOTAL INTEREST: #TotalInterest(Form.Principal, Form.AnnualPercent, Form.Months)#
Example 2 This function shows the use of optional arguments.
PAGE 275

Defining and Using Custom Functions 255 You can use functions that manipulate many rows of a query outside such tags. There you can pass in a query and loop over it in the function. The following example, which changes text in a query column to uppercase, illustrates using a function to modify multiple query rows. function UCaseColumn(myquery, colName) { var currentRow = 1; for (; currentRow lte myquery.
PAGE 276

256 Chapter 13 Extending ColdFusion Pages with CFML Scripting function makes using the structure appears, but the change the function makes using the directly passed array does not affect the array outside the function. //Create a two-element array inside a structure mystruct = StructNew(); mystruct.myarray = ArrayNew(1);; mystruct.myarray[1] = "This is the original element one"; mystruct.
PAGE 277

Defining and Using Custom Functions 257 } else { // Need to return error value // Caller will look at value and then decide to look at errorInfo // Alternatively, caller can look at errorInfo and see whether // some pre-defined fields are available return -1; // or "" or whatever we have agreed to...
PAGE 278

258 Chapter 13 Extending ColdFusion Pages with CFML Scripting
PAGE 279

Chapter 14 Using Regular Expressions in Functions This chapter describes how regular expressions work in the following ColdFusion functions: • REFind • REFindNoCase • REReplace • REReplaceNoCase This chapter does not apply to regular expressions used in the cfinput and cftextinput tags. These tags use JavaScript regular expressions, which have a slightly different syntax than ColdFusion regular expressions.
PAGE 280

260 Chapter 14 Using Regular Expressions in Functions About Regular Expressions Regular expressions allow you to perform very powerful and flexible string search and replace operations. In traditional search and replace operations, as in the Find and Replace functions of ColdFusion, you must provide the exact text to be searched for. This makes searches for dynamic data very difficult, if not impossible.
PAGE 281

Basic Regular Expression Rules 261 Basic Regular Expression Rules This section describes the basic rules for creating regular expressions (REs), including single-character regular expressions. The following are the basic rules for regular expressions: • Special characters are: + * ? . [ ^ $ ( ) { | \ • Any character that is not a special character matches itself. • A backslash (\) followed by any special character matches the literal character itself, that is, the backslash escapes the special character.
PAGE 282

262 Chapter 14 Using Regular Expressions in Functions This code replaces all the spaces with *, producing this string: Macromedia*Web*Site The following table shows the POSIX character classes that ColdFusion supports: Character Class Matches alpha Matches any letter. Same as [A-Za-z]. upper Matches any uppercase letter. Same as [A-Z]. lower Matches any lowercase letter. Same as [a-z]. digit Matches any digit. Same as [0-9]. alnum Matches any alphanumeric character. Same as [A-Za-z0-9].
PAGE 283

Multicharacter Regular Expressions 263 Multicharacter Regular Expressions You can use the following rules to build multicharacter regular expressions: • Parentheses group parts of regular expressions together into grouped subexpressions that you can be treat as a single unit; for example, (ha)+ matches one or more instances of “ha”.
PAGE 284

264 Chapter 14 Using Regular Expressions in Functions An excellent reference on regular expressions is Mastering Regular Expressions, Jeffrey E. F. Friedl. O’Reilly & Associates, Inc., 1997. ISBN: 1-56592-257-3, http:// www.oreilly.com. Limiting input string size In CFML regular expression functions, large input strings (greater than approximately 20,000 characters) cause a debug assertion failure and a regular expression error occurs.
PAGE 285

Using Backreferences 265 Using Backreferences ColdFusion Server supports backreferencing, which allows you to match text in previously matched sets of parentheses. A slash followed by a digit n (\n) refers to the nth subexpression in parentheses. One use for backreferencing is in searching for doubled words; for example, to find instances of “the the” or “is is” in text.
PAGE 286

266 Chapter 14 Using Regular Expressions in Functions Returning Matched Subexpressions The REFind and REFindNoCase functions allow you to get information about matched subexpressions. If you set these functions’ fourth parameter, ReturnSubExpression, to True, the function returns a CFML structure with two arrays containing the positions and lengths of text strings that match the subexpressions of the first instance of a matched regular expression pattern. The returned structure has two keys, pos and len.
PAGE 287

Regular Expression Examples 267 Regular Expression Examples The following examples show some regular expressions and describe what they match: Expression Description [\?&]value= A URL parameter value in a URL. [A-Z]:(\\[A-Z0-9_]+)+ An uppercase DOS/Windows full path that (a) is not the root of a drive, and (b) has only letters, numbers, and underscores in its text. [A-Za-z][A-Za-z0-9_]* A ColdFusion variable with no qualifier. ([A-Za-z][A-Za-z0-9_]*)(\.
PAGE 288

268 Chapter 14 Using Regular Expressions in Functions Expression Returns REFind ("[Uu]\.?[Ss]\.?[Aa}\.?", Report ) The position in the variable Report of the first occurrence of the abbreviation USA. The letters can be in either case and the abbreviation can have a period after any letter.
PAGE 289

Chapter 15 Indexing and Searching Data You can provide a full-text search capability for documents and data sources on a ColdFusion site by enabling the Verity search engine. ColdFusion 5 supports two Verity search engines: the default Verity search engine (VDK mode) and a restricted version of the Verity K2 Server. The ColdFusion installation and administration documentation provides information about using both engines.
PAGE 290

270 Chapter 15 Indexing and Searching Data Searching a ColdFusion Web Site Until now, you have searched for records in databases based on the value of particular fields using ODBC. However, to efficiently search through paragraphs of text or files of varying types you need full-text search capabilities. The Verity search engines are bundled with ColdFusion to provide full-text indexing and searching.
PAGE 291

Supported File Types 271 Supported File Types The ColdFusion Verity implementation supports a wide array of file and document types. As a result, you can index Web pages, ColdFusion applications, and many binary document types and produce search results that include summaries of these documents. To support multiple WYSIWYG document types, Verity bundles the KeyView Filter Kit. The KeyView Filter Kit includes document filters that support the indexing and viewing of over 45 native document formats.
PAGE 292

272 Chapter 15 Indexing and Searching Data Support for International Languages The ColdFusion International Language Search Pack is not shipped with ColdFusion, but is available on a separate CD-ROM free of charge. To order the Language Search Pack, contact Macromedia Customer Service or visit the online store at http://www.coldfusion.com/store.
PAGE 293

Creating a Searchable Data Source 273 Creating a Searchable Data Source You must do the following steps to create a searchable data source: 1 Create a collection. You can do this either through the ColdFusion Administrator or programmatically. 2 Populate and index the collection. You must select the data and generate the index. You can perform this task either through the ColdFusion Administrator or programmatically.
PAGE 294

274 Chapter 15 Indexing and Searching Data If you checked the option to install the ColdFusion documentation, the documentation collection is listed by default. The Verity engine is used to search the online documents. 2 In the top section of the page, enter a name for the collection. 3 Enter a path for the directory location of the new collection. By default, new collections are added to \Cfusion\Verity\Collections\ in Windows and /opt/coldfusion/verity/collections in UNIX.
PAGE 295

Creating a Searchable Data Source To create a simple collection form page: 1 Open a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: Collection Creation Input Form
Specify a collection
PAGE 296
276 Chapter 15 Indexing and Searching Data
The collection #Form.CollectionName# is created.
The collection #Form.CollectionName# is repaired.
The collection #Form.
PAGE 297

Creating a Searchable Data Source 277 Selecting an indexing method Use the following guidelines to determine which method to use: Use the Administrator if Use the cfindex tag if You want to index document files. You want to index ColdFusion query results. The collection will not be updated frequently. Your collection needs to be updated frequently. You want to generate the collection without writing any CFML code.
PAGE 298

278 Chapter 15 Indexing and Searching Data Using cfindex You can use a form page an action page similar to the following examples to select a collection and index it. To select which collection to index: 1 Open a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: Select the Collection to Index
Specify the index you want to build
PAGE 299
Creating a Searchable Data Source 279 The collection #Form.IndexColl# has been indexed. 3 Save the file as collectionindexaction.cfm. 4 View collectionindexform.cfm in your browser, enter values, and then click Index. Building a search interface After you create and index a searchable data source, you need to build a search interface to allow users to access the data source.
PAGE 300

280 Chapter 15 Indexing and Searching Data value=simple checked> Simple
Explicit

Enter a search string:

3 Save the file as collectionsearchform.cfm.
PAGE 301

Creating a Searchable Data Source 281
3 Save the file as collectionsearchaction.cfm. 4 View the file collectionsearchform.cfm in your browser, enter values in the form, and then submit it. Creating summaries As part of the indexing process, Verity automatically produces a summary of every document file or every query result set that gets indexed. The default summarization selects the best sentences, based on internal rules, up to a maximum of 500 characters.
PAGE 302

282 Chapter 15 Indexing and Searching Data Indexing Query Results The following sections describe the reasons and procedures for indexing the results of database, LDAP, and pop queries. Indexing database query results The main advantage of performing searches against a Verity collection over using cfquery alone is that the database is indexed in a form that provides faster access. Use this technique instead of cfquery in the following cases: • You want to index textual data.
PAGE 303

Indexing Query Results 283 body="MessageText" key="Message_ID" title="Subject" query="Messages"> This cfindex statement specifies the MessageText column as the information to be indexed and names the table’s primary key, the Message_ID column, as the key value. Note that the title attribute names the Subject column. You can use the title attribute to designate an output parameter.
PAGE 304

284 Chapter 15 Indexing and Searching Data #Key#, #Title#, #Body#
Indexing cfpop query results The contents of mail servers are generally quite volatil
PAGE 305

Using Query Expressions 285 type="custom" title="subject" query="p_messages" body="body"> #key#, #title#
Using Query Expressions When you search a Verity collection, you use the cfsearch tag in a ColdFusion application page.
PAGE 306

286 Chapter 15 Indexing and Searching Data A simple query automatically employs the STEM operator and the MANY modifier. STEM searches for words that derive from those entered in the query expression, so entering “find” returns documents that contain “find,” “finding,” “finds,” and so on. The MANY modifier presents the documents returned in the search as a list based on a relevancy score.
PAGE 307

Using Query Expressions 287 Verity Search Operators = MATCHES STARTS > NEAR STEM >= NEAR/N SUBSTRING Accrue OR WILDCARD AND PARAGRAPH WORD Special characters The search engine handles a number of characters in particular ways as described in the following table: Characters Description ,()[ These characters end a text token. =>
PAGE 308

288 Chapter 15 Indexing and Searching Data When you use prefix notation, the expression specifies precedence explicitly. The following example means: Look for documents that contain b and c first, then documents that contain a: OR (a, AND (b,c)) When you use infix notation, precedence is implicit in the expression. For example, the AND operator takes precedence over the OR operator.
PAGE 309

Using Query Expressions 289 Wildcard Description {} Curly braces. Matches any one of a set of patterns separated by a comma, as in “hoist{s, ing, ed}”, which locates “hoists,” “hoisting,” and “hoisted”. ^ Caret. Matches any character not in the set, as in “sl[^ia]m”, which locates “slum” but not “slim” or “slam.” - Hyphen. Specifies a range of characters in a set, as in “c[a-r]t”, which locates every word beginning with “c,” ending with “t,” and containing any letter from “a” to “r.
PAGE 310

290 Chapter 15 Indexing and Searching Data Operators and modifiers The power of the cfsearch tag is in the control it provides over the Verity search engine. The engine offers users a high degree of specificity in setting search parameters. Operators An operator represents logic to be applied to a search element. This logic defines the qualifications that a document must meet to be retrieved. You can use operators to refine your search or to influence the results in other ways.
PAGE 311

Using Query Expressions 291 The following tale describes the evidence operators: Operator Description STEM Expands the search to include the word you enter and its variations. The STEM operator is automatically implied in any simple query. For example, the explicit query expression: believe yields matches such as “believe,” “believing,” and “believer”. WILDCARD Matches wildcard characters included in search strings.
PAGE 312

292 Chapter 15 Indexing and Searching Data The following table describes the proximity operators: Operator Description NEAR Selects documents containing specified search terms. The closer the search terms are to one another within a document, the higher the document’s score. The document with the smallest possible region containing all search terms always receives the highest score. Documents whose search terms are not within 1000 words of each other are not selected.
PAGE 313

Using Query Expressions 293 You use the following operators for numeric and date comparisons: Operator Description = Equals > Greater than >= Greater than or equal to < Less than <= Less than or equal to The following relational operators compare text and match words and parts of words: Operator Description CONTAINS Selects documents by matching the word or phrase you specify with the values stored in a specific document field.
PAGE 314

294 Chapter 15 Indexing and Searching Data Document fields You can specify the values for the cfindex attributes TITLE, KEY, URL, and CUSTOM as document fields for use with relational operators in the criteria attribute. Document fields are referenced in text comparison operators.
PAGE 315

Using Query Expressions 295 key="Identifier" body="TEXT" query="GetText"> Record Counts:
#GetText.RecordCount#
#GetText_Search.RecordCount#
Query Results --- Should be 5 rows
#Identifier#
Search Results -- should be 1 row
#GetText_Search.
PAGE 316

296 Chapter 15 Indexing and Searching Data Score operators Score operators govern how the search engine calculates scores for retrieved documents. The maximum score that a returned search element can have is 1.000. You can set the score percentage display to as many as four decimal places.
PAGE 317

Using Query Expressions 297 Modifiers You combine modifiers with operators to change the standard behavior of an operator in some way. For example, you can use the CASE modifier with an operator to specify that you want to match the case of the search word. The following table describes the available modifiers. Modifier Description CASE Specifies a case-sensitive search.
PAGE 318

298 Chapter 15 Indexing and Searching Data Managing Collections As with any data source, the maintenance requirements of a Verity collection are dictated by the number, frequency, and type of changes that occur in the records. You can run maintenance routines directly from either the cfcollection or cfindex tags or via the Administrator Verity Collections page. For more information on this topic, see the Knowledge Base article “Maintaining Collections” (ID# 1080) at http:// www.coldfusion.
PAGE 319

Managing Collections 299 To restrict access to a collection, follow these steps: 1 In the ColdFusion Administrator, click the Security tab and select Advanced Security > Security Configuration. 2 Select the Use Advanced Server Security box. 3 Click the Submit Changes button. 4 Click the Security Contexts button. 5 Enter a name for the secured collection and click Add Security Context. 6 (Optional) Enter a description for the secured collection.
PAGE 320

300 Chapter 15 Indexing and Searching Data
PAGE 321

Chapter 16 Sending and Receiving E-mail You can add interactive mail features to your ColdFusion applications, providing a complete two-way interface to mail servers via the cfmail tag and the cfpop tag. The boom in Internet mail services makes ColdFusion’s enhanced e-mail capability a vital link to your users. Contents • Using ColdFusion with Mail Servers...................................................................... 302 • Sending E-mail Messages ..................................................
PAGE 322

302 Chapter 16 Sending and Receiving E-mail Using ColdFusion with Mail Servers Adding e-mail to your ColdFusion applications lets you respond automatically to user requests. You can use e-mail in your ColdFusion applications in many different ways. These are just a few examples: • Trigger e-mail messages based on users’ requests or orders. • Allow users to request and receive additional information or documents through e-mail. • Confirm customer information based on order entries or updates.
PAGE 323

Sending E-mail Messages 303 Sending SMTP mail with cfmail The cfmail tag provides support for sending SMTP e-mail from within ColdFusion applications. The cfmail tag is similar to the cfoutput tag, except that cfmail outputs the generated text as SMTP mail messages rather than to a page. The cfmail tag supports all the attributes and commands that you use with cfoutput, including query. To send a simple e-mail message: 1 Create a new file in ColdFusion Studio.
PAGE 324

304 Chapter 16 Sending and Receiving E-mail Sample Uses of cfmail An application page with the cfmail tag dynamically generates e-mail messages based on the tag’s settings.
PAGE 325

Sample Uses of cfmail 305 #ProductRequests.FirstName# #ProductRequests.LastName# (#ProductRequests.Company#) #ProductRequests.EMailAddress#&##013; Regards, The WebMaster webmaster@MyCompany.com Note the use of the cfoutput tag to present a dynamic list embedded within a normal cfmail message. The text within the cfoutput is repeated for each row in the ProductRequests query, while the text above and below it serve as the header and footer, respectively, for the mail message.
PAGE 326

306 Chapter 16 Sending and Receiving E-mail Customizing E-mail for Multiple Recipients In the following example, a query (GetCustomers) is run to retrieve the contact information for a list of customers. This query is then used to send an e-mail to each customer asking the person to verify that the contact information is still valid: PAGE 327
Customizing E-mail for Multiple Recipients 307 Attaching a MIME file You use the cfmailparam tag to attach a file or add a header to a mail message. In the following example, a MIME-encoded file is sent along with an e-mail message: Dear Bob, Here is a copy of the file you requested. Regards, A. Beech PAGE 328
308 Chapter 16 Sending and Receiving E-mail Advanced Sending Options The ColdFusion implementation of SMTP mail uses a spooled architecture. When a cfmail tag is processed in an application page, the messages that are generated are not sent immediately. Instead, they are spooled to disk and processed in the background. This architecture has two distinct advantages: • End users of your application are not required to wait for SMTP processing to complete before a page returns to them.
PAGE 329

Receiving E-mail Messages 309 Receiving E-mail Messages the Post Office Protocol tag, cfpop, expands your ability to add Internet mail client features and e-mail consolidation to applications. While a conventional mail client provides an adequate interface for personal mail, there are many cases in which an alternative interface to some mailboxes is desirable. cfpop is a tool to develop targeted mail clients to suit the specific needs of a wide range of applications.
PAGE 330

310 Chapter 16 Sending and Receiving E-mail cfpop query variables Two variables are returned for each cfpop query that provide record number information: • RecordCount The total number of records returned by the query. • CurrentRow The current row of the query being processed by cfoutput in a query-driven loop. You can reference these properties in a cfoutput tag by prefixing the query variable with the query name in the name attribute of cfpop: This operation returned #Sample.
PAGE 331

Handling POP Mail 311
This example retrieves message header information:
MessageNumber: #HTMLEditFormat(Sample.messageNumber)#
To: #HTMLEditFormat(Sample.to)#
From: #HTMLEditFormat(Sample.from)#
Subject: #HTMLEditFormat(Sample.subject)#
Date: #HTMLEditFormat(Sample.date)#
Cc: #HTMLEditFormat(Sample.
PAGE 332

312 Chapter 16 Sending and Receiving E-mail Retrieving an entire message When you use the cfpop tag with action="GetAll", ColdFusion returns the same columns as with getheaderonly, plus two additional columns, body and header. To retrieve an entire message: 1 Create a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: POP Mail Message Body Example
This example adds retrieval of the message body:
PAGE 333
Handling POP Mail 313 Note that this example does not use a CFML function to encode the body contents. As a result, the browser displays the formatted message as you would normally see it in a mail program that supports HTML messages.
PAGE 334

314 Chapter 16 Sending and Receiving E-mail
Body:
#Sample.body#

Header:
HTMLCodeFormat(Sample.header)#

3 Change the following line so that it refers to a valid POP mail server, as well as to a valid user name and password:
PAGE 335

Handling POP Mail 315 To delete messages: 1 Create a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: POP Mail Message Delete Example
This example deletes messages:
PAGE 336
316 Chapter 16 Sending and Receiving E-mail
PAGE 337

Chapter 17 Managing Files on the Server The cffile, cfdirectory, and cfcontent tags handle browser/server file management tasks. To perform server-to-server operations, use the CFFTP tag, described in “Performing File Operations with cfftp” on page 341. Contents • Using cffile ............................................................................................................... 318 • Uploading Files..................................................................................................
PAGE 338

318 Chapter 17 Managing Files on the Server Using cffile The cffile tag gives you the ability to work with files on your server in a number of ways: • Uploading files from a client to the Web server using an HTML form • Moving, renaming, copying, or deleting files on the server • Reading, writing, or appending to text files on the server You use the action attribute to specify any of the following file actions: upload, move, rename, copy, delete, read, readBinary, write, and append.
PAGE 339

Uploading Files 319 Uploading Files File uploading requires that you create two files: • An HTML form to enter file upload information • An action page containing the file upload code To create an HTML file to specify file upload information: 1 Create a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: Specify File to Upload
Specify File to Upload

PAGE 340
320 Chapter 17 Managing Files on the Server The user can enter a file path or browse the system and pick a file to send. To create an action page to upload the file: 1 Create a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: Upload File
Upload File
You uploaded the file #cffile.ClientFileName#.#cffile.
PAGE 341

Uploading Files 321 Reviewing the code The following table describes the code and its function: Code Description Specify the name of the file to upload. Note that you do not enclose the variable in pound signs. You uploaded the file #cffile.ClientFileName#.#cffile.
PAGE 342

322 Chapter 17 Managing Files on the Server Note Not all browsers support MIME type associations. Example: Restricting file types This cffile specification saves an image file only if it is in the GIF format: This cffile specification saves an image file only if it is in GIF or JPEG format: PAGE 343
Setting File and Directory Attributes 323 Setting File and Directory Attributes In Windows, you specify file attributes using the cffile attributes attribute. In UNIX, you specify file and directory permissions using the cffile and cfdirectory mode attribute. Windows In Windows, you can set the following file attributes: • ReadOnly • Temporary • Archive • Hidden • System • Normal To specify several attributes, use a comma-separated list, such as attributes="ReadOnly,Archive".
PAGE 344

324 Chapter 17 Managing Files on the Server You enter permissions values in the mode attribute for each type of user: owner, group, and other in that order. For example, use the following code to assign read permissions for everyone: mode=444 To give a file or directory owner read/write/execute permissions and read only permissions for everyone else: mode=744 Evaluating the Results of a File Upload After a file upload is completed, you can retrieve status information using file upload variables.
PAGE 345

Evaluating the Results of a File Upload 325 Variable Description fileWasAppended Indicates (Yes or No) whether ColdFusion appended the uploaded file to an existing file. fileWasOverwritten Indicates (Yes or No) whether ColdFusion overwrote a file. fileWasRenamed Indicates (Yes or No) whether the uploaded file was renamed to avoid a name conflict. fileWasSaved Indicates (Yes or No) whether ColdFusion saved a file. oldFileSize Size of a file that was overwritten in the file upload operation.
PAGE 346

326 Chapter 17 Managing Files on the Server Moving, Renaming, Copying, and Deleting Server Files With cffile, you can create application pages to manage files on your Web server. You can use the tag to move files from one directory to another, rename files, copy a file, or delete a file. The examples in the following table show static values for many of the attributes. However, the value of all or part of any attribute in a cffile tag can be a dynamic parameter. This makes cffile a very powerful tool.
PAGE 347

Reading, Writing, and Appending to a Text File 327 Reading, Writing, and Appending to a Text File In addition to managing files on the server, you can use cffile to read, create, and modify text files. As a result, you can do the following things: • Create log files. (You can also use cflog to create and write to log files.) • Generate static HTML documents. • Use text files to store information that can be brought into Web pages. Reading a text file You can use cffile to read an existing text file.
PAGE 348

328 Chapter 17 Managing Files on the Server Writing a text file You can use cffile to write a text file based on dynamic content. For example, you could create static HTML files or log actions in a text file. To create a form in which to enter data for a text file: 1 Open a new file in ColdFusion Studio.
PAGE 349

Performing Directory Operations 329 The text file is written to the location you specified. If the file already exists, it is replaced. You can use cffile action="Append" to append additional text to the end of an existing text file, for example, when you create log files. Performing Directory Operations Use the cfdirectory tag to return file information from a specified directory and to create, delete, and rename directories.
PAGE 350

330 Chapter 17 Managing Files on the Server Modified Attributes Mode #mydirectory.name# #mydirectory.size# #mydirectory.type# #mydirectory.dateLastModified# #mydirectory.attributes# #mydirectory.mode# 3 Modify the line directory="c:\inetpub\wwwroot\mine"so that it points to a directory on your server. 4 Save the file as directoryinfo.
PAGE 351

Chapter 18 Interacting with Remote Servers This chapter describes how ColdFusion wraps the complexity of Hypertext Transfer Protocol (HTTP) and File Transfer Protocol (FTP) communications in a simplified tag syntax that lets you easily extend your site’s offerings across the Web. Contents • Using cfhttp to Interact with the Web.................................................................... 332 • Using the cfhttp Get Method..............................................................................
PAGE 352

332 Chapter 18 Interacting with Remote Servers Using cfhttp to Interact with the Web The cfhttp tag, which enables you to retrieve information from a remote server, is one of the more powerful tags in the CFML tag set. You can use one of two methods to interact with a remote server using the cfhttp tag: Get or Post. • Using the Get method, you can only send information to the remote server directly in the URL. This method is often used for a one-way transaction in which cfhttp retrieves an object.
PAGE 353

Using the cfhttp Get Method 333 Reviewing the code The following table describes the code and its function: Code Description Get the page specified in the URL and make the links absolute instead of relative so that they display properly. #cfhttp.fileContent#
Display the page, which is stored in the variable cfhttp.fileContent, in the browser.
PAGE 354

334 Chapter 18 Interacting with Remote Servers To get a binary file and save it: 1 Open a new file in ColdFusion Studio. 2 Modify the file so that it appears as follows: #cfhttp.MimeType# 3 Change the URL to point to a binary file you want to download. 4 Change the path to point to a path on your hard drive. 5 Save the file as savebinary.
PAGE 355

Creating a Query from a Text File 335 Creating a Query from a Text File You can create a query object from a delimited text file by using the cfhttp tag and specifying method="Get" and the name attribute. This is a powerful method for processing and handling generated text files. After you create the query object, you can easily reference columns in the query and perform other ColdFusion operations on the data.
PAGE 356

336 Chapter 18 Interacting with Remote Servers
Now using replacement column names
Order ID: #ID#
Order Number: #Number#
Order Date: #SDate#
3 Substitute the URL with the location of your text file.
PAGE 357

Using the cfhttp Post Method 337 Using the cfhttp Post Method Use the Post method to send cookie, form field, CGI, URL, and file variables to a specified ColdFusion page or CGI program for processing. For Post operations, you must use the cfhttpparam tag for each variable you want to post. The Post method passes data to a specified ColdFusion page or an executable that interprets the variables being sent and returns data.
PAGE 358

338 Chapter 18 Interacting with Remote Servers 3 Replace the path to the GIF file to a path on your server. 4 Save the file as posttest.cfm in myapps under your Web root directory. Reviewing the code The following table describes the code and its function: Code Description Post an HTTP request to the specified page. Send a cookie in the request.
PAGE 359

Using the cfhttp Post Method 339 The URL variable is: #URL.myurl#
The Cookie variable is: #Cookie.mycookie6#
The CGI variable is: #CGI.mycgi#.
The Formfield variable is: #Form.emailaddress#.
The file was uploaded to #File.ServerDirectory#\#File.ServerFile#. 3 Replace C:\temp\Junk with an appropriate directory path on your hard drive. 4 Save the file as server.cfm in myapps under your Web root directory. 5 View posttest.
PAGE 360

340 Chapter 18 Interacting with Remote Servers To return results of a CGI program: The following code runs the (theoretical) CGI program search.exe on the (equally theoretical) somesiteorother.com site and displays the results, including both the Mime type and Length of the response. The search.exe program must expect a “search” parameter. PAGE 361
Performing File Operations with cfftp 341 Performing File Operations with cfftp The cfftp tag lets you perform tasks on remote servers using File Transfer Protocol (FTP). You can use cfftp to cache connections for batch file transfers. Note To use cfftp, the Enable cfftp Tag option must be selected on the Tag Restrictions page of the Basic Security section of the ColdFusion Administrator Security tab. For server/browser operations, use the cffile, cfcontent, and cfdirectory tags.
PAGE 362

342 Chapter 18 Interacting with Remote Servers
Did the connection close successfully? #cfftp.
PAGE 363

Performing File Operations with cfftp 343 Code Description Use the Myftp connection to get a directory listing. Use the value returned by the last cfftp call (the current directory of the connection) to specify the directory to list. Save the results in a variable named dirlist (a query object). Stop processing if there is an error.
PAGE 364

344 Chapter 18 Interacting with Remote Servers Assigning a cfftp connection to an Application variable could cause problems, since multiple users could access the same connection object at the same time. Creating a Session variable for a cfftp connection makes more sense, because the connection is available to only one client and does not last past the end of the session. Example: Caching a connection PAGE 365
Moving Complex Data Structures Across the Web with WDDX 345 Moving Complex Data Structures Across the Web with WDDX You can move complex data structures across the Web using Web Distributed Data Exchange (WDDX). This capability is based on Extensible Markup Language (XML) 1.0 and you can use it to exchange data between CFML applications and other applications. Additionally, you can use WDDX for server-to-browser and browser-to-server JavaScript data exchanges.
PAGE 366

346 Chapter 18 Interacting with Remote Servers objects on a remote system. Communication between objects on remote systems uses an efficient, special-purpose wire protocol. In the disconnected world, however, these services are a barrier to development. At the most fundamental level, the wire protocols of Distributed COM and CORBA are blocked by most Web firewall software.
PAGE 367

Moving Complex Data Structures Across the Web with WDDX 347 types, and descriptors that allow the data to be manipulated on a target system between arbitrary application servers. When you use WDDX in ColdFusion pages, you typically use the ColdFusion cfwddx tag and the JavaScript utility classes that are installed as /CFIDE/scripts/wddx.js on your local host.
PAGE 368

348 Chapter 18 Interacting with Remote Servers In the CFML implementation, useTimezoneInfo is an attribute of the cfwddx action=cfml2wddx tag. In the JavaScript implementation, useTimezoneInfo (note the case sensitivity of JavaScript) is a property of the WddxSerializer object. Date-time values in WDDX are represented using a subset of the ISO8601 format. Time zone information is represented as an hour/minute offset from UTC; for example, “1998-9-8T12:6:26-4:0”.
PAGE 369

Converting CFML Data to a JavaScript Object 349 Converting CFML Data to a JavaScript Object The following example demonstrates the transfer of a cfquery result set from a CFML page executing on the server to a JavaScript object that is processed by the browser.
PAGE 370

350 Chapter 18 Interacting with Remote Servers Transferring Data from Browser to Server This example serializes form field data, posts it to the server, deserializes it, and outputs the data. For simplicity, only a small amount of data is collected. In applications that generate complex JavaScript data collections, you can extend this basic approach very effectively. Note that this example uses the WddxSerializer JavaScript object to serialize the data, and the cfwddx tag to deserialize the data.
PAGE 371

Transferring Data from Browser to Server // Person info record set with columns firstName and lastName // Make sure the case of field names is preserved var personInfo = new WddxRecordset(new Array("firstName", "lastName"), true); // Add next record to end of personInfo record set function doNext() { // Extract data var firstName = document.personForm.firstName.value; var lastName = document.personForm.lastName.value; // Add names to record set nRows = personInfo.getRowCount(); personInfo.
PAGE 372

352 Chapter 18 Interacting with Remote Servers
Names added so far:
PAGE 398

378 Chapter 20 Using cfobject to Invoke Component Objects Exception handling You can catch exceptions thrown by the CORBA object methods with the cftry and cfcatch tags. However, you cannot extract information from the exception object. Calling Java Objects The cfobject tag can call any Java class that is available on the class path specified on the ColdFusion Administrator JVM and Java Settings page.
PAGE 399

Calling Java Objects 379 FirstName =""; LastName =""; Salary = 0.0f; JobGrade = 0; } public Employee(String First, String Last) { FirstName = First; LastName = Last; Salary = 0.
PAGE 400

380 Chapter 20 Using cfobject to Invoke Component Objects Example: CFML page that uses the Employee class Save the following text as JEmployee.cfm:
PAGE 401

Calling Java Objects 381 • Java method and field names are not case sensitive. Similarly, ColdFusion variables are not case sensitive. As a result, the sample code works even though the CFML uses emp.firstname and emp.lastname, while the Java source code uses FirstName and LastName for these fields. • If you omit a call to the constructor (or, as in this example, comment it out) ColdFusion automatically invokes the default constructor when it first uses the class.
PAGE 402

382 Chapter 20 Using cfobject to Invoke Component Objects Default data type conversion Whenever possible, ColdFusion matches Java types to ColdFusion types as listed in the following table. ColdFusion does not support direct conversion of Date/Time variables and structures.
PAGE 403

Calling Java Objects 383 Example: exception-throwing class The following Java code defines the foo class that throws a sample exception. It also defines a fooException class that extends the Java built-in Exception class and includes a method for getting an error message.
PAGE 404

384 Chapter 20 Using cfobject to Invoke Component Objects Code Description Catch any exceptions and handle them in this block. Get the exception data by calling the CFML GetException function and passing it the Obj object. Set the message variable to the string returned by the exception object’s GetErrorMessage method.
PAGE 405

Calling Java Objects 385 To disable automatic class loading, put all classes in the normal Java class path. Classes located on the Java class path are loaded once per server lifetime and can only be reloaded by stopping and restarting ColdFusion Server. A more complex Java example The following code provides a more complete example of using Java with cfobject. The Example class manipulates integer, float, array, Boolean, and Example object types.
PAGE 406

386 Chapter 20 Using cfobject to Invoke Component Objects String[] ret = new String[arr.length]; for (int i=0; i < arr.length; i++) { ret[arr.length-i-1]=arr[i]; } return ret; } public int Add(int a, int b) { return (a+b); } public float Add(float a, float b) { return (a+b); } public Example Add(Example a, Example b) { return new Example(a.mPublicInt + b.mPublicInt); } static public int SumArray(int[] arr) { int sum=0; for (int i=0; i < arr.
PAGE 407

Calling Java Objects 387 The useExample CFML Page The following useExample.cfm page uses the Example class to manipulate numbers, strings, Booleans, and Example objects. Note the use of the JavaCast CFML function to ensure that CFML variables convert into the appropriate Java data types.
PAGE 408

388 Chapter 20 Using cfobject to Invoke Component Objects
PAGE 409

Chapter 21 Building Custom CFXAPI Tags Sometimes, the best approach is to develop elements of your application by building executables to run with ColdFusion. Perhaps the application requirements go beyond what is currently feasible in CFML. Perhaps you can improve application performance for certain types of processing. To meet these types of requirements, you can use the ColdFusion Extension Application Programming Interface (CFXAPI) to access ColdFusion functions.
PAGE 410

390 Chapter 21 Building Custom CFXAPI Tags What Are CFX Tags? CFX tags are custom tags written against the ColdFusion Extension Application Programming Interface. Generally, you create a CFX if you want to do something that is not possible in CFML, or if you want to improve performance of a repetitive task. CFXs can do the following: • Handle any number of custom attributes. • Use and manipulate ColdFusion queries for custom formatting.
PAGE 411

Before You Begin Developing CFX Tags in Java 391 Before You Begin Developing CFX Tags in Java While implementing CFX tags in Java is easy, you should consider the information in this section before you begin developing them. Sample Java CFXs Before you begin developing a CFX tag in Java, you might want to study sample CFX tags. You can find the Java source files for the examples on Windows in the cfx\java\distrib\examples subdirectory of the main installation directory.
PAGE 412

392 Chapter 21 Building Custom CFXAPI Tags The classes directory created by the ColdFusion setup program serves two purposes: • It contains the supporting classes required for developing and deploying Java CFXs. This is the com.allaire.cfx package located in the cfx.jar archive. • It supports a feature that allows Java CFXs located in the directory to be reloaded every time they are changed.
PAGE 413

Writing a Java CFX 393 Writing a Java CFX To create a Java CFX, you create a class that implements the CustomTag interface. This interface contains one method, processRequest, which is passed Request and Response objects that are then used to do the work of the tag. To create a Java CFX: 1 Create a new source file in your editor. 2 Enter your code. The following code shows how t o create a very simple Java CFX named SimpleJavaCFX that writes a text string back to the calling page: import com.allaire.
PAGE 414

394 Chapter 21 Building Custom CFXAPI Tags This section provides an overview of these object types. For a complete example Java CFX that uses Request, Response, and Query objects, see the “ZipBrowser Example” on page 397. Request object The Request object is passed to the processRequest method of the CustomTag interface. It provides methods for retrieving attributes, including queries, passed to the tag and for reading global tag settings.
PAGE 415

Writing a Java CFX 395 Method Description addRows Adds a new row to the query. setData Sets a data element within the query. For detailed reference information on each of these interfaces, see the CFML Reference. Loading Java CFX classes Each Java CFX class has its own associated ClassLoader that loads it and any dependent classes also located in the classes directory. When Java CFXs are reloaded after a change, a new ClassLoader is associated with the freshly loaded class.
PAGE 416

396 Chapter 21 Building Custom CFXAPI Tags The default value is reload="Auto". This is appropriate for most applications. Use reload="Always" during the development process when you must ensure that you always have the latest class files, even when only a dependent class changed. Use reload="Never" to increase performance by omitting the check for changed classes. Note The reload attribute applies only to class files located in the classes directory.
PAGE 417

ZipBrowser Example 397 ColdFusion processes the page and returns a page that displays the text “Hello, Robert.” If an error is returned instead, check the source code to make sure you have entered it correctly. ZipBrowser Example The following example illustrates the use of the Request, Response, and Query objects. The example uses the java.util.zip package to implement a Java CFX called ZipBrowser, which is a zip file browsing tag.
PAGE 418

398 Chapter 21 Building Custom CFXAPI Tags // read the zip file and build a query from its contents ZipInputStream zin = new ZipInputStream( new FileInputStream(strArchive) ) ; ZipEntry entry ; while ( ( entry = zin.getNextEntry()) != null ) { // add a row to the results int iRow = files.addRow() ; // populate the row with data files.setData( iRow, iName, entry.getName() ) ; files.setData( iRow, iSize, String.valueOf(entry.getSize()) ) ; files.setData( iRow, iCompressed, String.valueOf(entry.
PAGE 419

Approaches to Debugging Java CFXs 399 If you need to debug a Java CFX while running against a live production server, this is the technique you must use. In addition to outputting debug text using the Response.write method, you can also call your Java CFX tag with the debug="On" attribute. This attribute flags the CFX that the request is running in debug mode and therefore should output additional extended debug information.
PAGE 420

400 Chapter 21 Building Custom CFXAPI Tags Debugging classes example The following example demonstrates the use of the debugging classes: import java.util.Hashtable ; import com.allaire.cfx.* ; public class OutputQuery implements CustomTag { // debugger testbed for OutputQuery public static void main(String[] argv) { try { // initialize attributes Hashtable attributes = new Hashtable() ; attributes.put( "HEADER", "Yes" ) ; attributes.
PAGE 421

Developing CFX Tags in C++ 401 Developing CFX Tags in C++ The following sections provide some background to help you develop CFX tags in C++. Sample C++ CFXs Before you begin development of a CFX tag in C++, you might want to study the two CFX tags that are included to give you additional insight into working with the CFXAPI. The two example tags are as follows: • CFX_DIRECTORYLIST Queries a directory for the list of files it contains.
PAGE 422

402 Chapter 21 Building Custom CFXAPI Tags To build a CFX tag: 1 In Visual C++, select File > New, and then click the Projects tab. 2 Select ColdFusion Tag Wizard and enter a tag name of the form CFX_MyNewTag in the Project name box. Click OK to open the wizard. 3 Enter the new tag name as the name of the custom tag. 4 (Optional) Add text that will appear as comments in the tag’s code. 5 Select an MFC usage option and click Finish to generate the code.
PAGE 423

Developing CFX Tags in C++ 403 On UNIX Use the following debuggers and settings for the supported UNIX operating systems: OS Debugger Solaris dbx Other OS-specific requirements The environment variables must include LD_LIBRARY_PATH and CFHOME. Use “stop in main” to set a breakpoint in main. Linux gdb HP-UX DDE The environment variables must include LD_LIBRARY_PATH and CFHOME. Use “break main” to set a breakpoint in main. The environment variables must include SHLIB_PATH and CFHOME.
PAGE 424

404 Chapter 21 Building Custom CFXAPI Tags Registering CFXs To use a CFX tag in your ColdFusion applications, first register it in the Extensions, CFX Tags page in the ColdFusion Administrator. To register a Java CFX: 1 On the ColdFusion Administrator Server tab, select Extensions > CFX Tags to opent the CFX Tags page. 2 Click the Register Java CFX button. 3 Enter the tag name (for example cfx_MyNewTag). 4 Enter the class name (without the .class extension). 5 (Optional) Enter a description.
PAGE 425

Distributing CFX Tags 405 To delete a CFX tag: • Click the Delete Applet (right-most) icon in the Controls column of the Registered CFX Tags list for the tag you want to delete. On Windows NT only, the Visual C++ Custom Tag Wizard automatically registers custom tags so that they can be tested and debugged. Distributing CFX Tags If you are distributing a custom tag, you can automatically register it during the setup process by writing the registration entries directly into the registry.
PAGE 426

406 Chapter 21 Building Custom CFXAPI Tags To import a Java custom tag: 1 Export the custom tag’s registry entry by using the Regedit utility. This creates a file similar to the following: REGEDIT4 [HKEY_LOCAL_MACHINE\SOFTWARE\Allaire\ColdFusion\CurrentVer sion\ CustomTags\CFX_TEST] "ClassName"="ProcessTagRequest" "Description"="Sample CFX tag.
PAGE 427

Index Special #,using 14 , in search expressions 288 A Accessing Client variables 225 collections 298 data sources 21 generated content 187 Action pages 45 Active Server Pages 345 Adding data elements to structures data sources 22 elements to an array 119 Administrative lock management 236 Advanced security, implementing 358 Ancestor tags data access 182 definition 180 AND operator SQL, definition 27 SQL, using 52 Appearance, of graphs 67 Application 215 Application framework about 214 approaches to 217
PAGE 428

408 B Backreferences about 265 in regular expression searches 142 in replacement strings 265 Bar charts, specifying appearance 68 Base tags 180 BETWEEN SQL Operator 27 Binary files, saving 334 break, CFScript statement 248 Browsers cfform considerations 138 displaying e-mail in 309 transferring data to a server 350 Building drop-down list boxes 166 queries 28 search interfaces 52, 279 slider bar controls 164 text entry boxes 165 tree controls 147 Built-in variables Client 225 custom tags 185 Server 232 Ses
PAGE 429

Index 409 interaction with CFScript 249 syntax checker 194 syntax errors 195 CFML expressions,in CFScript 245 CFML functions ArrayAppend 119 ArrayDeleteAt 118 ArrayInsertAt 119 ArrayNew 119 ArrayPrepend 119 ArraySet 121 ArraySort 129 AtructKeyArray 129 CreateTimeSpan 35, 228 DateFormat 94 DeleteClientVarialbesList 226 DollarFormat 94 for arrays 124 for queries 34 for structures 133 formatting data 49 GetClientVarialbesList 226 GetException 382, 384 HTMLEditFormat 311, 353 IsAuthenticated 358, 360 IsAuthor
PAGE 430

410 Class path configuring 391 Java objects and 368 Class reloading, automatifc 395 Classes, debugging 399 Client cookies 222 Client scope 214 Client state management clustering 222 cookies for 222 described 221 enabling 223 Client variables and cflocation tag 226 built-in 225 caching 226 characteristics of 214 configuring 223 creating 224 deleting 226 description 221 exporting from Registry 227 listing 226 setting options for 223 storage 224 storage method 223 using 225 Clustering, client state management
PAGE 431

Index arguments 251 calling 251 defining 250 described 250 error handling 256 evaluating strings 255 examples 253 identifying 253 in Application.
PAGE 432

412 Editions of ColdFusion 4 E-mail attachments 313 checking for spooled 308 customizing 306 deleting 314 error logging 308 for multiple recipients 306 form-based 304 handling POP 310 headers 310 indexing 270, 284 integrating Coldfusion 302 multiple recipients 305 query-based 304 receiving 309 sending 302 undelivered 308 Embedding Java applets 167, 169 URLs in a cftree 152 Enabling access to an existing collection 274 Session variables 228 Encoding custom tags 189 Encrypting application pages 358 Error han
PAGE 433

Index referring to 45 scope of 45, 48 Formatting data items 50 query results 50 Forms about 40 action pages 45 check boxes 84 considerations for 44 creating with cfform 136 deleting data 112 designing 44 drop-down list boxes 166 dynamically populating 82 HTML 40 inserting data 102 Java applets in 167 preserving data 137 requiring entries 89 slider bars 164 text entry boxes 165 tree controls 147 updating data 106 validating data in 91 FROM SQL clause description 27 using 26 FTP actions and attributes 344 ch
PAGE 434

414 Index class loading 395 debugging 398, 399 example 397 importing 406 life cycle of 396 writing 393 Java objects calling 378 considerations 380 exception handling 382 JavaCast CFML function 382 JavaScript differences from CFScript 248 validating with 144 Joining tables 52 Looping through structures 132 K Methods, calling 369 Missing files, exceptions 208 Modes of execution 185 Modifiers, searching 297 MonthAsString CFML function 121 Moving data across the Web 345 server files 326 Multicharacter reg
PAGE 435

Index Post cfhttp method 332, 337 Pound signs, using 14 Precedence rules, search 287 Prefix notation, search strings 287 preservedata cfform attribute 137 Problems, troubleshooting 195 Processing Application.cfm 216 form variables on action pages 45 Java CFX requests 393 OnRequestEnd.
PAGE 436

416 Scopes and custom functions 252 Application 215, 230 Attributes 174, 176 Caller 174, 176 Client 214, 221, 223 File 185 Form 14, 45 local 14 locking 234 managing locking of 237 Request 174 Server 215, 232 Session 214, 221, 228 types 13 URL 14 Variables 14 Variables, and custom tags 172 Score search operators 296 Search and replace 260 Search criteria database retrieval 51 example of 98 multiple 52 Search expressions commas in 288 composing 287 delimiters 288 document fields 294 Search expressions, evide
PAGE 437

Index 417 CFScript 244, 245 SQL 26 Strings evaluating in functions 255 limiting size of 264 storing complex data in 353 StructClear CFML function 130 StructCopy CFML function 130 StructCount CFML function 129 StructDelete CFML function 130 StructFind CFML function 129 StructInsert CFML function 127 StructIsEmpty CFML function 129 StructKeyArray CFML function 129 StructKeyExists CFML function 129 StructKeyList CFML function 129 StructNew CFML function 127 StructUpdate CFML function 128 Structured Query Lan
PAGE 438

418 types of 13 URL 14 using pound signs 14 validating 91 See also Scope, Built-in variables Verbs, SQL 26 Verity about 270 See also Searching, Search expressions Verity wizard 279 Viewing application pages 11 online documentation xix W WDDX and application-level data 347 and Web Services 346 components 346 converting CFML to JavaScript 349 exchanging data 347 operation of 348 purpose of 345 storing data in strings 353 time zone processing 347 transferring data 350 Web accessing with cfhttp 332 applicatio

Employee	Department
#person#	#Departments[person]#