User Guide

Manuals Brands Macromedia Manuals Other COLDFUSION 4.5-DEVELOPING WEB APPLICATIONS

Allaire Corporation

Developing Web

Applications with

ColdFusion

ColdFusion 4.5

Summary of content (380 pages)

PAGE 1

Developing Web Applications with ColdFusion ColdFusion 4.
PAGE 2

Copyright Notice © 1999 Allaire Corporation. All rights reserved. This manual, 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 Allaire Corporation.
PAGE 3

Contents Preface: Welcome to ColdFusion ..................................................................xv Intended Audience.........................................................................................................................xvi Welcome to the ColdFusion 4.5 Web Application Server ...........................................................xvi Products and System Requirements ...........................................................................................
PAGE 4

iv Developing Web Applications with ColdFusion ColdFusion Server .....................................................................................................................6 ColdFusion Administrator........................................................................................................6 Data sources ..............................................................................................................................7 How ColdFusion Server Works ...........................
PAGE 5

Contents Creating Table Joins........................................................................................................................40 Building Flexible Search Interfaces ...............................................................................................40 Code Review ............................................................................................................................41 Returning Query Results to the User...................................................
PAGE 6

vi Developing Web Applications with ColdFusion Access to generated content...................................................................................................84 Installing Custom Tags ...................................................................................................................85 Local tags..................................................................................................................................85 Shared tags.......................................
PAGE 7

Contents Array Functions.............................................................................................................................111 About Structures ...........................................................................................................................113 Structure notation .................................................................................................................113 Creating and Using Structures.................................................
PAGE 8

viii Developing Web Applications with ColdFusion Chapter 11: Indexing and Searching Data .................................................149 Searching a ColdFusion Web Site................................................................................................150 Advantages of using Verity ...................................................................................................150 Online Verity training ....................................................................................
PAGE 9

Contents Choosing a client variable storage method.........................................................................189 Managing Client State in a Clustered Environment ..................................................................190 Using Client State Management..................................................................................................190 Creating a client variable ......................................................................................................
PAGE 10

x Developing Web Applications with ColdFusion Chapter 14: Managing Files on the Server .................................................219 Using CFFILE ................................................................................................................................220 Uploading Files .............................................................................................................................220 Resolving conflicting file names ...............................................
PAGE 11

Contents Chapter 17: Application Security ................................................................263 ColdFusion Security Features......................................................................................................264 Remote Development Services (RDS) Security ..........................................................................264 Overview of User Security ............................................................................................................
PAGE 12

xii Developing Web Applications with ColdFusion CCFXQuery Class ..........................................................................................................................295 Class members.......................................................................................................................295 CCFXQuery::AddRow............................................................................................................296 CCFXQuery::GetColumns..................................
PAGE 13

Contents Invoking Component Objects......................................................................................................327 Coding guidelines..................................................................................................................327 Calling methods ....................................................................................................................327 Calling nested objects ............................................................................
PAGE 14

xiv Developing Web Applications with ColdFusion
PAGE 15

Preface Welcome to ColdFusion This manual describes the process of developing Web applications using ColdFusion. In the first six chapters, you can follow the instructions presented to learn how to create basic ColdFusion applications. Then, chapters seven through 17 cover various topics of interest in enhancing your applications. Finally, chapters 18 through 21 explain how to extend ColdFusion’s capabilities.
PAGE 16

xvi Developing Web Applications with ColdFusion Intended Audience This manual is particularly useful for Web application developers who are new to ColdFusion. In particular, Chapters 1 through 6 provide instructions for creating a basic ColdFusion application. If you are somewhat familiar with ColdFusion, but want to learn more about a particular topic such as sending and receiving email, refer to Chapters 7 through 17.
PAGE 17

Preface xvii Products and System Requirements ColdFusion has been fully tested on the following platforms and with the following configurations. ColdFusion Server 4.5 Enterprise Edition for Windows • Windows NT 4.0 SP4+ • Intel Pentium or above • 150 MB hard disk space • 128 MB RAM (256 MB recommended for clustering) ColdFusion Server 4.5 Enterprise Edition for Solaris • SPARC Solaris 2.5.1, 2.
PAGE 18

xviii Developing Web Applications with ColdFusion ColdFusion Studio 4.5 • Windows 95/98/NT4 • Intel Pentium or above • 35 MB hard disk space • 32 MB RAM (64 MB recommended) New Features in ColdFusion 4.5 A wide range of new features are available in ColdFusion 4.5. New visual tools Universal File Browser — Access all your files from a single explorer that integrates access to the Windows file system, ColdFusion RDS servers, and FTP servers.
PAGE 19

Preface xix Enhancements to CFML Object Scripting — Instantiate and script objects using CFML script in addition to the CFOBJECT tag easier integration with distributed object middleware such as COM and CORBA. Structured Exception Handling — Exception handling now offers hierarchical exception handling that supports both greater customization and greater access to internal exceptions. String Conversion Functions — Convert strings quickly and easily to be compatible with Java Script and XML standards.
PAGE 20

xx Developing Web Applications with ColdFusion Scriptable Performance Metrics — Track key server metrics at run time through your own scripts for intelligent diagnosis of performance bottlenecks of stability problems in your applications. Performance Debugging Data — Access detailed debugging information on the performance of each individual page included in an application page that is being debugged.
PAGE 21

Preface xxi OS Server Sandbox Security — Secure shared hosting environments more easily by creating Server Sandboxes with Windows NT security. OS Server Sandboxes process all requests under the privileges of a designated Windows NT user account (Enterprise Edition for Windows only). Enhanced Advanced Security — Secure CFML functions and enable CFML code segments to be executed using the run-time security permissions of a designated user.
PAGE 22

xxii Developing Web Applications with ColdFusion About ColdFusion Documentation ColdFusion documentation is designed to provide support for all components of the ColdFusion development system. Both the print and online versions are organized to allow you to quickly locate the information you need. In addition to the book set, the documentation is provided in two other formats: • HTML — Browser-based Help references.
PAGE 23

Preface xxiii Using ColdFusion Studio Documents everything you need to know about using ColdFusion Studio, including features like projects, source control integration, as well as the Studio workspace and interface. ColdFusion Quick Reference Guide A valuable quick reference to CFML tags, functions, and variables. ColdFusion Server online documentation To view the HTML documentation, open the following URL: http://127.0.0.1/ cfdocs/dochome.htm.
PAGE 24

xxiv Developing Web Applications with ColdFusion Documentation conventions When reading, please be aware of these formatting cues: • Code samples, filenames, and URLs are set in a monospaced font • Notes and tips are identified by bold type • Bulleted lists present options and features • Numbered steps indicate procedures • Tool button icons are generally shown with procedure steps • Menu levels are separated by the greater than (>) sign • Text for you to type in is set in italics Getting Answers One of
PAGE 25

Preface xxv Technical support Telephone support is available Monday through Friday 8 A.M. to 8 P.M. Eastern time (except holidays) Toll Free: 888.939.2545 (U.S. and Canada) Tel: 617.761.2100 (outside U.S. and Canada) For complete details about Allaire Product Support options, please refer to the Allaire Support pages on the Allaire web site: http://www.allaire.com/support. Postings to the ColdFusion Support Forum (http://forums.allaire.com) can be made any time. Sales Toll Free: 888.939.2545 Tel: 617.
PAGE 26

xxvi Developing Web Applications with ColdFusion
PAGE 27

CHAPTER 1 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 • What You Should Already Know........................................................................ 2 • What is ColdFusion?......................
PAGE 28

2 Developing Web Applications with ColdFusion A Quick Web Overview Over the last few years, the Web has 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 ecommerce to managing internal business processes.
PAGE 29

Chapter 1: Introduction to ColdFusion 3 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 30

4 Developing Web Applications with ColdFusion Rapid development The ColdFusion development platform enhances the speed and ease of development through the following features: • A tag-based server scripting language that is powerful and intuitive. • Two-way visual programming and database tools. • Remote interactive debugging for quickly identifying and fixing problems. • Web application wizards to automate common development tasks. • Source control integration to enable team development.
PAGE 31

Chapter 1: Introduction to ColdFusion 5 Complete security ColdFusion provides a foundation for building secure applications through the following features: • Integration with existing authentication systems including Windows NT domain and LDAP directory servers, and proprietary user and group databases. • Advanced access control so that server administrators can control developers’ access to files and data sources. • Support for existing database security.
PAGE 32

6 Developing Web Applications with ColdFusion ColdFusion Studio ColdFusion Studio is the development environment for ColdFusion Server. It offers visual development tools, including dynamic page previews using your Web browser, an interactive debugger, a query builder, an expression builder, project management and source control tools, and many other productivity enhancements. To learn more about ColdFusion Studio, see Using ColdFusion Studio.
PAGE 33

Chapter 1: Introduction to ColdFusion 7 Data sources ColdFusion applications may interact with any database that supports the ODBC standard. However, ColdFusion is not limited to ODBC data sources. You can also retrieve data using OLE-DB, native database drivers, or directory servers that support the Lightweight Directory Access Protocol (LDAP). Data can also be retrieved from mail servers that support the Post Office Protocol (POP), and which is indexed in Verity collections.
PAGE 34

8 Developing Web Applications with ColdFusion
PAGE 35

CHAPTER 2 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 • Writing Code..................................................................................................... 10 • Saving Application Pages................................
PAGE 36

10 Developing Web Applications with ColdFusion The Development Process Whether you are creating a static HTML page or a ColdFusion application page, you follow the same iterative process: • Write some code. • Save the code to a document or page. • View the page in a browser. • Modify the page. • Save the page again. • View it in a browser. • and so on...
PAGE 37

Chapter 2: Writing Your First ColdFusion Application 11 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. Save ColdFusion application pages underneath the Web root or another Web server mapping so that the Web server can publish these pages to the Internet.
PAGE 38

12 Developing Web Applications with ColdFusion 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’s returned to the browser.
PAGE 39

Chapter 2: Writing Your First ColdFusion Application 13 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 can be used in applications. As with other programming languages, you’ll set variables in ColdFusion to store data that you want to access later. And you’ll reference a range of variables to perform different types of application processing.
PAGE 40

14 Developing Web Applications with ColdFusion Adding More Variables to the Application Applications can use many different variables. For example, the calldept.cfm application page can set and display values for department, city, and salary. To modify the application: 1. Return to the file calldept.cfm in ColdFusion Studio, 2.
PAGE 41

CHAPTER 3 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 42

16 Developing Web Applications with ColdFusion 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 43

Chapter 3: Querying a Database 17 Data can be organized in multiple tables. This type of data structure is known as a relational database and is the type used for all but the simplest data sets. From this basic description, a few database design rules emerge: • Each record should contain a unique identifier, known as the primary key. This could be an employee ID, a part number, or a customer number.
PAGE 44

18 Developing Web Applications with ColdFusion Understanding Data Sources A database is a file or server that contains a collection of data. A data source is a pointer from ColdFusion to a specific database. You add data sources to your ColdFusion Server so that you can point to the databases that you want to connect to from your ColdFusion applications. Open Database Connectivity (ODBC) ODBC is a standard interface for connecting to a database from an application.
PAGE 45

Chapter 3: Querying a Database 19 Adding Data Sources You add data sources in the ColdFusion Administrator to define connection requirements for database access. 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. To add a data source: 1. Start the ColdFusion Administrator.
PAGE 46

20 Developing Web Applications with ColdFusion The data source is added to the data source list. 9. Locate CompanyInfo in the data source list. 10. Choose Verify to run the verification test on the data source. If the data source was created, you should see this message: The connection to the data source was verified successfully. For more information about managing data sources, See Administering ColdFusion Server.
PAGE 47

Chapter 3: Querying a Database 21 • Performs SQL commands that are enclosed within the block. • Returns query variable values to the page. CFQUERY tag syntax You’ll type SQL here In this example, the query code tells ColdFusion to: • Use the CompanyInfo data source to connect to the company.mdb database. • Store the retrieved data in the query variable EmpList.
PAGE 48

22 Developing Web Applications with ColdFusion When the database processes the SQL, it creates a data set that is returned to ColdFusion Server. ColdFusion places the data set in memory and assigns it the name that you defined for the query in the begin CFQUERY tag. You may reference that data set by name using the CFOUTPUT tag further down on the page. Basic SQL Syntax elements The following sections present brief descriptions of the main SQL command elements.
PAGE 49

Chapter 3: Querying a Database 23 Operators These specify conditions and perform logical and numeric functions: Basic SQL Operators Operator Description AND Both conditions must be met, such as Paris AND Texas OR At least one condition must be met, such as Smith OR Smyth NOT Exclude the condition following, such as Paris NOT France = Equal to <> Not equal to < Less than > Greater than <= Less than or equal to >= Greater than or equal to + Addition - Subtraction / Division * Mul
PAGE 50

24 Developing Web Applications with ColdFusion 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. 2. Edit the page so that it appears as follows: Employee List
Employee List
SELECT FirstName, LastName, Salary, Contract FROM Employees 4 4 4 4 3.
PAGE 51

Chapter 3: Querying a Database 25 Query Notes and Considerations When creating queries to retrieve data, keep these guidelines in mind: • Enter the query NAME and DATASOURCE attributes in the begin CFQUERY tag. • Surround attribute settings with double quotes("). • Reference the query data by naming the query in the CFOUTPUT tag later on the page. • Make sure that a data source exists in the ColdFusion Administrator before you reference iit n a CFQUERY tag.
PAGE 52

26 Developing Web Applications with ColdFusion 4 4 #FirstName#, #LastName#, #Salary#, #Contract#
3. Save the file as emplist.cfm. 4. View the page in a browser. A list of employees appears in the browser, with each line displaying one row of data. You have created a ColdFusion application page that retrieves and displays data from a database. At present, the output is raw. You will learn how to format the data in the next chapter.
PAGE 53

Chapter 3: Querying a Database 27 • When outputting the data itself, you define the variable name using the QUERY attribute. • When outputting query properties variables, don’t use the QUERY attribute; instead, prefix the variable reference with the name of the query, for example, EmpList.RecordCount. • Columns must exist and be retrieved to the application in order to output their values. • As with other attributes, surround the QUERY value with double quotes (").
PAGE 54

28 Developing Web Applications with ColdFusion 4 4 4 The query returned #EmpList.RecordCount# records. 3. Save the file as emplist.cfm. 4. View the page in a browser. The number of employees now appears below the list of employees. Code Review You now display the number of records retrieved in the query. Code Description Display what follows The query returned Display the text "The query returned" #EmpList.
PAGE 55

CHAPTER 4 Chapter 4 Retrieving and Formatting the Data You Want 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.................................................. 30 • Processing Form Variables on Action Pages...................................................
PAGE 56

30 Developing Web Applications with ColdFusion Using Forms to Specify the Data to Retrieve Until now, you’ve retrieved all of the records from a table. However, there are many instances when you’ll want to retrieve data based on certain criteria. For example, you may 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 57

Chapter 4: Retrieving and Formatting the Data You Want HTML Form Controls Control Code Text control Radio buttons DisplayName1 DisplayName2 DisplayName3 Select box
Department:
Training
Sales
Marketing

Contractor? Yes
PAGE 74

48 Developing Web Applications with ColdFusion Searching numeric values Suppose you want a user to select one or more departments using checkboxes. You query the database to retrieve detailed information on the selected department(s).
PAGE 75

Chapter 5: Making Variables Dynamic 49 The first example searched for department information based on a numeric primary key field called "Department_ID." Suppose, instead, that the primary key is a database field called "DepartmentName" that contains string values. In that case, it’s necessary to make the following modifications: • Make the value attribute of the checkboxes equal to the string value. • Enclose the value attribute in single quotes.
PAGE 76

50 Developing Web Applications with ColdFusion multiple select list is a comma-delimited list of the entries selected by the user. For example, a multiple select list contains four entries: Training, Marketing, HR, and Sales. The user selects Marketing and Sales. The value of the form field variable is then ’Marketing’, ’Sales’. Just as you can with checkboxes, you can also query with multiple select lists by searching a database field that contains either numeric values or string values.
PAGE 77

Chapter 5: Making Variables Dynamic 51
PAGE 78

52 Developing Web Applications with ColdFusion There are two ways to use the CFPARAM tag, depending on how you want the validation test to proceed. • Use CFPARAM with only the NAME attribute to test that a required variable exists. If it does not exist, the ColdFusion server stops processing the page. • Use CFPARAM with both the NAME and DEFAULT attributes to test for the existence of an optional variable. If the variable exists, processing continues and the value is not changed.
PAGE 79

Chapter 5: Making Variables Dynamic 53 Example: Checking data types 3. Save the page as askemp.cfm. Once you have created the input form, you can then create the action page to process the user’s request. This action page will determine where the user has entered search criteria and search based only on those criteria. To create the action page: 1.
PAGE 82

56 Developing Web Applications with ColdFusion

First Name Last Name Salary Contractor

#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. The results should meet the criteria you specify.
PAGE 83

Chapter 5: Making Variables Dynamic 57 CFML Code Description AND Employees.LastName LIKE ’#form.LastName#%’ If the user entered anything in the LastName text box in the form, add "AND Employees.LastName LIKE ‘[what the user entered in the LastName text box]%'" to the SQL statement. AND Employees.Salary >= #form.Salary# If the user entered anything in the Salary text box in the form, add "AND Employees.
PAGE 84

58 Developing Web Applications with ColdFusion
PAGE 85

CHAPTER 6 Chapter 6 Updating Your Data This chapter describes how to insert, update, and delete data in a database with ColdFusion. Contents • Inserting Data ................................................................................................... 60 • Creating an HTML Insert Form....................................................................... 60 • Creating an Action Page to Insert Data........................................................... 61 • Updating Data ................
PAGE 86

60 Developing Web Applications with ColdFusion Inserting Data Inserting data into a database is usually done with two application pages: • An insert form • An insert action page You can create an insert form with CFFORM tags (see “Creating Forms with the CFFORM Tag” on page 124) or with standard HTML form tags. When the form is submitted, 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 87

Chapter 6: Updating Your Data 61 3. Save the file as insertform.cfm in the myapps directory. 4. View insertform.cfm in a browser. Data Entry Form Notes and Considerations Creating data entry fields for an HTML form is very simple: • You need only create the HTML form fields for each database field into which you want to insert data. • The names of your form fields must be identical to the names of your database fields.
PAGE 88

62 Developing Web Applications with ColdFusion 3. Save the page. as insertpage.cfm. 4. View insertform.cfm in a browser, enter values, and click the Submit button. 5. The data is inserted into the Employees table and the message appears. To create an insert page with CFQUERY: 1. Create a new application page in Studio. 2. Enter the following code: 4 4 4 4 4 INSERT INTO Employees (Fi’, ’#Form.LastName#’, ’#Form.
PAGE 89

Chapter 6: Updating Your Data 63 Creating an Update Form An update form is similar to an insert form, but there are two key differences: • An update form contains a reference to the primary key of the record that is being updated. A primary key is a field or combination of fields in a database table that uniquely identifies each record in the table. For example, in a table of employee names and addresses, only the Employee_ID would be unique to each record.
PAGE 90

64 Developing Web Applications with ColdFusion 3. Save the page. as updatedorm.cfm. 4. View updateform.cfm in a browser. Code Review Code Description SELECT * FROM Employees WHERE Employee_ID = #URL.Employee_ID# Query the CompanyInfo datasource and return the records in which the employee ID matches what was entered in the URL.
PAGE 91

Chapter 6: Updating Your Data 65 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. 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 all of the fields that make up the primary key in your form submittal.
PAGE 92

66 Developing Web Applications with ColdFusion 4 4 4 4 4 4 UPDATE Employees SET Firstname=’#Form.Firstname#’, LastName=’#Form.LastName#’, Department_ID=’#Form.Department_ID#’ StartDate=’#Form.StartDate#’> Salary=#Form.Salary#> WHERE Employee_ID=#Employee_ID#
Employee Added
You have updated the information for #Form.FirstName# #Form.LastName# in the Employees database. 3. Save the page. as updatepage.cfm. 4. View updateform.
PAGE 93

Chapter 6: Updating Your Data 5. 67 Enter the following code: DELETE FROM Employees WHERE Employee_ID = #URL.EmployeeID# Delete Employee Record
The employee record has been deleted.
6. Save the page. as deletepage.cfm. 7. View deleteform.cfm in a browser, enter values, and click the Submit button.
PAGE 94

68 Developing Web Applications with ColdFusion example, if you want the error message to read "You must enter your first name," use the syntax: Validating the Data That Users Enter in Form Fields Another limitation of 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 95

Chapter 6: Updating Your Data To validate the data users enter in the Insert Form 1. Open the file insertform.cfm in Studio. 2. Modify the file so that it appears as follows: Insert Data Form
Insert Data Form

PAGE 96
70 Developing Web Applications with ColdFusion
3. Save the file. The VALUE attribute is optional. A default message displays if no value is supplied. When the form is submitted, ColdFusion scans the form fields to find any validation rules you specified. The rules are then used to analyze the user’s input.
PAGE 97

CHAPTER 7 Chapter 7 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 ......................................................................................... 72 • Reusing Common Code with CFINCLUDE.................................................... 72 • About Custom Tags in CFML...........................................................................
PAGE 98

72 Developing Web Applications with ColdFusion Ways to Reuse Code ColdFusion provides several different ways to reuse code. If you are using ColdFusion Studio, you can write code snippets, which you can copy into templates. For more information on writing code snippets, see Using ColdFusion Studio. You can include a template within another template with the CFINCLUDE tag. In addition, you can create custom tags in CFML.
PAGE 99

Chapter 7: Reusing Code 73 About Custom Tags in CFML Custom tags wrap functionality in a page that can be called from a ColdFusion application page. ColdFusion custom tags built in CFML allow for rapid application development and code re-use while offering off-the-shelf solutions to many programming chores. An online RealVideo title called "Creating Custom Tags" is available at the Allaire Alive section of our Web site.
PAGE 100

74 Developing Web Applications with ColdFusion Defining attributes CFML custom tags support both required and optional attributes. Attributes are defined as name-value pairs. Custom tag attributes conform to CFML coding standards: • ColdFusion passes any attributes in the ATTRIBUTES scope. • Use the CFPARAM tag at the top of a custom tag to test for and assign defaults for each attribute that may be passed from a calling template. • Use the ATTRIBUTES.
PAGE 101

Chapter 7: Reusing Code 75 Enter Name 4 Before you leave this page, you’re #NameYouEntered#.
PAGE 102

76 Developing Web Applications with ColdFusion 7. Open the file callingpage.cfm in your browser. The calling page uses the getmd custom tag and displays the results. Code Review Code Description In the calling page, create a variable NameYouEntered and assign it the value "Smith." In the calling page, call the getMD custom tag and pass it the NAME parameter whose value is the value of the variable NameYou Entered.
PAGE 103

Chapter 7: Reusing Code 77 Nesting Custom Tags ColdFusion lets you turn a custom tag into a special kind of container that can enclose additional custom tags, which allows you to nest tags. Base tags are also know as ancestors or parent tags, while the tags that base tags call are known as sub tags, descendants, or child tags.
PAGE 104

78 Developing Web Applications with ColdFusion 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 and without violating the encapsulation of a tag’s implementation outside the circle of its collaborating tags.
PAGE 105

Chapter 7: Reusing Code 79 When CFASSOCIATE is encountered in a sub tag, the sub tag’s attributes are automatically saved in the base tag. The attributes are in a structure appended to the end of an array whose name is ‘ThisTag.collection_name'. The default value for the DataCollection attribute is ‘AssocAttribs'. This attribute should be used only in cases where the base tag can have more than one type of sub tag. It is convenient for keeping separate collections of attributes, one per tag type.
PAGE 106

80 Developing Web Applications with ColdFusion Example: Ancestor data access This example was snipped from a custom tag. I’m not nested inside any custom tags. :^(
Passing Custom Tag Arguments via CFML Structures Attributes can be passed to custom tags via the reserved attribute ATTRIBUTECOLLECTION. ATTRIBUTECOLLECTION must reference a structure.
PAGE 108

82 Developing Web Applications with ColdFusion Examples Via CFMODULE Via shorthand Accessing attributes within the custom tag If testtwo.cfm contains this CFML: ---custom tag ---
#attributes.a# #attributes.
PAGE 109

Chapter 7: Reusing Code 83 • AssocAttribs — holds the attributes of all nested tags if CFASSOCIATE was used them. Pattern of execution The same CFML template is executed for both the start and end tag of a custom tag.
PAGE 110

84 Developing Web Applications with ColdFusion Terminating tag execution CFEXIT terminates execution of a custom tag. CFEXIT’s METHOD attribute specifies where execution continues. CFEXIT can specify that processing continues from the first child of the tag or continues immediately after the end tag marker. The METHOD attribute can also be used to specify that the tag body should be executed again. This enables custom tags to act as high-level iterators, emulating CFLOOP behavior.
PAGE 111

Chapter 7: Reusing Code 85 ’> Installing Custom Tags Custom tags are just like other .cfm files except that they must be installed in a specific location to be accessible from the calling template. Because ColdFusion loads the first instance it finds of the custom tag called by a template, you should avoid placing copies of a custom tag in different locations.
PAGE 112

86 Developing Web Applications with ColdFusion CFMODULE Attributes Attribute Description Template Required if the NAME attribute is not used. Specifies a relative path to the cfm file. Same as TEMPLATE attribute in CFINCLUDE. Note that the directory must have a mapping defined in ColdFusion Administrator Example: identifies a custom tag file in the parent directory. Name Required if Template attribute is not used.
PAGE 113

Chapter 7: Reusing Code 87 The following options are supported: cfencode Command Line Options Option Description input file Name of the file you want to encode. cfencode will not process an encoded file. output file Path and filename of the output file. Warning: If you don’t specify an output file name, a warning message asks if you want to continue, in which case the encoded file will overwrite the source file.
PAGE 114

88 Developing Web Applications with ColdFusion
PAGE 115

CHAPTER 8 Chapter 8 Debugging and Error Handling ColdFusion includes sophisticated debugging and code validation tools. This chapter gives an overview of the debugging options available in the ColdFusion Administrator and how to enable CFML attribute validation. In addition, the ColdFusion Server offers a means to catch and process exceptions in ColdFusion application pages, through the CFTRY, CFCATCH, and CFTHROW tags.
PAGE 116

90 Developing Web Applications with ColdFusion Debug Settings in the ColdFusion Administrator ColdFusion can provide important debugging information for every application page requested by a browser. When enabled, debugging output is shown in a block following normal page output. For detailed information on the debugging and logging settings in the ColdFusion Administrator, see Administering ColdFusion Server .
PAGE 117

Chapter 8: Debugging and Error Handling Tip 91 If you get a message that does not explicitly identify the cause of the error, check on key system parameters like available memory and disk space. For information on using the Logging settings and Mail Logging settings, see Administering ColdFusion Server. CFML Code Validation The ColdFusion Application Server features two modes of attribute checking for processing application pages: strict and relaxed.
PAGE 118

92 Developing Web Applications with ColdFusion Connection errors may include problems with the location of files, network connections, and database client library configuration. First, verify that you can connect to the database by clicking the Verify button on the ODBC Data Sources page of the ColdFusion Administrator. If you are unable to make a simple connection from that page, you need to work with your database and/or driver vendor to solve the problem.
PAGE 119

Chapter 8: Debugging and Error Handling 93 Generating Custom Error Messages (CFERROR) ColdFusion displays error pages that can help you to debug your application. There are four types of errors in ColdFusion: • REQUEST — Request errors occur when a application page is requested and there is an error in the page's code. • VALIDATION — Validation errors occur when a user violates the form field validation rules during a form submittal. • EXCEPTION — Exception errors handle exceptions.

PAGE 120

94 Developing Web Applications with ColdFusion

An error occurred when you requested this page. Please email the Webmaster to report this error. We will work to correct the problem and apologize for the inconvenience.

Error Information
#Error.DateTime#
#Error.Template#
#Error.RemoteAddress#
#Error.

Chapter 8: Debugging and Error Handling Note 95 For cases when the error handler is not able to successfully handle the thrown error, use the CFRETHROW tag within a block. ... Add code here ... ... Add exception processing code here ... ... Add exception processing code here ... ... Add exception processing code here ...

PAGE 122

96 Developing Web Applications with ColdFusion Types of recoverable exceptions Type Tag(s) Notes Application-defined exception events CFTHROW CFCATCH TYPE="Application" CFCATCH TYPE="Any" a CFCATCH block that has no TYPE attribute Raise exceptions using the CFTHROW tag (with an optional diagnostic message), then catch using CFCATCH.

PAGE 123

Chapter 8: Debugging and Error Handling 97 Specifying the type as ANY causes the ColdFusion Application Server to catch internal exceptions, memory allocation errors, and access violations, which you may not be prepared to handle. Applications can optionally use the CFTHROW tag to raise custom exceptions.

PAGE 124

98 Developing Web Applications with ColdFusion Exception Property Variables (Continued) Property variable Description CFCATCH.ERRORCODE Any exception that is a part of the CFML exception hierarchy supplies a value for this variable. For TYPE="Application" CFTHROW tags may supply a value for this code via the ERRORCODE attribute. For Type="Database"CFCATCH.ERRORCODE has the same value as CFCATCH.SQLSTATE. Otherwise, the value of CFCATCH.ERRORCODE is the empty string. CFCATCH.

PAGE 125

Chapter 8: Debugging and Error Handling 99 Database exceptions For database exceptions, ColdFusion supplies some additional diagnostic information. The following variables are available whenever the exception type is database: Property variable Description CFCATCH.NATIVEERRORCODE The native error code associated with this exception. Database drivers typically provide error codes to assist in the diagnosis of failing database operations. The values assumed by CFCATCH.

PAGE 126

100 Developing Web Applications with ColdFusion MissingInclude exceptions For exceptions related to missing files, where the type of exception is MissingInclude, the following variable is available: Property variable Description CFCATCH.MISSINGFILENAME The name of the file missing in an exception of type MissingInclude. Exception handling strategies Use CFTRY with CFCATCH to handle exceptions based on their point of origin within an application page, or based on diagnostic information.

PAGE 127

Chapter 8: Debugging and Error Handling 101 Test CFTRY/CFCATCH

Department: #DepartmentID#

Last Name: #LastName#

First Name: #FirstName#

PAGE 138

112 Developing Web Applications with ColdFusion Array Functions (Continued) Function Description ArrayResize Resets an array to a specified minimum number of elements. ArraySet Sets the elements in a 1D array in a specified range to a specified value. ArraySort Returns the specified array with elements sorted numerically or alphanumerically. ArraySum Returns the sum of values in the specified array. ArraySwap Swaps array values in the specified indexes.

PAGE 139

Chapter 9: Handling Complex Data with Structures 113 About Structures ColdFusion supports the creation and handling of structures, which enable developers to create and maintain key-value pairs. A structure lets you build a collection of related variables that are grouped under a single name. Structures can also be used as associative arrays. You can define ColdFusion structures dynamically. You can use structures to refer to related string values as a unit rather than individually.

PAGE 140

114 Developing Web Applications with ColdFusion Creating and Using Structures This section explains how to use the structure functions to create and use structures in ColdFusion. The sample structure is called employee, and is used to add new employees to a corporate information system.

PAGE 141

Chapter 9: Handling Complex Data with Structures "lastname", "#FORM.lastname#")> "email", "#FORM.email#")> "phone", "#FORM.phone#")> "department", "#FORM.

PAGE 142

116 Developing Web Applications with ColdFusion But if the key is dynamic, or contains special characters, you must use the StructKeyExists function: Getting a list of keys in a structure To get a list of the keys in a CFML structure, you use the StructKeyList function: The delimiter can be any delimiter, but the default is a comma ( , ).

PAGE 143

Chapter 9: Handling Complex Data with Structures 117 Structure Example Structures are particularly useful for grouping together a set of variables under a single name. In the following example files, structures are used to collect information from a form, structinsert.cfm, and to submit that information to a custom tag at addemployee.cfm. These example files show how you can use a structure to pass information to a custom tag, named CF_ADDEMPLOYEE. Example file structinsert.

PAGE 144

118 Developing Web Applications with ColdFusion

PAGE 146

120 Developing Web Applications with ColdFusion called person to hold value of key as loop runs --->

#person#

#Departments[person]#

Structure Functions There are several functions that help you create and manage structures in ColdFusion applications. Structure Functions Function Description IsStruct Returns TRUE if the specified variable is a structure.

PAGE 147

Chapter 9: Handling Complex Data with Structures 121 Structure Functions (Continued) Function Description StructNew Returns a new structure. StructUpdate Updates the specified key with the specified value. Note that in all cases, except StructDelete, an exception will be thrown if the referenced key or structure does not exist. For more information on these functions, see the CFML Language Reference.
PAGE 148

122 Developing Web Applications with ColdFusion
PAGE 149

CHAPTER 10 Chapter 10 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. These controls can be enabled without the need to code Java directly. Contents • Creating Forms with the CFFORM Tag......................................................... 124 • Input Validation with CFFORM Controls .....................................................
PAGE 150

124 Developing Web Applications with ColdFusion Creating Forms with the CFFORM Tag You’ve already learned how to use HTML forms to gather user input. (See “Using Forms to Specify the Data to Retrieve” on page 30.) This chapter shows you how to use the CFFORM tag to create dynamic forms in CFML.
PAGE 151

Chapter 10: Building Dynamic Forms 125 CFFORM Controls (Continued) Control Description CFTREE and CFTREEITEM Java applet-based controls used to define a tree control and individual tree control items. CFTEXTINPUT A Java applet-based control used to define a text input box. CFSELECT Used to define a drop-down list box. CFAPPLET Used to embed your own Java applets.
PAGE 152

126 Developing Web Applications with ColdFusion Input Validation with CFFORM Controls The CFINPUT and CFTEXTINPUT tags include the VALIDATE attributes which allows you to specify a valid data type entry for the control. You can validate user entries on the following data types. Input Validation Controls VALIDATE Entry Description Date Verifies US date entry in the form mm/dd/yyy. Eurodate Verifies valid European date entry in the form dd/mm/ yyyy. Time Verifies a time entry in the form hh:mm:ss.
PAGE 153

Chapter 10: Building Dynamic Forms 127 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: • CFINPUT • CFSLIDER • CFTEXTINPUT • CFTREE JavaScript objects passed to the validation routine The following JavaScript objects are passed by ColdFusion to the JavaScript funct
PAGE 154

128 Developing Web Applications with ColdFusion To use JavaScript to validate form data: 1. Create a new file in Studio. 2. Edit the page so that it appears as follows: JavaScript Validation 4 ONVALIDATE="testbox" Text box control parameter that calls the JavaScript test. See the following Web site for information on JavaScript validation scripts: • http://www.dannyg.
PAGE 156

130 Developing Web Applications with ColdFusion 4 4 4 4 QUERY="engquery" QUERYASROOT="yes" IMG="folder,document"> 3. Save the page and view it in your browser. Code Review Code Description Allow vertical scrolling.
PAGE 157

Chapter 10: Building Dynamic Forms 131
3. Save the page and view it in your browser.
PAGE 158

132 Developing Web Applications with ColdFusion • form.treename.path — Returns the complete path of the user selection, in the form: root\node1\node2\node_n\value The root part of the path is only returned if you set the COMPLETEPATH attribute tof CFTREE to YES; otherwise, the path value starts with the first node. In the previous example, if the user selects the name "John Allen" in this tree, the following form variables are returned by ColdFusion: form.tree1.node = John Allen form.tree1.
PAGE 159

Chapter 10: Building Dynamic Forms 133 Example: Multi-level tree control When populating a CFTREE, you manipulate the structure of the tree by specifying a TREEITEM parent. In this example, every TREEITEM, except the top level, specifies a parent. The PARENT attribute allows your CFTREE to show the relationships between elements in the tree control. PAGE 160
134 Developing Web Applications with ColdFusion The built-in image names are: • cd • computer • document • element • folder • floppy • fixed • remote 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. To embed links in a CFTREE: 1. Open a new file named tree3.cfm in Studio. 2.
PAGE 161

Chapter 10: Building Dynamic Forms 135 Code Review Code Description HREF="http://www.allaire.com"> Make the node of the tree a link. HREF="http://forums.allaire.com" Make the node of the tree a link. Note HREF can refer to the name of a column in a query if the tree item is populated from that query.
PAGE 162

136 Developing Web Applications with ColdFusion Populating a grid from a query To populate a grid from a query: 1. Open a new file named grid1.cfm in Studio. 2. Edit the file so that it appears as follows: SELECT * FROM Employees PAGE 163
Chapter 10: Building Dynamic Forms 137 Code Review Code Description Allow the user to select only one cell.
PAGE 164

138 Developing Web Applications with ColdFusion Editing data in a CFGRID To enable grid editing, you use the SELECTMODE="EDIT" attribute. When enabled, a user can edit cell data and insert or delete grid rows. When a CFFORM containing a CFGRID is submitted, data about changes to grid cells are stored in one-dimensional arrays you can reference like any other ColdFusion array. To make the grid editable: 1. Open the file grid1.cfm in Studio. 2.
PAGE 165

Chapter 10: Building Dynamic Forms HEADERITALIC="NO" HEADERBOLD="YES" DISPLAY="YES" SELECT="YES"> 3. Save the file as grid2.cfm. To update the data source with CFQUERY: 1. Open a new file in Studio. 2.
PAGE 166

140 Developing Web Applications with ColdFusion UPDATE Employees SET LastName=’#form.employee_grid.LastName[Counter]#’, Department_ID=#form.employee_grid.Department_ID[Counter]# WHERE Employee_ID=#form.employee_grid.original.Employee_ID[Counter]#
PAGE 167

Chapter 10: Building Dynamic Forms 141 How user edits are stored The following arrays are created to keep track of edits to grid rows and cells: Arrays Used to Store Grid Cell Edit Information Array reference Description gridname.colname [ row_index ] Stores the new value of an edited grid cell gridname.Original.colname [ row_index ] Stores the original value of the edited grid cell gridname.RowStatus.Action [ row_index ] Stores the edit type made against the edited grid cell.
PAGE 168

142 Developing Web Applications with ColdFusion 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, , colors for the groove in which the slider knob moves, label font name, size, boldface, italics, and color, as well as slider scale increments, range, positioning, and behavior. As with CFTREE and CFGRID, input valication can be serviced with a JavaScript specified in the ONVALIDATE attribute.
PAGE 169

Chapter 10: Building Dynamic Forms 143 validation methods using either a JavaScript or the VALIDATE attribute in CFTEXTINPUT. 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. For a complete list of validation formats, refer to the CFML Language Reference.
Please enter a date: PAGE 170
144 Developing Web Applications with ColdFusion To populate a drop-down list box with query data using CFSELECT: 1. Open a new file in Studio. 2. Modify the file so that it appears as follows: SELECT * FROM Employees PAGE 171
Chapter 10: Building Dynamic Forms 145 • Parameter options — You can override parameter values you defined in the Administrator by specifying the parameter value pair in CFAPPLET. Unless overridden, ColdFusion uses the parameter value pairs you defined in the Administrator.
PAGE 172

146 Developing Web Applications with ColdFusion Applet Registration Fields (Continued) Field Description Height Enter a measurement in pixels for the vertical space for the applet. Width Enter a measurement in pixels for the horizontal space for the applet. Vspace Enter a measurement in pixels for the space above and below the applet. Hspace Enter a measurement in pixels for the space on each side of the applet. Align Choose the alignment you want.
PAGE 173

Chapter 10: Building Dynamic Forms 147 Overriding parameter values You can also override the values you assigned to applet parameters in the Administrator by providing new values for any parameter. Note that in order to override a parameter, you must have already defined the parameter and a default value for it in the ColdFusion Administrator Applets page.
PAGE 174

148 Developing Web Applications with ColdFusion
PAGE 175

CHAPTER 11 Chapter 11 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. Contents • Searching a ColdFusion Web Site.................................................................. 150 • Supported File Types...................................................................................... 151 • Support for International Languages .....................................................
PAGE 176

150 Developing Web Applications with ColdFusion Searching a ColdFusion Web Site Until now, you’ve 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 requires full-text search capabilites. The Verity, Inc. search engine is bundled with ColdFusion to provide full-text indexing and searching.
PAGE 177

Chapter 11: Indexing and Searching Data 151 Online Verity training A video titled "Creating Search Engines with Verity" is available at http:// alive.allaire.com. The video gives an overview of the Verity implementation in ColdFusion and illustrates the development process with sample code. The video is part of Allaire Alive, an educational service that offers Web videos on topics specific to ColdFusion development and application deployment as well as broader industry issues.
PAGE 178

152 Developing Web Applications with ColdFusion Supported File Types (Continued) Documents Versions Type MS Word for DOS 4, 5, 6 Binary MS Word for Macintosh 4.0, 5.0, 6.0 Binary MS Notepad, WordPad all Binary MS Write, MS Works all Binary XYWrite 4.12 Binary Corel QuattroPro 7, 8 Binary Lotus 1-2-3 for DOS/Windows 2.0, 3.0, 4.0, 5.0, ’96, ’97 Binary Lotus 1-2-3 for OS/2 2 Binary MS Excel 3, 4, 5, ’95, ’97 Binary MS Works all Binary Corel Presentations 7.0, 8.
PAGE 179

Chapter 11: Indexing and Searching Data 153 • Spanish • Swedish The default language for Verity collections is English. To index data in one of the supported languages, you must select the language from the drop-down list when you create a collection on the ColdFusion Administrator Verity page. You must then enter the selected language as a value of the LANGUAGE attribute in both the CFINDEX and CFSEARCH tags used against that collection.
PAGE 180

154 Developing Web Applications with ColdFusion Using the ColdFusion Administrator to create a collection To create a new collection: 1. Open the ColdFusion Administrator Verity page. If you checked the option to install the ColdFusion Documentation, the documentation collection is listed by default. The Verity engine is used to search our online documents. 2. In the Add a Collection section, enter a name for the collection. 3. Enter a path for the location of the new collection.
PAGE 181

Chapter 11: Indexing and Searching Data 155 Collection Creation Input Form
Specify a collection
PAGE 182
156 Developing Web Applications with ColdFusion To create a collection action page: 1. Open a new file in Studio. 2. Modify the file so that it appears as follows: CFCOLLECTION
Collection creation

The collection #FORM.CollectionName# is created.
PAGE 183

Chapter 11: Indexing and Searching Data 157 Populating and Indexing a Collection At this point, the new collection is just an empty shell. To populate the collection with indexed data, you can use either of two methods: • The CF Administrator • The CFINDEX tag You can use the Verity Wizard in ColdFusion Studio to create the templates to make yur documents searchable. To run the wizard, click File > New and select the Verity Wizard from the CFML tab of the New Document dialog.
PAGE 184

158 Developing Web Applications with ColdFusion 5. Check the Recursively index subdirectories box if you want to extend the indexing operation to all directories below the selected path. 6. Optionally, you can enter a Return URL to prepend to all indexed files. This allows you to easily create a link to any of the files in the index. A typical entry might be something like http://localhost/wwwroot/. 7.
PAGE 185

Chapter 11: Indexing and Searching Data 159 To use CFINDEX to index a collection: 1. Open a new file in Studio. 2. Modify the file so that it appears as follows: Creating Index
Indexing Complete
The collection #Form.IndexColl# has been indexed.
PAGE 186

160 Developing Web Applications with ColdFusion Basic search operations To search the collection: 1. Create a new file in Stuio. 2. Modify the file so that it appears as follows: Select the collection to search
Search
PAGE 187
Chapter 11: Indexing and Searching Data 161
Search Results
#Search1.RecordCount# found out of #Search1.RecordsSearched# searched.
#Search1.title#

3. Save the file as collectionsearchaction.cfm. 4. View the file collectionsearchform.
PAGE 188

162 Developing Web Applications with ColdFusion CFSEARCH properties Three properties are generated for each CFSEARCH query that provide information about a particular query: • RecordCount — The total number of records returned by the query. • CurrentRow — The current row of the query being processed by CFOUTPUT. • RecordsSearched — The total number of records in the index that were searched. If no records were returned in the search, this property returns a null value.
PAGE 189

Chapter 11: Indexing and Searching Data 163 This CFINDEX statement specifies the MessageText column as the core of the collection and names the table’s primary key, the Message_ID column, as the KEY value. Note that the TITLE attribute names the Subject column. The TITLE attribute can be used to designate an output parameter.
PAGE 190

164 Developing Web Applications with ColdFusion DN: #dn#
O: #o#
TELEPHONENUMBER: #telephonenumber#
MAIL: #mail#
=============================
PAGE 191
Chapter 11: Indexing and Searching Data 165
PAGE 192

166 Developing Web Applications with ColdFusion pass a simple query expression to the search engine directly from an HTML input form. The Verity query language provides many operators and modifiers for composing queries.
PAGE 193

Chapter 11: Indexing and Searching Data 167 density of the search term in the searched documents. The more frequent the occurrence of a word in a document, the higher the document’s score. As a result, the search engine ranks documents according to word density as it searches for the word you specify, as well as words that have the same stem. For example, "films," "filmed," and "filming" are stemmed variations of the word "film.
PAGE 194

168 Developing Web Applications with ColdFusion Special characters A number of characters are handled in particular ways by the search engine. Special Search Characters Characters Description , () [ These characters end a text token. = >
PAGE 195

Chapter 11: Indexing and Searching Data 169 When prefix notation is used, precedence is handled explicitly within the expression. The following example means: "Look for documents that contain b and c first, then documents that contain a": OR (a, AND (b,c)) When infix notation is used, precedence is implicit in the expression. For example, the AND operator takes precedence over the OR operator.
PAGE 196

170 Developing Web Applications with ColdFusion Searching with Wildcards This table shows the wildcard characters for searching Verity collections. Verity Wildcard Characters Wildcard Description ? Question. Specifies any single alphanumeric character. * Asterisk. Specifies zero or more alphanumeric characters. Avoid using the asterisk as the first character in a search string. Asterisk is ignored in a set, [] or an alternative pattern {}. [] Square brackets.
PAGE 197

Chapter 11: Indexing and Searching Data 171 • left curly brace ({) • left bracket ([) • less than sign (<) • backquote (‘ ) In addition to the backslash character, you can use paired backquotes (‘ ‘ ) to interpret special characters as literals.
PAGE 198

172 Developing Web Applications with ColdFusion • Natural language operators — Allow the use of natural language expressions in forming queries. Ordinarily, you use operators in explicit searches. They are used in the following manner: "search_string" Evidence operators Evidence operators can be used to specify either a basic word search or an intelligent word search. A basic word search finds documents that contain only the word or words specified in the query.
PAGE 199

Chapter 11: Indexing and Searching Data 173 The following table describes each operator. Verity 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 200

174 Developing Web Applications with ColdFusion The following operators are used for numeric and date comparisons. Verity Numerical and Date Relational Operators Operator Description = Equals > Greater than >= Greater than or equal to < Less than <= Less than or equal to Text comparison operators match words and parts of words. The following operators are used for text comparisons.
PAGE 201

Chapter 11: Indexing and Searching Data 175 VerityText Comparison Operators (Continued) Operator Description ENDS Selects documents by matching the character string you specify with the ending characters of the values stored in a specific document field. SUBSTRING Selects documents by matching the query string you specify with any portion of the strings in a specific document field. For example, specifying "god" will match "godliness," "a god among men," "godforsaken," etc.
PAGE 202

176 Developing Web Applications with ColdFusion YearPlaceText (Continued) Year Place Text 1991 Oregon Text about Oregon 1991 1992 Utah Text about Utah 1992 The following application page matches records that have 1990 in the TEXT column and are in the Place Utah. The search is performed against the collection that contains the TEXT column and then is narrowed further by searching the string "Utah" in the CF_TITLE document field.
PAGE 203

Chapter 11: Indexing and Searching Data 177 #GetText_Search.TITLE#
Concept operators Concept operators combine the meaning of search elements to identify a concept in a document. Documents retrieved using concept operators are ranked by relevance. The following table describes each concept operator. Verity Concept Operators Operator Description AND Selects documents that contain all of the search elements you specify.
PAGE 204

178 Developing Web Applications with ColdFusion The following table lists the score operators. Verity Score Operators Operator Description YESNO Forces the score of an element to 1 if the element’s score is nonzero: mainframe If the retrieval result of the search on "mainframe" is 0.75, the YESNO operator forces the result to 1. You can use YESNO to avoid relevance ranking. PRODUCT Multiplies the scores for documents matching a query.
PAGE 205

Chapter 11: Indexing and Searching Data 179 Search modifiers Modifiers are combined 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. Modifiers are as follows. Verity Search Modifiers Modifier CASE Description Specifies a case-sensitive search: J[JAVA, java] Searches for "JAVA" and "Java.
PAGE 206

180 Developing Web Applications with ColdFusion Verity Search Modifiers (Continued) Modifier Description NOT Used to exclude documents that contain the specified word or phrase. Used only with the AND and OR operators. Java programming coffee ORDER Used to specify that the search elements must occur on the same order in which they were specified in the query.
PAGE 207

Chapter 11: Indexing and Searching Data 181 • Delete (when used as a CFINDEX ACTION) — Deletes the specified KEY value, or comma-separated values, from the collection. • Delete (when used on the Administrator Verity page or in CFCOLLECTION) — Deletes the entire collection. • Update — Re-populates the collection with changed records and new records and adds a key if one is not part of the collection. This operation does not delete records that have been deleted from the data source.
PAGE 208

182 Developing Web Applications with ColdFusion
PAGE 209

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

184 Developing Web Applications with ColdFusion 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. You create a special template, named Application.cfm, which you place in the root directory of the application.
PAGE 211

Chapter 12: Using the Application Framework 185 Custom error handling Using the CFERROR tag, you can display customized HTML pages when errors occur. This allows you to maintain a consistent look and feel within your application even when errors occur. It also allows you to optionally suppress the display of error information. See “Generating Custom Error Messages (CFERROR)” on page 93 for more information.
PAGE 212

186 Developing Web Applications with ColdFusion • Development: The application is easier to develop and maintain because the application page files are well organized. • Portability: The application can be more easily moved to another server or another part of a server without having to change any code in the application page files. • Application-level Settings: Application pages that fall under the same root directory can share application-level settings and functions.
PAGE 213

Chapter 12: Using the Application Framework 187 Bandwidth Associates Web Wonders, Inc. Application.cfm Application.cfm Products Products Orders Support Services Consulting Application.cfm Marketing Application.cfm Sales Application.cfm Behavior with CFINCLUDE Only one Application.cfm file is ever processed for each ColdFusion application page. The presence of an Application.cfm file is an implicit CFINCLUDE. If it is present in the directory tree, there is no way not to include it.
PAGE 214

188 Developing Web Applications with ColdFusion • Default variables • Custom error pages • Data sources • Default style settings • Exclusive locks • Other application-level constants Note Because UNIX is case sensitive, the application framework file must be spelled with an initial capital, Application.cfm, for applications that run on UNIX platforms. Naming the application In ColdFusion, you define an application by giving it a name using the CFAPPLICATION tag.
PAGE 215

Chapter 12: Using the Application Framework 189 4 2. Save the file as Application.cfm in the root directory of your application framework. Choosing a client variable storage method Once you have enabled client state management, you then have to determine where you want to store client variables.
PAGE 216

190 Developing Web Applications with ColdFusion Cookie storage When you set CLIENTSTORAGE="Cookie" the cookie that ColdFusion creates has the application’s name. Storing client data in a cookie is scalable to large numbers of clients, but this storage mechanism has some limitations. Chief among them is that if the client turns off cookies in the browser, client variables won’t work.
PAGE 217

Chapter 12: Using the Application Framework 191 Creating a client variable To create a client variable and set the value of the parameter, use the CFSET or CFPARAM tag., for example: Once a client variable has been set in this manner, it is available for use within any application page in your application that is accessed by the client for whom the variable is set.
PAGE 218

192 Developing Web Applications with ColdFusion the client ID (CFID)and the client security token (CFTOKEN) between pages, either in hidden form fields or appended to URLs. You accomplish this using the variable Client.URLTOKEN or Session.URLTOKEN. Note In ColdFusion, client state management is explicitly designed to work with cookies, the standard tool for identifying clients.
PAGE 219

Chapter 12: Using the Application Framework 193 Variable caching All client variable reads and writes are cached to help decrease the overhead of client state management operations. See Administering ColdFusion Server for information on variables and server clustering.
PAGE 220

194 Developing Web Applications with ColdFusion For information on setting time-outs for variables, See Administering ColdFusion Server. Differentiating client, session, and application variables This table shows the relationships among client, session, and application variables.
PAGE 221

Chapter 12: Using the Application Framework 195 period, ColdFusion interprets this as the end of the session and clears any variables associated with that session. The default time-out for session variables is set to 20 minutes. In the Variables page of the ColdFusion Administrator, you can change this time-out value. See Administering ColdFusion Server for more information.
PAGE 222

196 Developing Web Applications with ColdFusion to be triggered on every page ---> Using Application Variables Application variables require an application name be associated with them and are always scoped within that application name.
PAGE 223

Chapter 12: Using the Application Framework 197 You can set the time-out period for application variables within a specific application (thereby overriding the default setting in the ColdFusion Administrator) by using the APPLICATIONTIMEOUT attribute of the CFAPPLICATION tag. If no clients access the application within the specified time-out period, ColdFusion Server destroys its application variables.
PAGE 224

198 Developing Web Applications with ColdFusion Example: Application.cfm The following example shows a complete Application.cfm file for the sample Products application: PAGE 225
Chapter 12: Using the Application Framework 199 • Exclusive locks allow only one request to process the locked code. • Read-only locks allow multiple requests to execute concurrently, provided that no exclusive locks are executing. Note Unless you specify the TYPE attribute, the default lock is exclusive. You should minimize the use of exclusive locks. If you have performancesensitive code inside CFLOCK tags, consider adding the TYPE="ReadOnly" attribute to CFLOCK tags that do not update shared data.
PAGE 226

200 Developing Web Applications with ColdFusion A deadlock is a state in which no request can execute the locked section of the page. Thus, all requests to the protected section of the page are blocked until there is a timeout. The following table shows one scenario that would cause a deadlock. Deadlock Scenario User 1 User 2 Locks the session scope. Locks the application scope. Deadlock: Tries to lock application scope, but application scope is already locked by User 2.
PAGE 227

Chapter 12: Using the Application Framework The following sample code might be part of the Application.cfm file. Define Session and Application Variables
CFAPPLICATION Example

CFAPPLICATION defines scoping for a ColdFusion applicationand enables or disables the storing of client and/or session variables. This tag is placed in the Application.cfm file for the current application.
PAGE 228

202 Developing Web Applications with ColdFusion E-Turtleneck is proud to say that we have sold #application.number# turtlenecks to date. Tip In general, you should limit lock scopes. When locking variables, queries, and arrays (anything other than structures), you can copy to a local variable in the CFLOCK block, then reference the local variable. The remaining sample code would appear inside the application page where customers place orders.

PAGE 229

Chapter 12: Using the Application Framework 203

Congratulations! You have just selected the longest wearing, most comfortable turtleneck in the world. Please indicate the color and size you want to buy.

Select a color. PAGE 230 204 Developing Web Applications with ColdFusion dynamic value for the NAME attribute to allow protection of a file with any given name. Example of protecting ColdFusion Extensions This example illustrates how a custom tag wrapper can be built around CFXs that are not thread-safe. The wrapper simply forwards attributes to the non thread-safe CFX that is used inside a CFLOCK tag. PAGE 231 CHAPTER 13 Chapter 13 Sending and Receiving Email You can add interactive email features to your ColdFusion applications, providing 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 email capability a vital link to your users. Contents • Using ColdFusion with Mail Servers............................................................. 206 • Sending Email Messages................................................. PAGE 232 206 Developing Web Applications with ColdFusion Using ColdFusion with Mail Servers Adding email to your ColdFusion applications lets you respond automatically to user requests. You can use email in your ColdFusion applications in many different ways. These are just a few examples: • Trigger email messages based on users’ requests or orders. • Allow users to request and receive additional information or documents through email. • Confirm customer information based on order entries or updates. PAGE 233 Chapter 13: Sending and Receiving Email 207 Sending SMTP mail with CFMAIL The CFMAIL tag provides support for sending SMTP email 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. You can use all the attributes and commands that you use with CFOUTPUT with CFMAIL as well. To send a simple email message: 1. Create a new file in Studio. 2. PAGE 234 208 Developing Web Applications with ColdFusion • Use a query to send a customized mail message, such as a billing statement to a list of recipients that is dynamically populated from a database. • Send a MIME file attachment along with a mail message. Sending form-based email In the example below, the contents of a customer inquiry form submittal are forwarded to the marketing department. Note that the same application page could also insert the customer inquiry into the database. PAGE 235 Chapter 13: Sending and Receiving Email 209 the "ProductRequests" query, while the text above and below it serve as the header and footer (respectively) for the mail message. Sending email to multiple recipients In the following example, a query ("CFBetaTesters") is run to retrieve a list of people who are beta testing ColdFusion. This query is then used to send a notification to each of these testers that a new version of the beta release is available: PAGE 236 210 Developing Web Applications with ColdFusion Company Name: #Company# Contact: #FirstName# #LastName# Address: #Address1# #Address2# #City#, #State# #Zip# Phone: #Phone# Fax: #Fax# Home Page: #HomePageURL# Please let us know if any of the above information has changed, or if we need to get in touch with someone else in your organization regarding this request. Thanks, Allaire Customer Service service@allaire. PAGE 237 Chapter 13: Sending and Receiving Email 211 Advanced Sending Options The ColdFusion implementation of SMTP mail uses a spooled architecture. This means that when a CFMAIL tag is processed in an application page, the messages generated are not sent immediately. Instead, they are spooled to disk and processed in the background. This architecture has two distinct advantages: 1. End users of your application are not required to wait for SMTP processing to complete before a page returns to them. PAGE 238 212 Developing Web Applications with ColdFusion Use CFPOP in applications when you want to receive email. Here are two instances where implementing POP mail makes sense: • If your site has generic mailboxes that are read by more than one person (sales@yourcompany.com), it may be more efficient to construct a ColdFusion mail front-end to supplement individual user mail clients. • In many applications, the processing of mail can be automated when the mail is formatted to serve a particular purpose. PAGE 239 Chapter 13: Sending and Receiving Email Handling POP Mail This section gives an example of each of the following usages: • Retrieving only message headers • Retrieving a message body • Retrieving attachments • Deleting messages Returning only message headers The header includes: • DATE • FROM • MESSAGENUMBER • REPLYTO • SUBJECT • CC • TO To retrieve only the message header: 1. Create a new file in Studio. 2. PAGE 240 214 Developing Web Applications with ColdFusion Cc: #HTMLEditFormat(Sample.CC)# ReplyTo: #HTMLEditFormat(Sample.REPLYTO)# 3. Change the following line so that it refers to a valid POP mail server, as well as a valid user name and password: PAGE 241 Chapter 13: Sending and Receiving Email 215 the message body: MessageNumber: #HTMLEditFormat(Sample.MESSAGENUMBER)# To: #HTMLEditFormat(Sample.TO)# From: #HTMLEditFormat(Sample.FROM)# Subject: #HTMLEditFormat(Sample.SUBJECT)# Date: #HTMLEditFormat(Sample.DATE)# Cc: #HTMLEditFormat(Sample.CC)# ReplyTo: #HTMLEditFormat(Sample. PAGE 242 216 Developing Web Applications with ColdFusion This example retrieves message header, body, and all attachments: MessageNumber: #HTMLEditFormat(Sample.MESSAGENUMBER)# To: #HTMLEditFormat(Sample.TO)# From: #HTMLEditFormat(Sample.FROM)# Subject: #HTMLEditFormat(Sample.SUBJECT)# Date: #HTMLEditFormat(Sample. PAGE 243 Chapter 13: Sending and Receiving Email 217 returned will be 1,2,3,4. If messages 1 and 2 are then deleted within a single CFPOP tag, messages 3 and 4 will be assigned message numbers 1 and 2, respectively. To delete messages: 1. Create a new file in Studio. 2. Modify the file so that it appears as follows: POP Mail Message Delete Example This example deletes messages: PAGE 244 218 Developing Web Applications with ColdFusion PAGE 245 CHAPTER 14 Chapter 14 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. Contents • Using CFFILE .................................................................................................. 220 • Uploading Files............................................................................................... 220 • Setting File and Directory Attributes .................... PAGE 246 220 Developing Web Applications with ColdFusion 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. The required attributes depend on the ACTION specified. For example, if ACTION="WRITE", ColdFusion expects the attributes associated with writing a text file. PAGE 247 Chapter 14: Managing Files on the Server 221 Code Review Code Description Create a form that contains file selection fields for upload by the user. Allow the user to input a field. (The File input type automatically includes a Browse button to allow the user to look for the file instead of entering the entire path and file name. PAGE 248 222 Developing Web Applications with ColdFusion 3. Change the following line to point to an appropriate location on your server: DESTINATION="c:\inetpub\wwwroot\HR\" 4. Save the file as uploadfileaction.cfm in myapps under the Web root directory. 5. View uploadfileform.cfm in your browser, enter values and submit the form. 6. The file you specified is uploaded. Code Review Code Description PAGE 249 Chapter 14: Managing Files on the Server 223 A file’s MIME type is determined by the browser. Common types, like "image/gif" and "text/plain", are registered in your browser. Note Not all browsers support MIME type associations. Example: Restricting file types This CFFILE specification will only save an image file that is in the GIF format: PAGE 250 224 Developing Web Applications with ColdFusion You enter permissions values in the MODE attribute for each type of user: owner, group, other in that order. PAGE 251 Chapter 14: Managing Files on the Server 225 The following file upload status variables are available after an upload. File Upload Variables Parameter Description AttemptedServerFile Initial name ColdFusion used attempting to save a file, for example, myfile.txt. See "Resolving conflicting file names" above. ClientDirectory Directory location of the file uploaded from the client’s system. ClientFile Name of the file uploaded from the client’s system, such as myfile.txt. PAGE 252 226 Developing Web Applications with ColdFusion File Upload Variables (Continued) Parameter Description ServerFileExt Extension of the uploaded file on the server, without a period, for example, txt not.txt. ServerFileName Filename, without an extension, of the uploaded file on the server. TimeCreated Time the uploaded file was created. TimeLastModified Date and time of the last modification to the uploaded file. Use the File prefix to refer to these variables, for example, #CFFILE.FileExisted#. PAGE 253 Chapter 14: Managing Files on the Server 227 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. This gives you the ability to • Create 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 254 228 Developing Web Applications with ColdFusion To create a form in which to enter data for a text file: 1. Open a new file in Studio. 2. Modify the file so that it appears a follows: Put Information into a Text File Put Information into a Text File PAGE 255 Chapter 14: Managing Files on the Server 229 Performing Directory Operations Use the CFDIRECTORY tag to return file information from a specified directory and to create, delete, and rename directories. As with CFFILE, ColdFusion administrators can disable CFDIRECTORY processing in the ColdFusion Administrator Tags page. See the CFML Language Reference for details on the syntax of this tag. PAGE 256 230 Developing Web Applications with ColdFusion
#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.cfm and view it in your browser.

PAGE 257

CHAPTER 15 Chapter 15 Interacting with Remote Servers This chapter describes how ColdFusion wraps the complexity of Hypertext Transfer Protocol communications in a simplified tag syntax that allows you to easily extend your site’s offerings across the Web. Contents • Using CFHTTP to Interact with the Web ...................................................... 232 • Using the CFHTTP Get Method ....................................................................
PAGE 258

232 Developing Web Applications with ColdFusion Using CFHTTP to Interact with the Web The CFHTTP tag 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. The Get method is a one-way transaction in which CFHTTP retrieves an object.
PAGE 259

Chapter 15: Interacting with Remote Servers 233 Code Review Code Description Get the page specified in the URL and make the links absolute instead of relative.. #CFHTTP.FileContent#
Display the page, which is stored in the variable CFHTTP.FileContent, in the browser. To get a Web page and save it in a file: 1. Open a new file in Studio. 2.
PAGE 260

234 Developing Web Applications with ColdFusion #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.cfm in myapps under your Web root directory and view it in your browser.
PAGE 261

Chapter 15: Interacting with Remote Servers 235 • When duplicate column heading names are encountered, ColdFusion adds an underscore character to the duplicate column name to make it unique. For example, if two CustomerID columns are found, the second is renamed "CustomerID_". To create a query from a text file: 1. Create a new file in Studio. 2. Modify the file so that it appears as follows: separated by commas.
PAGE 262

236 Developing Web Applications with ColdFusion 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 Post operations, you must use the CFHTTPPARAM tag for each variable you want to post. Unlike the Get method, Post passes data to a specified ColdFusion page or to some executable that interprets the variables being sent and returns data.
PAGE 263

Chapter 15: Interacting with Remote Servers 237 You have POSTed to me.
The URL variable is: #url.myurl#
The Cookie variable is: #cookie.mycookie6#
The CGI variable is: #cgi.mycgi#.
The Formfield variable is: #form.myformfield#.
3. Replace c:\temp\junk with a path and filename on your hard drive. 4. Save the file as posttest.
PAGE 264

238 Developing Web Applications with ColdFusion This example runs a CGI program, search.exe, that searches the site and returns the hits on the value specified in VALUE. Using Secure Sockets Layer (SSL) with CFHTTP When using Secure Sockets Layer (SSL) to transmit secured transactions via CFHTTP, you need to be aware of limitations on its use caused by a bug in one of the components of Microsoft’s InetSDK. The problem occurs on Windows NT and should not affect Windows 95/98 machines.
PAGE 265

Chapter 15: Interacting with Remote Servers 239 Performing File Operations with CFFTP The CFFTP tag allows you to perform tasks on remote servers via the File Transfer Protocol (FTP). CFFTP allows you to cache connections for batch file transfers. Note In order to use CFFTP, make sure CFOBJECT is enabled on the Basic Security page of the ColdFusion Administrator. For server/browser operations, use the CFFILE, CFCONTENT, and CFDIRECTORY tags.
PAGE 266

240 Developing Web Applications with ColdFusion 3. Change beta.company.com to the name of a server you have permission to FTP to. 4. Change betauser and monroe to a valid username and password.
PAGE 267

Chapter 15: Interacting with Remote Servers 241 Connection caching actions and attributes The following table shows which CFFTP attributes are required for CFFTP actions when employing connection caching. If connection caching is not used, the connection attributes USERNAME, PASSWORD, and SERVER must be specified.
PAGE 268

242 Developing Web Applications with ColdFusion The best source of information about WDDX is http://www.wddx.org/. This site, sponsored by Allaire Corporation, offers a free download of the WDDX SDK and a number of resources, including a WDDX FAQ and a developer forum.
PAGE 269

Chapter 15: Interacting with Remote Servers 243 descriptors that allow the data to be manipulated on a target system between arbitrary application servers. WDDX is based on XML, which is a W3C Recommendation. Other W3C efforts now in the works will have obvious application to WDDX when they are completed, most importantly, the XML-Schema proposal.
PAGE 270

244 Developing Web Applications with ColdFusion All of Allaire’s WDDX serializers (CFML, COM, and JS) have an attribute/property useTimezoneInfo that specifies whether time zone information should be used in the serialization process. The default value is true. In the CFML implementation, useTimezoneInfo is a property of the CFWDDX Action=Cfml2WDDX tag. In the COM implementation, useTimezoneInfo is a property of the IWDDXSerializer interface provided by the object WDDX.Serializer.1.
PAGE 271

Chapter 15: Interacting with Remote Servers 245 Comparison of JavaScript object and deserialized XML JavaScript CFML x = new Object(); x.a = "Property a"; x.b = "Property b"; x = structNew(); x.a = "Property a"; x.b = "Property b"; See the CFML Language Reference for more information on JavaScript objects.
PAGE 272

246 Developing Web Applications with ColdFusion q.dump(true); Note To see how CFWDDX Action="cfml2js" works, view the source to the page. 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 where complex JavaScript data collections are generated, this basic approach can be extended very effectively.
PAGE 273

Chapter 15: Interacting with Remote Servers 247 Personal information
First name:
Last name:

PAGE 274
248 Developing Web Applications with ColdFusion
PAGE 275

CHAPTER 16 Chapter 16 Connecting to LDAP Directories Support for the Lightweight Directory Access Protocol (LDAP) API in CFML is part of Allaire’s commitment to open networking standards. Contents • What is LDAP? ................................................................................................ 250 • ColdFusion Support for LDAP....................................................................... 252 • Working with LDAP Directories ....................................................
PAGE 276

250 Developing Web Applications with ColdFusion What is LDAP? LDAP (Lightweight Directory Access Protocol) is a protocol that enables organizations to arrange directory information in a hierarchy. Note that in this case, "directory" refers to a collection of information something like a telephone directory, not a collection of files in a folder on a disk drive. An LDAP directory is, in essence, a database, which is usually a hierarchical structure, (although this is not a requirement).
PAGE 277

Chapter 16: Connecting to LDAP Directories 251 LDAP attributes Following is a list of the common attributes: Common LDAP Attributes Attribute Name c country st state or province l locality o organization ou organizational unit cn common name sn surname Key Terms Following is a brief description of the LDAP information structure. Entry The basic information object of LDAP is the entry.
PAGE 278

252 Developing Web Applications with ColdFusion attribute is "ou=support, o=allaire" the level below "support" is searched. You can optionally restrict a query to the level of the Start entry or extend it to the entire subtree. Referral While not supported directly in the LDAP2 standard, the ability of an LDAP server to refer a client query to another server is an attractive feature and has been implemented in the Netscape and University of Michigan servers.
PAGE 279

Chapter 16: Connecting to LDAP Directories 253 • Build applications that incorporate data from directory queries in their processes. Working with LDAP Directories The CFLDAP tag allows you to work with LDAP directories in the following ways. You can: • View the directory schema • Search an LDAP directory • Process the results of querying an LDAP directory (OUTPUT) Viewing the Directory Schema LDAP 3.0 now supports access to a directory’s schema information as part of a special entry in the root DN.
PAGE 280

254 Developing Web Applications with ColdFusion ATTRIBUTES="dn, objectclasses, attributetypes" SCOPE="BASE" FILTER="objectclass=*" START=#EntryList.subschemasubentry# > DN=#dn#
objectClasses: #objectclasses#

attribute Types: #attributetypes#

3. Change the SERVER from testldap.company.com to a valid LDAP server. 4. Save the template as testldap.cfm in myapps under your Web root directory and view it in your browser.
PAGE 281

Chapter 16: Connecting to LDAP Directories 255 CFLDAP Filter Operators (Continued) Operator Example * o=alla* - organization names starting with "alla" o=*aire - organization names ending with "aire" o=all*aire - organization names starting with "all and " ending with "aire" & (&(o=allaire)(co=usa)) - organization name = "allaire" AND country = "usa" | (|(o=allaire)(sn=allaire)) - organization name = "allaire" OR surname = "allaire" ! (!(STREET=*)) - all entries that do NOT contain a StreetAddres
PAGE 282

256 Developing Web Applications with ColdFusion 3. Save the page as ldapadd.cfm and view it in your browser.
PAGE 283

Chapter 16: Connecting to LDAP Directories 257
Human Resources Directory for Arius
PAGE 284
258 Developing Web Applications with ColdFusion
PAGE 286

260 Developing Web Applications with ColdFusion
Authentication error
<--- Display the message. Alternatively, you might place code here to define the user to the security context. --->
#CFCATCH.
PAGE 296

270 Developing Web Applications with ColdFusion • USERNAME — The username of the user to impersonate. • PASSWORD — The password of the user to impersonate. • TYPE — Indicates the type of impersonation to implement, application-level or operating-system-level. Application-level impersonation lets you assume the rights assigned to a ColdFusion user by a specified security context. Operatingsystem-level impersonation lets you assume the rights assigned to a Windows NT user by a specified Windows NT Domain.
PAGE 297

Chapter 17: Application Security 271 If a user passes the authentication test, ColdFusion passes a cookie to carry the user’s authentication state to subsequent application pages governed by this Application.cfm page. • Next, only authenticated users are able to access the requested application page, for selecting and updating customer orders in a database. This page checks to see which resources the authenticated user is authorized to see and use. Authenticating users in Application.
PAGE 298

272 Developing Web Applications with ColdFusion
Invalid Login
PAGE 299

Chapter 17: Application Security Example: orders.cfm ...
PAGE 300

274 Developing Web Applications with ColdFusion
PAGE 301

CHAPTER 18 Chapter 18 Building Custom CFAPI Tags For some applications, building executables to run with ColdFusion is the best solution. Perhaps the application requirements go beyond what is currently feasible in CFML. Or perhaps application performance can be improved 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 302

276 Developing Web Applications with ColdFusion What Are CFX Tags? CFX tags are custom tags written against the ColdFusion Application Programming Interface. Generally, you create a CFX if you want to do something that’s not possible in CFML, or if you want to improve performance of a task in CFML that’s repetitive. Unlike CFML custom tags, CFXs are implemented as DLL files and can: • Handle any number of custom attributes. • Use and manipulate ColdFusion queries for custom formatting.
PAGE 303

Chapter 18: Building Custom CFAPI Tags 277 Using the Tag Wizard to create CFXs in C++ On Windows NT, you can get a start in developing CFXs by using the ColdFusion Tag Wizard. To use the wizard, the CFXAPI Tag Development Kit must be installed (it is by default), and the setup routine must detect Microsoft Visual C++ on the system. The wizard generates a DLL file with a basic tag structure containing a single procedure. By modifying and testing this tag, you can quickly learn how to work within the API.
PAGE 304

278 Developing Web Applications with ColdFusion On UNIX Solaris You can debug custom tags on UNIX using the dbx debugger. You should shut down ColdFusion using the stop script. Set the environment variables, including LD_LIBRARY_PATH and CFHOME as they are set in the start script. You should then be able to run the cfserver executable under the dbx debugger and set break points in your CFX code.
PAGE 305

Chapter 18: Building Custom CFAPI Tags 279 • HelloWorldGraphic - Generates a "Hello World!" graphic in JPEG format. Demonstrates how to dynamically create and return graphics from a Java CFX. Setting Up Your Development Environment to Develop CFXs in Java You can use a wide range of Java development environments to build Java CFXs, including the Java Development Kit which you can download from Sun at http://www.javasoft.com/products/jdk/1.2/index.
PAGE 306

280 Developing Web Applications with ColdFusion To create a Java CFX: 1. Create a new source file in your editor. 2. Enter the code, for example, the code below illustrates the creation of a very simple Java CFX named SimpleJavaCFX that writes a text string back to the calling page: import com.allaire.cfx.* ; public class HelloColdFusion implements CustomTag { public void processRequest( Request request, Response response ) throws Exception { String strName = request.getAttribute( "NAME" ) ; response.
PAGE 307

Chapter 18: Building Custom CFAPI Tags 281 Request Object Passed to the processRequest method of the CustomTag interface. Provides methods for retrieving attributes passed to the tag, including queries, and reading global tag settings.
PAGE 308

282 Developing Web Applications with ColdFusion Query Object Provides an interface for working with ColdFusion queries, including methods for retrieving name, row count, and column names as well as methods for getting and setting data elements..
PAGE 309

Chapter 18: Building Custom CFAPI Tags 283 Automatic Class Reloading You can determine how the server treats changed Java CFX class files by using the RELOAD (?) . The allowable values for the RELOAD attribute are as follows:. Allowable Values of RELOAD Attribute Value Description Auto Automatically reload Java CFX and dependent classes within the classes directory whenever the CFX class file changes. Does not reload if a dependent class file changes without the CFX class file changing as well.
PAGE 310

284 Developing Web Applications with ColdFusion your CustomTag object. If you wish to store data and/or objects that are accessible to all instances of your CustomTag you should use static data members. Calling the CFX from a ColdFusion Template You call Java CFXs from within ColdFusion templates by using the name of the CFX. The following CFML template calls the HelloColdFusion custom tag: 4 To test the CFX: 1.
PAGE 311

Chapter 18: Building Custom CFAPI Tags The Java implementation of ZipBrowser is as follows: import import import import com.allaire.cfx.* ; java.util.Hashtable ; java.io.FileInputStream ; java.util.zip.* ; public class ZipBrowser implements CustomTag { public void processRequest( Request request, Response response ) throws Exception { // validate that required attributes were passed if ( !request.attributeExists( "ARCHIVE" ) || !request.
PAGE 312

286 Developing Web Applications with ColdFusion Approaches to Debugging Java CFXs Java CFXs are not standalone applications that run in their own process like typical Java applications. Rather, they are created and invoked from an existing process — ColdFusion Server. This makes debugging Java CFXs more difficult because it is not possible to use an interactive debugger to debug Java classes that have been loaded by another process.
PAGE 313

Chapter 18: Building Custom CFAPI Tags 287 • DebugResponse — An implementation of the Response interface that enables you to print the results of a request once it has completed. • DebugQuery — An implementation of the Query interface that enables you to initialize a query with a name, columns, and a data set. To use the debugging classes: 1. Create a main method for your Java CFX class. This method will be used as the testbed for your CFX. 2.
PAGE 314

288 Developing Web Applications with ColdFusion DebugQuery query = new DebugQuery( "Employees", columns, data ) ; // create tag, process debug request, and print results OutputQuery tag = new OutputQuery() ; DebugRequest request = new DebugRequest( attributes, query ) ; DebugResponse response = new DebugResponse() ; tag.processRequest( request, response ) ; response.printResults() ; } catch( Throwable e ) { e.printStackTrace() ; } } public void processRequest( Request request ) throws Exception { // ...
PAGE 315

Chapter 18: Building Custom CFAPI Tags 289 DebugQuery // initialize a query with name and columns public DebugQuery( String name, String[] columns ) throws IllegalArgumentException ; // initialize a query with name, columns, and data public DebugQuery( String name, String[] columns, String[][] data ) throws IllegalArgumentException ; Java Customization and Configuration You use the ColdFusion Administrator to customize your Java development environment, such as customizing the Class Path, Java system pro
PAGE 316

290 Developing Web Applications with ColdFusion To register a C++ CFX: 1. In the CF Administrator, open the Extensions > CFX Tags page. 2. Enter CFX_MyNewTag in the Tag name and, optionally, a description. 3. Select the type of tag (either C++ or Java). 4. Click Add to open the New CFX Tag page. 5. If the Server library (DLL) field is empty, enter the file path. 6. Accept the default Procedure entry. 7. Un-check the Keep library loaded box while developing the tag.
PAGE 317

Chapter 18: Building Custom CFAPI Tags 291 Distribution If you are distributing a custom tag, you may want to automatically register the custom tag during the setup process by writing the registration entries directly into the Registry.
PAGE 318

292 Developing Web Applications with ColdFusion To import a C++ 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\CurrentVersion\ CustomTags\CFX_TEST] "LibraryPath"="C:\\cfusion\\cfx\\CFX_TEST\\test.dll" "ProcedureName"="ProcessTagRequest" "Description"="Sample CFX tag." "CacheLibrary"="1" 2.
PAGE 319

Chapter 18: Building Custom CFAPI Tags 293 C++ CFX Reference Below is a listing of CFXAPI classes and members. Individual members are described fully in the following sections.
PAGE 320

294 Developing Web Applications with ColdFusion CCFXException Class Abstract class that represents an exception thrown during the processing of a ColdFusion Extension (CFX) procedure. Exceptions of this type can be thrown by CCFXRequest Class, CCFXQuery Class, and CCFXStringSet Class. Your ColdFusion Extension code must therefore be written to handle exceptions of this type. (See the CCFXRequest::ThrowException and CCFXRequest::ReThrowException tags for details on doing this correctly.
PAGE 321

Chapter 18: Building Custom CFAPI Tags 295 pRequest->ReThrowException( e ) ; } // Catch ALL other exceptions and throw them as // Cold Fusion exceptions (DO NOT REMOVE! -// this prevents the server from crashing in // case of an unexpected exception) catch( ... ) { pRequest->ThrowException( "Error occurred in tag CFX_FOO2", "Unexpected error occurred while processing tag." ) ; } } CCFXQuery Class Abstract class that represents a query used or created by a ColdFusion Extension (CFX).
PAGE 322

296 Developing Web Applications with ColdFusion CCFXQuery::AddRow int CCFXQuery::AddRow(void) Add a new row to the query. You should call this function each time you want to append a row to the query. Returns the index of the row that was appended to the query.
PAGE 323

Chapter 18: Building Custom CFAPI Tags 297 CCFXQuery::GetData LPCSTR CCFXQuery::GetData(int iRow, int iColumn) Retrieves a data element from a row and column of the query. Row and column indexes begin with 1. You can determine the number of rows in the query by calling CCFXQuery::GetRowCount. You can determine the number of columns in the query by retrieving the list of columns using CCFXQuery::GetColumns and then calling CCFXStringSet::GetCount on the returned string set.
PAGE 324

298 Developing Web Applications with ColdFusion Retrieves the number of rows in the query. Returns the number of rows contained in the query. Example The following example retrieves the number of rows in a query and writes it back to the user: CCFXQuery* pQuery = pRequest->GetQuery() ; char buffOutput[256] ; wsprintf( buffOutput, "The number of rows in the query is %ld.
PAGE 325

Chapter 18: Building Custom CFAPI Tags 299 CCFXQuery::SetQueryString This is a deprecated function and should not be used. CCFXQuery::SetTotalTime This is a deprecated function and should not be used. CCFXRequest Class Abstract class that represents a request made to a ColdFusion Extension (CFX). An instance of this class is passed to the main function of your extension DLL.
PAGE 326

300 Developing Web Applications with ColdFusion virtual void WriteDebug( LPCSTR lpszOutput ) CCFXRequest::WriteDebug writes text output into the debug stream. virtual CCFXStringSet* CreateStringSet() CCFXRequest::CreateStringSet allocates and returns a new CCFXStringSet instance. virtual void ThrowException( LPCSTR lpszError, LPCSTR lpszDiagnostics ) CCFXRequest::ThrowException throws an exception and ends processing of this request.
PAGE 327

Chapter 18: Building Custom CFAPI Tags 301 // Create a query that contains these columns CCFXQuery* pQuery = pRequest->AddQuery( "People", pColumns ) ; // Add data to the query int iRow ; iRow = pQuery->AddRow() ; pQuery->SetData( iRow, iFirstName, "John" pQuery->SetData( iRow, iLastName, "Smith" iRow = pQuery->AddRow() ; pQuery->SetData( iRow, iFirstName, "Jane" pQuery->SetData( iRow, iLastName, "Doe" ) ) ; ) ; ) ; ; CCFXRequest::AttributeExists BOOL CCFXRequest::AttributeExists(LPCSTR lpszName) Check
PAGE 328

302 Developing Web Applications with ColdFusion CCFXRequest::Debug BOOL CCFXRequest::Debug(void) Checks whether the tag contains the DEBUG attribute. You should use this function to determine whether or not you need to write debug information for this request. (See the CCFXRequest::WriteDebug tag for details on writing debug information.) Returns TRUE if the tag contains the DEBUG attribute; otherwise, returns FALSE.
PAGE 329

Chapter 18: Building Custom CFAPI Tags 303 You are not responsible for freeing the memory allocated for the returned string set (it will be freed automatically by ColdFusion after the request is completed). Example The following example retrieves the list of attributes and then iterates over the list, writing each attribute and its value back to the user.
PAGE 330

304 Developing Web Applications with ColdFusion (created using the CFQUERY tag or another custom tag). The QUERY attribute is optional and should only be used by tags that need to process an existing data set. Returns an object of the CCFXQuery Class that represents the query that was passed to the tag. If no query was passed to the tag, NULL is returned.
PAGE 331

Chapter 18: Building Custom CFAPI Tags 305 your extension code and then either re-throw them (if they are of the CCFXException Class) or create and throw a new exception pointer using CCFXRequest::ThrowException. e An existing CCFXException that has been caught. Example The following code demonstrates the correct way to handle exceptions in ColdFusion Extension DLL procedures: try { ...Code that could throw an exception... } catch( CCFXException* e ) { ...Do appropriate resource cleanup here...
PAGE 332

306 Developing Web Applications with ColdFusion void ProcessTagRequest( CCFXRequest* pRequest ) { try { MYTAGDATA tagData ; pRequest->SetCustomData( (LPVOID)&tagData ) ; ... remainder of procedure ... } CCFXRequest::SetVariable void CCFXRequest::SetVariable(LPCSTR lpszName, LPCSTR lpszValue) Sets a variable in the calling template. If the variable name specified already exists in the template, its value is replaced. If it does not already exist, a new variable is created.
PAGE 333

Chapter 18: Building Custom CFAPI Tags 307 CCFXRequest::ReThrowException to provide protection against resource leaks in extension code. lpszError Short identifier for error. lpszDiagnostics Error diagnostic information. Example The following example throws an exception indicating that an unexpected error occurred while processing the request: char buffError[512] ; wsprintf( buffError, "Unexpected Windows NT error number %ld " "occurred while processing request.
PAGE 334

308 Developing Web Applications with ColdFusion Example The following example checks to see whether the DEBUG attribute is present, and if it is, it writes a brief debug message: if ( pRequest->Debug() ) { pRequest->WriteDebug( "Top secret debug info" ) ; } CCFXStringSet Class Abstract class that represents a set of ordered strings. Strings can be added to a set and can be retrieved by a numeric index (the index values for strings are 1-based).
PAGE 335

Chapter 18: Building Custom CFAPI Tags 309 CCFXStringSet::GetCount int CCFXStringSet::GetCount(void) Gets the number of strings contained in the string set. This value can be used along with CCFXStringSet::GetString to iterate over the strings in the set (when iterating, remember that the index values for strings in the list begin at 1). Returns the number of strings contained in the string set.
PAGE 336

310 Developing Web Applications with ColdFusion CCFXStringSet::GetString LPCSTR CCFXStringSet::GetString(int iIndex) Retrieves the string located at the passed index (note that index values are 1-based). Returns the string located at the passed index. iIndex Index of string to retrieve.
PAGE 337

Chapter 18: Building Custom CFAPI Tags 311 Java CFX Reference Contents • Interface CustomTag • Interface Query • Interface Request • Interface Response Interface CustomTag public abstract interface CustomTag Interface for implementing custom tags. Classes that implement this interface can be specified in the CLASS attribute of the Java CFX tag. For example, if I have a class MyCustomTag which implements this interface then the following CFML code could be used to call the MyCustomTag.
PAGE 338

312 Developing Web Applications with ColdFusion response — Interface for generating response to request (output, variables, queries, etc.) Throws: Exception — If an unexpected error occurs while processing the request. Interface Query public abstract interface Query Interface to a query used or created by a CustomTag. A query contains tabular data organized by named columns and rows Method Summary int addRow() Adds a new row to the query.
PAGE 339

Chapter 18: Building Custom CFAPI Tags 313 Returns: The name of the query. getRowCount public int getRowCount() Retrieves the number of rows in the query. The following example retrieves the number of rows in a query and writes it back to the user: Query query = request.getQuery() ; int rows = query.getRowCount() ; response.write( "The number of rows in the query is " + Integer.toString(rows) ) ; Returns: The number of rows contained in the query.
PAGE 340

314 Developing Web Applications with ColdFusion Retrieves a list of the column names contained in the query. The following example retrieves the array of columns and then iterates over the list, writing each column name back to the user: // Get the list of columns from the query String[] columns = query.getColumns() ; int nNumColumns = columns.length ; // Print the list of columns to the user response.write( "Columns in query: " ) ; for( int i=0; i
PAGE 341

Chapter 18: Building Custom CFAPI Tags 315 Throws: IndexOutOfBoundsException - If an invalid index is passed to the method. See Also: setData, addRow addRow public int addRow() Adds a new row to the query. Call this method each time you want to append a row to the query. The following example demonstrates the addition of 2 rows to a query that has 3 columns (’City’, ’State’, and ’Zip’): // Define column indexes int iCity = 1, iState = 2, iZip = 3 ; // First row int iRow = query.addRow() ; query.
PAGE 342

316 Developing Web Applications with ColdFusion int iCity = 1, iState = 2, iZip = 3 ; // First row int iRow = query.addRow() ; query.setData( iRow, iCity, "Minneapolis" ) ; query.setData( iRow, iState, "MN" ) ; query.setData( iRow, iZip, "55345" ) ; // Second row iRow = query.addRow() ; query.setData( iRow, iCity, "St. Paul" ) ; query.setData( iRow, iState, "MN" ) ; query.
PAGE 343

Chapter 18: Building Custom CFAPI Tags 317 Method Summary String getAttributeList() Retrieves a list of all attributes passed to the tag. int getIntAttribute(String name) Retrieves the value of the passed attribute as an integer. int getIntAttribute(String name, int def) Retrieves the value of the passed attribute as an integer (returns default if the attribute does not exist or is not a valid number). Query getQuery() Retrieves the query that was passed to this tag.
PAGE 344

318 Developing Web Applications with ColdFusion getAttribute public String getAttribute(String name) Retrieves the value of the passed attribute. Returns an empty string if the attribute does not exist (use attributeExists to test whether an attribute was passed to the tag). Use getAttribute(String,String) to return a default value rather than an empty string. The following example retrieves an attribute named DESTINATION and writes its value back to the user: String strDestination = request.
PAGE 345

Chapter 18: Building Custom CFAPI Tags 319 Throws: NumberFormatException — If the attribute is not a valid number. See Also: attributeExists, getAttributeList, getIntAttribute(String,int) getAttributeList public String[] getAttributeList() Retrieves a list of all attributes passed to the tag. To retrieve the value of an individual attribute you should use the getAttribute member function.
PAGE 346

320 Developing Web Applications with ColdFusion "order for this tag to work correctly." ) ; } Returns: The Query that was passed to the tag. If no query was passed to the tag then null is returned. getSetting public String getSetting(String name) Retrieves the value of a global custom tag setting. Custom tag settings are stored within the CustomTags section of the ColdFusion Registry key. Note All custom tags implemented in Java share a single registry key for storing settings.
PAGE 347

Chapter 18: Building Custom CFAPI Tags 321 Returns: Returns true if the tag contains the DEBUG attribute otherwise returns false. See Also: Response.writeDebug Interface Response public abstract interface Response Interface to response generated from a CustomTag. This interface includes methods for writing output, generating queries, and setting variables within the calling page. Method Summary Query addQuery(String name, String[] columns) Adds a query to the calling template.
PAGE 348

322 Developing Web Applications with ColdFusion Sets a variable in the calling template. If the variable name specified already exists in the template then its value is replaced. If it does not already exist then a new variable is created. For example, this code sets the value of a variable named ’MessageSent’ based on the success of an operation performed by the custom tag: boolean bMessageSent ; ...attempt to send the message... if ( bMessageSent == true ) { response.
PAGE 349

Chapter 18: Building Custom CFAPI Tags query.setData( iRow, iFirstName, "John" query.setData( iRow, iLastName, "Smith" iRow = query.addRow() ; query.setData( iRow, iFirstName, "Jane" query.setData( iRow, iLastName, "Doe" ) 323 ) ; ) ; ) ; ; Parameters: name — The name of the query to add to the template columns — The column names to be used in the query Returns: The Query that was added to the template.
PAGE 350

324 Developing Web Applications with ColdFusion
PAGE 351

CHAPTER 19 Chapter 19 Using CFOBJECT to Invoke Component Objects The CFOBJECT tag is used to invoke objects created by component technologies. This includes COM/DCOM, CORBA, Java, and EJB objects. Contents • Component Object Overview........................................................................ 326 • Invoking Component Objects ....................................................................... 327 • Getting Started with COM/DCOM.........................................................
PAGE 352

326 Developing Web Applications with ColdFusion Component Object Overview This section gives you some basic information on objects supported in ColdFusion and provides resources for further inquiry. About COM COM (Component Object Model) is a specification and a set of services defined by Microsoft to enable component portability, reusability, and versioning.
PAGE 353

Chapter 19: Using CFOBJECT to Invoke Component Objects 327 Invoking Component Objects The CFOBJECT tag is used to create an instance of the object and other ColdFusion tags, such as CFSET and CFOUTPUT, are used to invoke properties (attributes), and methods (operations) on the object. An object created by CFOBJECT or returned by other objects is implicitly released at the end of the template execution. Coding guidelines The following coding practice is required (or recommended) when accessing the object.
PAGE 354

328 Developing Web Applications with ColdFusion Calling nested objects The current release of ColdFusion does not support nested (scoped) object calls. For example, if an object method returns another object and you would like to invoke a property/method on that object, the following is required: (That is, the syntax will fail.) Getting Started with COM/DCOM ColdFusion is an automation (late-binding) COM client.
PAGE 355

Chapter 19: Using CFOBJECT to Invoke Component Objects 329 deployed with their own setup programs that register objects automatically, while others may require manual registration. Inproc object servers (*.dll, *.ocx) can be registered manually by using the "regsvr32.exe" utility using the following form: regsvr32 c:\path\servername.dll Local servers (*.exe) are typically registered either by simply starting them or specifying a command line parameters like: C:\pathname\servername.
PAGE 356

330 Developing Web Applications with ColdFusion To view an object’s properties: 1. Open the Object Viewer and scroll to the object you want to examine. 2. Select and expand the object in the Object Viewer. 3. Right-click the object to view it. If you view the TypeInfo, you’ll see the object’s methods and properties. Some objects will not have any access to the TypeInfo area. This is determined when an object is built and by the language used.
PAGE 357

Chapter 19: Using CFOBJECT to Invoke Component Objects 331 Creating and Using COM Objects In the following example, an SMTP mail handling component is created using CFOBJECT. The component needs to be created by ColdFusion before any methods in the component can be invoked or properties assigned in your application pages. This sample SMTP component includes a number of methods and properties to perform a wide range of mail handling tasks..
PAGE 358

332 Developing Web Applications with ColdFusion • REMOTE — This is also an Out-of-Process server object (also typically an EXE) that is running remotely on the network. Using REMOTE implies using the SERVER attribute to identify where the object resides. Setting properties and invoking methods The following example, using the sample SMTPMailer COM object, shows how to assign properties to the mail message you want to send and how to execute component methods to handle mail messages.
PAGE 359

Chapter 19: Using CFOBJECT to Invoke Component Objects 333 • If VisiBroker is already installed on the server, the log directory is the directory pointed to by the VBROKER_ADM environment variable. • If this is a new VisiBroker installation, the log directory is created on the root of the drive from which ColdFusion Server is started. For example, if ColdFusion is installed in c:\cfusion or opt/coldfusion (UNIX), then the log directory will be c:\vbroker\log or /vbroker (UNIX).
PAGE 360

334 Developing Web Applications with ColdFusion { short s; long l; float d; }; struct NestedStruct { SimpleStruct f; char c; string s; }; typedef sequence BLongSequence; interface SomeObject { short SomeMethod( in NestedStruct inStruct, in BlongSequence inSeq); }; The applicable ColdFusion code
PAGE 361

Chapter 19: Using CFOBJECT to Invoke Component Objects 335 Calling Java Objects The CFOBJECT tag can call any Java class that’s available on the Class Path specified in the ColdFusion Administrator. For example: Although this loads the class, it doesn’t create an instance object. Static methods and fields are accessible after the call to CFOBJECT. To call the constructors explicitly, use the init method with the appropriate arguments.
PAGE 362

336 Developing Web Applications with ColdFusion
PAGE 363

CHAPTER 20 Chapter 20 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. This chapter describes the CFScript language’s functionality and syntax. Contents • About CFScript ............................................................................................... 338 • The CFScript Language.......
PAGE 364

338 Developing Web Applications with ColdFusion 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 . You can use ColdFusion expressions, but not CFML tags, inside a CFScript region. See the CFML Language Reference for more information about CFML expressions.
PAGE 365

Chapter 20: Extending ColdFusion Pages with CFML Scripting 339 • for • break • continue • for-in • switch-case For more information The following JavaScript references may be useful in understanding the concepts and control flow statements in CFScript: • Netscape’s JavaScript Guide • Netscape’s JavaScript Reference • David Flanagan’s JavaScript: The Definitive Guide, published by O’Reilly & Associates, 1996, 1998, http://www.oreilly.com.
PAGE 366

340 Developing Web Applications with ColdFusion for loop: for (init-expr ; test-expr ; final-expr) statement ; Note that 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, A LT 5, loop LE x, or Y EQ "not found" AND loop LT end • empty Here are some examples of for loops: // Multiline
PAGE 367

Chapter 20: Extending ColdFusion Pages with CFML Scripting 341 do-while loop: do statement while (expr) ; // Complete do-while loop on a single line a = ArrayNew(1); do {a[loop1] = loop1 + 5; loop1 = loop1 + 1;} while (loop1 LT 10); // Multiline do-while loop a = ArrayNew(1); do { a[loop1] = loop1 + 5; loop1 = loop1 + 1; } while (loop1 LT 10); switch-case: switch (expr) {case const-expr : statement break ; default : statement } In this syntax, const-expr must be a constant (i.e.
PAGE 368

342 Developing Web Applications with ColdFusion continue: skip to next loop iteration for ( loop=1; loop LT 10; loop = loop+1) { if(a[loop]=0) continue; a[loop]=1; } break: break out of the current switch statement or loop for( ; ; ) { indx=indx+1; if(Find("key",strings[indx],1)) break; } Expressions CFScript supports all CFML expressions. CFML expressions include operators (such as +, -, EQ, etc.) as well as all CFML functions.
PAGE 369

Chapter 20: Extending ColdFusion Pages with CFML Scripting 343 • CFScript is case-insensitive. • All statements end in a semi-colon, and line breaks in your code are insignificant. • In CFScript, assignments are statements, not expressions. • Some implicit objects are not available, such as Window and Document. Note CFScript is not directly exportable to JavaScript. Only a limited subset of JavaScript can run inside CFScript.
PAGE 370

344 Developing Web Applications with ColdFusion //‘testres' is a column in the "employees" query if( testres EQ 1 ) result="positive"; else result="negative"; Test for #name# is #result#.
PAGE 371

CHAPTER 21 Chapter 21 Accessing the Windows NT Registry The CFREGISTRY tag gives you programmatic access to the Windows Registry. Contents • Overview of Registry Access in ColdFusion ................................................. 346 • Getting Registry Values .................................................................................. 346 • Setting Registry Values................................................................................... 347 • Deleting Registry Values ...........
PAGE 372

346 Developing Web Applications with ColdFusion Overview of Registry Access in ColdFusion ColdFusion includes the CFREGISTRY tag, which allows you to get, set, and delete registry values. The registry is a database that Windows uses to maintain hierarchical information about users, hardware, and software. Under UNIX, ColdFusion includes functionality that emulates the registry. It includes keys and values: • Keys can contain either values or other keys.
PAGE 373

Chapter 21: Accessing the Windows NT Registry 347 2. Access the record set (this example uses the CFTABLE tag):
CFREGISTRY ACTION="GetAll"
PAGE 374
348 Developing Web Applications with ColdFusion If the specified value does not exist, ColdFusion creates it. If the value already exists, ColdFusion updates the value data.
PAGE 375

Index A Accessing collections 181 Action pages 34 Active Server Pages 242 Advanced security implementing 265 Allaire xxiv contacting xxiv headquarters xxiv sales xxv technical support xxiv Ancestor tags 77 AND operator 23, 40 Application Framework, Web custom error pages 93 Application Framwork 184 Application pages 6 creating 10 description of 6 errors 93 naming 3, 14 processing of 7 saving 11 viewing 11 viewing source code of 11 Application servers data exchange across 243 Application variables lifetime
PAGE 376

350 CFAUTHENTICATE tag 185, 266 example 270 syntax 266 using SETCOOKIE 266 CFCATCH tag 95 CFCONTENT tag 239 CFDIRECTORY tag 239 CFELSE tag 42, 53 CFELSEIF tag 53 CFERROR page 93 CFERROR tag 185 CFEXIT tag 84, 185 CFFILE tag 220, 237 CFFORM tag 124 CFFTP tag 239 CFGRID tag 135 CFHTTP tag 78, 232 CFHTTPPARAM tag 78, 236 CFID 191 CFIF tag 40, 53 CFINCLUDE 187 CFINCLUDE tag 72 CFINDEX tag 157 CFINPUT tag 127 CFINSERT tag 60 CFLDAP tag 162, 252 CFLOCATION tag 192 CFLOCK tag 198, 200 nesting 199 CFLOOP tag 84 CF
PAGE 377

Index descendants 77 distributing 291 downloading 73 encrypting 86 executing 82 execution modes 83 installing 85 local 85 location of 73 managing 85 naming 73 nesting 77 parent 77 restricting access to 86 shared 85 using existing 73 D Data converting to JavaScript Object 245 exchanging 241 passing 78 selecting 30 transferring from browser to server 246 Data sources 2, 7, 18 adding 19 connecting to 20 LDAP 7 naming 19 native database drivers 7 ODBC 7 OLE-DB 7 types of 16 Database design 2 Database exceptio
PAGE 378

352 CFFORM 124 Form fields required 68 Form variables in queries 35 naming 34 processing 34 referring to 34 testing 36 Formatting data items 38 query results 38 Forms 30 checkboxes 47 creating 55, 61 creating with CFFORM 124 deleting data 66 designing 34 drop-down list boxes 143 dynamically populating 46 HTML 30 inserting data 60 Java applets in 144 multiple select lists 49 slider bars 142 text entry boxes 142 tree controls 129 updating data 63 validating data in 68 FROM clause 21, 22 FTP 239 Functions str
PAGE 379

Index relational 173 score 177 searching 171 SQL 23 OR operator 23 ORDER BY clause 22 353 records returned 27 Querying LDAP directories 254 Quotes using 21, 51 R P Parameters dynamic SQL 53 Parent tags 77 Pattern matching 39 Perl 242 POP 7 Populating arrays 108 ArraySet 108 CFLOOP 108 from queries 110 nested loops 109 Populating collections 157 Post method 232, 236 Pound signs using 13 Protecting code 198 data 198 Punctuation searching 170 Python 242 Q Queries building 21, 24 building graphically 21 cr
PAGE 380

354 application-level 184 Shared data modifying 199 Single quotes 21, 51 in form field values 49 using 21 Slider bar controls 142 SMTP 206 Special characters searching 170 SQL 2, 20, 21 clauses 22 dynamic 53, 56 dynamic parameters 53 INSERT statement 61 non-standard 23 operators 23 single quotes in 49, 51 statements 22 syntax elements 22 text literals in 21 UPDATE statement 62 WHERE clause 35 SQL Server 18 SSL 238 export laws 238 standard 191 Structured Query Language See SQL Structures 113 adding data to