Sending Email from ColdFusion - macromedia COLDFUSION MX 7 Web Application Construction Kit [Electronic resources] نسخه متنی

اینجــــا یک کتابخانه دیجیتالی است

با بیش از 100000 منبع الکترونیکی رایگان به زبان فارسی ، عربی و انگلیسی

جستجو بر اساس ... همه عنوان پدیدآور موضوع یادداشت تمام متن
اصطلاحنامه مجموعه ها مرورالفبایی لغت نامه دهخدا
➟
جستجو در لغت نامه
بیشتر
کتابخانه شخصی پرسش از کتابدار ارسال منبع

macromedia COLDFUSION MX 7 Web Application Construction Kit [Electronic resources] - نسخه متنی

Ben Forta, Raymond Camden, Leon Chalnick, Angela Buraglia

| نمايش فراداده ، افزودن یک نقد و بررسی
افزودن به کتابخانه شخصی
میخواهم بخوانم
درحال خواندن
خوانده شده
ارسال به دوستان

آدرس پست الکترونیک گیرنده :

آدرس پست الکترونیک فرستنده :

نام و نام خانوارگی فرستنده :

پیغام برای گیرنده ( حداکثر 250 حرف ) :

کد امنیتی را وارد نمایید

ارسال
جستجو در متن کتاب
بیشتر
تنظیمات قلم

فونت

اندازه قلم

+ - پیش فرض

حالت نمایش

روز نیمروز شب
➟
جستجو در لغت نامه
بیشتر
لیست موضوعات

Copyright Credits NOTICE OF RIGHTS NOTICE OF LIABILITY TRADEMARKS DEDICATION ACKNOWLEDGMENTS Introduction Who Should Use This Book How to Use This Book Part I of this book introduces ColdFusion and explains what exactly it is that ColdFusion enables you to accomplish. Internet fundamentals are also introduced; a thorough understanding of these is a prerequisite to ColdFusion application development. This part also includes coverage of databases, SQL, Macromedia Dreamweaver MX 2004, and everything else you need to know to get up and running quickly.In Chapter 1, "Introducing ColdFusion," the core technologies ColdFusion is built on are introduced. The Internet and how it works are explained, as are DNS servers and URLs, Web servers and browsers, HTML, and Web server extensions. A good understanding of these technologies is a vital part of creating Web-based applications. This chapter also teaches you how ColdFusion works and explains the various components that comprise it.Chapter 2, "Introducing Macromedia Dreamweaver MX 2004," introduces Dreamweaver as a ColdFusion development environment. Dreamweaver is a powerfu267 and CFML editor, as well as a mature and trusted page layout and design tool. You learn how to use the editor, how to work with sites, as well as how to configure the environment to work the way you do.Chapter 3, "Accessing the ColdFusion Administrator," introduces the ColdFusion Administrator program. This Web-based program, written in ColdFusion itself, manages and maintains every aspect of your ColdFusion Application Server.To whet your appetite, Chapter 4, "Previewing ColdFusion," walks you through creating two real, working applications using Macromedia Dreamweaver MX 2004 code generation and also manually.Chapter 5, "Building the Databases," provides a complete overview of databases and related terms. Databases are an integral part of almost every ColdFusion application, so database concepts and technologies must be well understood. Databases are mechanisms for storing and retrieving information, and almost every Web-based application you build will sit on top of a database of some kind. Key database concepts, such as tables, rows, columns, data types, keys, and indexes, are taught, as are the basics of the relational database model. You also learn the differences between client-server- and shared-file-based databases, as well as their pros and cons.In Chapter 6, "Introducing SQL," you learn the basics of the SQL language. SQL is a standard language for interacting with database applications, and all ColdFusion database manipulation is performed using SQL statements. The link between ColdFusion and your database itself is via database drivers, so this chapter introduces this technology and walks you through the process of creating data sources. This chapter also teaches you how to use the SQL SELECT statement.Chapter 7, "SQL Data Manipulation," introduces three other important SQL statements: INSERT, UPDATE, and DELETE.Part IIUsing ColdFusion Part II concentrated on ColdFusion coding. In Part III, all the ideas and concepts are brought together in the creation of complete applications.Experienced developers know that it takes careful planning to write good code. Chapter 18, "Planning an Application," teaches important design and planning techniques that you can leverage within your own development.In Chapter 19, "Introducing the Web Application Framework," you learn how to take advantage of the ColdFusion Web application framework to facilitate the use of persistent variables, sophisticated parameter and variable manipulation, and customized error message handling. You also learn how to use the application template to establish applicationwide settings and options and how to use the APPLICATION scope.Chapter 20, "Working with Sessions," teaches you all you need to know about CLIENT and SESSION variables, as well as HTTP cookies. These special data types play an important part in creating a complete application that can track a client's state.Chapter 21, "Securing Your Applications," introduces important security concepts and explains which you should worry about and why. You learn how to create login screens, access control, and more.Chapter 22, "Building User-Defined Functions," introduces the <cffunction> tag and explains how it can (and should) be used to extend the CFML language.Chapter 23, "Building Reusable Components," explains two other code reuse options; custom tags and ColdFusion Components. Both are extremely important application building blocks, and so you'll learn exactly what they are, when to use them, and how to do so.Chapter 24, "Improving the User Experience," helps you create applications that really get used. You learn important user interface concepts, how to build sophisticated browse screens, and much more.Developers are always looking for ways to tweak their code, squeezing a bit more performance wherever possible. Chapter 25, "Improving Performance," provides tips, tricks, and techniques you can use to create applications that will always be snappy and responsive.Macromedia Flash is fast becoming the tool of choice for the creation of rich, highly interactive, portable, and lightweight user interfaces. Chapter 26, "Integrating with Macromedia Flash MX," introduces Flash from a ColdFusion developer's perspective and explains how the two can be used together using new Flash remoting capabilities.Chapter 27, "Interacting with Email," introduces ColdFusion's email capabilities. ColdFusion enables you to create SMTP-based email messages using its <cfmail> tag. You learn how to send email messages containing user-submitted form fields, how to email the results of a database query, and how to do mass mailings to addresses derived from database tables. Additionally, you learn how to retrieve mail from POP mailboxes using the <CFPOP> tag.Chapter 28, "Online Commerce," teaches you how to perform real-time electronic commerce, including credit card authorization. You build an entire working shopping-cart applicationone you can use as a stepping-stone when writing your own shopping applications.Part IVAdvanced ColdFusion Appendix A, "Installing ColdFusion MX and Dreamweaver MX," goes over system, hardware, and operating-system prerequisites and explains how to install both products. Installation of the sample applications used in this book is also explained.Appendix B, "ColdFusion Tag Reference," is an alphabetical listing of all CMFL tags and descriptions, complete with examples for each and extensive cross-referencing.Appendix C, "ColdFusion Function Reference," is a complete listing of every CFML function organized by category, complete with examples for each and extensive cross-referencing.Appendix D, "Special ColdFusion Variables and Result Codes," lists every special variable, prefix, and tag result code available within your applications.Appendix E, "Verity Search Language Reference," is a complete guide to the Verity search language. Using the information provided here, you will be able to perform incredibly complex searches with minimal effort.Appendix F, "ColdFusion MX 7 Directory Structure," explains the directories and files that make up ColdFusion MX 7, providing lots of useful tips and tricks in the process.Appendix G, "Sample Application Data Files," lists the format of the database tables used in the sample applications throughout this book. The accompanying CD-ROM contains everything you need to start writing ColdFusion applications, including:ColdFusion MX 7 (can be used as an Evaluation Version or as a Developer Edition).Evaluation edition of Macromedia Dreamweaver MX 2004.Evaluation edition of Macromedia Flash MX 2004.Source code and databases for all the examples in this bookElectronic versions of all chapters in Part IV, Advanced ColdFusion. Any versions of Coldfusion MX 7 not included on this CD-ROM can be found on the Macromedia Web site.So turn the page and start reading. In no time, you'll be creating powerful applications powered by ColdFusion MX 7. Part 1: Getting Started Chapter 1. Introducing ColdFusion The Basics The Internet Internet Applications DNS Intranets, Extranets, and Portals Web Servers Web Pages Web Browsers CAUTION URLs Hosts and Virtual Hosts Understanding ColdFusion The Dynamic Page Advantage Understanding Web Applications What Is ColdFusion? ColdFusion and Your Intranet, Extranet, and Portal ColdFusion Explained The ColdFusion Application Server NOTE TIP The ColdFusion Markup Language Linking to External Applications Extending ColdFusion Beyond the Web Inside ColdFusion MX 7 NOTE Powered by ColdFusion Chapter 2. Introducing Macromedia Dreamweaver MX 2004 Dreamweaver MX 2004 Overview Preparing to Use Dreamweaver ON THE CD NOTE Creating the Application Root NOTE Starting Dreamweaver for the First Time NOTE NOTE Site Definitions Creating the Site NOTE TIP NOTE About the Advanced Site Definition Dialog TIP NOTE TIP Working with Files Creating a Work Directory and File TIP TIP Saving, Closing, and Opening Files TIP TIP TIP Testing the Page TIP The Dreamweaver Workspace The Files Panel NOTE TIP NOTE The Document Window Managing Panels NOTE TIP Code Editing Code Hints and Tag Completion TIP The Code Panel Group TIP TIP NOTE TIP The Application Panel Group TIP Design Tools The Design Panel Group The Insert Bar TIP TIP NOTE NOTE TIP TIP TIP The Property Inspector TIP Customizing Dreamweaver NOTE Commands TIP Keyboard Shortcuts Extensions NOTE Preferences TIP NOTE NOTE Getting Help TIP The Macromedia Forums Chapter 3. Accessing the ColdFusion Administrator NOTE TIP Logging Into (and Out of) the ColdFusion Administrator NOTE TIP NOTE NOTE Using the ColdFusion Administrator Creating a Data Source Defining a Mail Server NOTE Enabling Debugging NOTE Viewing Settings TIP TIP NOTE Chapter 4. Previewing ColdFusion Preparing to Learn ColdFusion TIP CAUTION Using Dreamweaver Code Generation Preparing to Create an Application TIP TIP TIP TIP TIP Creating an Application in Dreamweaver TIP TIP NOTE TIP Trying It Yourself Browsing the Examples and Tutorials Chapter 5. Building the Databases Database Fundamentals Databases: A Definition Where Are Databases Used? Clarification of Database-Related Terms Data Types Using a Database A Database Primer Understanding Relational Databases TIP NOTE Primary and Foreign Keys TIP NOTE Different Kinds of Relationships Multi-Table Relationships Indexes Using Indexes CAUTION TIP Indexing on More than One Column Understanding the Various Types of Database Applications Shared-FileBased Databases Client/ServerBased Databases Which Database Product to Use Understanding the OWS Database Tables NOTE The Films Table The Expenses Table The Directors Table The FilmsDirectors Table The Actors Table The FilmsActors Table The FilmsRatings Table The UserRoles Table The Contacts Table The Merchandise Table The MerchandiseOrders Table The MerchandiseOrdersItems Table Chapter 6. Introducing SQL Understanding Data Sources Creating A Data Source Creating a Data Source From Within Dreamweaver TIP NOTE Creating a Data Source Using The ColdFusion Administrator NOTE Preparing to Write SQL Queries NOTE CAUTION NOTE Creating Queries TIP NOTE Sorting Query Results Filtering Data Filtering on a Single Column Filtering on Multiple Columns CAUTION The AND and OR Operators Evaluation Precedence TIP WHERE Conditions TIP Chapter 7. SQL Data Manipulation Adding Data NOTE Using the INSERT Statement TIP Understanding INSERT NOTE NOTE Modifying Data Understanding UPDATE CAUTION Making Global Updates Deleting Data TIP Part 2: Using ColdFusion Chapter 8. Using ColdFusion NOTE TIP TIP TIP NOTE NOTE TIP TIP NOTE Working with Expressions Building Expressions When To Use #, and When Not To Using ColdFusion Data Types NOTE Lists NOTE Arrays Structures "Dumping" Expressions TIP Commenting Your Code Chapter 9. CFML Basics Working with Conditional Processing If Statements NOTE Basic If Statements TIP Multi-condition If Statements TIP TIP If and Else Multiple If Statements NOTE Putting It All Together NOTE NOTE NOTE CAUTION NOTE Switch Statements Using Looping The Index Loop TIP The List Loop NOTE Nested Loops Reusing Code Revisiting Variables TIP Chapter 10. Creating Data-Driven Pages Accessing Databases NOTE Static Web Pages Dynamic Web Pages TIP TIP Understanding Data-Driven Templates CAUTION NOTE NOTE CAUTION NOTE TIP The Dynamic Advantage TIP Displaying Database Query Results Displaying Data Using Lists NOTE CAUTION Displaying Data Using Tables TIP TIP CAUTION NOTE Using Query Variables TIP TIP Grouping Result Output TIP Using Data Drill-Down Introducing Dynamic SQL NOTE Implementing Data Drill-Down Interfaces NOTE NOTE NOTE Displaying Data Using Frames NOTE TIP TIP Debugging Dynamic Database Queries NOTE TIP Chapter 11. The Basics of Structured Development Understanding Structured Development Single-Tier Applications Multi-Tier Applications Introducing ColdFusion Components NOTE NOTE Creating Your First CFC NOTE TIP TIP TIP TIP TIP NOTE Using ColdFusion Components NOTE NOTE Using Dreamweaver CFC Support NOTE NOTE NOTE TIP TIP TIP TIP NOTE More On Using ColdFusion Components Where to Save CFCs Unit Testing Documenting ColdFusion Components NOTE Chapter 12. ColdFusion Forms Creating Forms CAUTION TIP Form Submission Error Messages Processing Form Submissions Processing Text Submissions Processing Check Boxes and Radio Buttons Processing List Boxes Processing Text Areas TIP Processing Buttons TIP Creating Dynamic SQL Statements Building Truly Dynamic Statements Understanding Dynamic SQL NOTE NOTE Concatenating SQL Clauses NOTE Creating Dynamic Search Screens Chapter 13. Form Data Validation Understanding Form Validation Comparing Server-Side and Client-Side Validation Pros and Cons of Each Option TIP Using Server-Side Validation Using Manual Server-Side Validation TIP TIP Using <cfparam> Server-Side Validation Using Automatic Server-Side Validation CAUTION NOTE NOTE Using Client-Side Validation Understanding Client-Side Validation NOTE Client-Side Validation Via <cfform> NOTE NOTE TIP NOTE Extending <cfinput> Validation Options NOTE Specifying An Input Mask Validating On The Server And Client Preventing Multiple Form Submissions Putting It All Together Chapter 14. Using Forms to Add or Change Data Adding Data with ColdFusion Creating an Add Record Form TIP NOTE Processing Additions TIP NOTE Introducing <cfinsert> TIP CAUTION Controlling <cfinsert> Form Fields Collecting Data for More Than One INSERT <cfinsert> Versus SQL INSERT TIP Updating Data with ColdFusion Building a Data Update Form Processing Updates Introducing <cfupdate> CAUTION <cfupdate> Versus SQL UPDATE Deleting Data with ColdFusion Reusing Forms Creating a Complete Application NOTE TIP Chapter 15. Beyon259 Forms: Flash and XForms Using Flash Forms A Brief Introduction to Flash NOTE Introducing Flash Forms Getting Started With Flash Forms Flash Forms Controls NOTE NOTE Managing Form Layout NOTE Controlling Form Appearance NOTE TIP NOTE NOTE Using Data Bindings NOTE Using XForms Understanding XForms Barriers to XForms Adoption ColdFusion and XForms Where Do XSL Files Go? NOTE NOTE Chapter 16. Graphing, Printing, and Reporting Generating Graphs Building Simple Charts NOTE NOTE NOTE NOTE NOTE NOTE TIP Formatting Your Charts NOTE NOTE NOTE NOTE NOTE Using Multiple Data Series NOTE Drilling Down from Charts NOTE NOTE Additional Charting Topics Creating Printable Pages Using the <cfdocument> Tag NOTE Controlling Output using The <cfdocumentitem> Tag NOTE Defining Sections with <cfdocumentsection> Generating Reports Understanding the ColdFusion Report Builder NOTE NOTE Using the Setup Wizard NOTE NOTE Introducing the ColdFusion Report Builder Using the Report Wizard NOTE NOTE TIP TIP Running Your Reports Invoking Reports from Within ColdFusion Code And A Whole Lot More Too NOTE Chapter 17. Debugging and Troubleshooting Troubleshooting ColdFusion Applications Understanding What Can Go Wrong Debugging Web Server Configuration Problems TIP TIP Debugging Data Driver Errors TIP TIP TIP Debugging SQL Statement or Logic Errors CAUTION NOTE TIP Debugging ColdFusion Syntax Errors TIP Inspecting Variable Contents TIP TIP Using the Document Validator TIP NOTE Debugging URL and Path Problems TIP TIP Debugging Form Problems Using the ColdFusion Debugging Options TIP CAUTION Classic Debugging NOTE Dockable Debugging Dreamweaver Debugging Using Debugging Options NOTE Using Tracing Using the ColdFusion Log Files TIP Preventing Problems Part 3: Building ColdFusion Applications Chapter 18. Planning an Application Getting Started on Your Application Defining the Project NOTE TIP Knowing the Players Fact Finding Planning the Process Design Documents Planning the Testing Phase While You Are Working Charting Page Flow Include Files and Custom Tags Commenting Style Naming Conventions Keeping the Directory Structure in Mind TIP Moving Targets and Feature Creep Chapter 19. Introducing the Web Application Framework Using Application.cfc NOTE NOTE Placement of Application.cfc NOTE Application.cfc Structure A Basic Application.cfc Template Using OnRequestEnd() Using Application Variables What Are Application Variables? When to Use Application Variables Using the Application.cfc Component NOTE Using Application Variables Initializing Application Variables Putting Application Variables to Work Customizing the Look of Error Messages Introducing the <cferror> Tag Request vs. Exception Error Templates NOTE NOTE Creating a Customized Request Error Page NOTE Additional ERROR Variables NOTE TIP Creating a Customized Exception Error Page Creating a Customized Validation Error Page Using the OnError Method NOTE Using Locks to Protect Against Race Conditions NOTE NOTE NOTE What Is A Race Condition? NOTE NOTE NOTE NOTE <cflock> Tag Syntax Using Exclusive Locks TIP Using ReadOnly Locks NOTE NOTE TIP NOTE Using Named Locks instead of SCOPE NOTE Nested Locks and Deadlocks Locking with ColdFusion 5 and Earlier Application Variable Timeouts Adjusting Timeouts Using APPLICATIONTIMEOUT NOTE NOTE Adjusting Timeouts Using the ColdFusion Administrator Using onRequest() Chapter 20. Working with Sessions Addressing the Web's Statelessness The Problem of Maintaining State Solutions Provided by ColdFusion NOTE Choosing Which Type of Variables to Use Using Cookies to Remember Preferences NOTE Introducing the COOKIE Scope A Simple Cookie Exercise Using Cookies Gaining More Control with <cfcookie> NOTE Sharing Cookies with Other Applications TIP Cookie Limitation Using Client Variables NOTE NOTE How Do Client Variables Work? Enabling Client Variables NOTE Using Client Variables NOTE Deleting Client Variables NOTE Adjusting How Client Variables Are Stored NOTE NOTE TIP NOTE TIP NOTE NOTE Using Client Variables Without Requiring Cookies TIP Storing Complex Data Types in Client Variables Using Session Variables What Are Session Variables? Enabling Session Variables Using Session Variables Using Session Variables for Multiple-Page Data Entry TIP TIP NOTE When Does a Session End? NOTE NOTE Using Session Variables without Requiring Cookies TIP Other Examples of Session Variables Locking Revisited Sessions and the <cflock> Tag NOTE Working with onSessionStart and onSessionEnd Chapter 21. Securing Your Applications Options for Securing Your Application SSL Encryption TIP TIP HTTP Basic Authentication NOTE TIP NOTE Application-Based Security ColdFusion's <cflogin> Framework ColdFusion Sandbox Security NOTE Operating System Security Using ColdFusion to Control Access Deciding What to Protect Using Session Variables for Authentication Checking and Maintaining Login Status Restricting Access to Your Application NOTE Creating a Login Page NOTE NOTE TIP NOTE TIP Verifying the Login Name and Password TIP NOTE Personalizing Based on Login Being Careful with Passed Parameters NOTE Other Scenarios TIP NOTE Using ColdFusion's <cflogin> Framework NOTE Tags and Functions Provided by the <cflogin> Framework Using <cflogin> and <cfloginuser> NOTE NOTE Using getAuthUser() in Your Application Pages Using Roles to Dynamically Restrict Functionality NOTE Using Operating System Security Defending against Cross-Site Scripting Chapter 22. Building User-Defined Functions Thinking About Extending CFML Think about the CFML functions you already know. Almost all of them accept at least one piece of information, do something with the information internally, and then return some kind of result. For instance, ColdFusion's uCase() function accepts one piece of information (a string), performs an action (converts it to uppercase), then returns a result.So you can think of most functions as being like little engines, or mechanisms on an assembly line. Some functions accept more than one piece of information (more than one argument), but the point is still the same: almost all functions are about accepting input and creating some kind of corresponding output. A function's arguments provide the input, and its output is passed back as the function's return value.As the designer of your own functions, you get to specify the input by declaring one or more arguments. You also get to pass back whatever return value you wish. Building Your First UDF Basic Steps NOTE Using the Function UDF Tag Syntax NOTE Using Local Variables NOTE NOTE NOTE Where to Save Your UDFs Creating Libraries of Related UDFs Designing the UDF Library Putting the UDF Library to Use Creating General-Purpose UDFs Things to Consider Writing the SimpleJavaScriptFunctions Library NOTE NOTE Another Example Library: ColorFunctions Sharing UDF Libraries with Others Chapter 23. Building Reusable Components Easy, Powerful Extensibility Introducing CFML Custom Tags The Basic Custom Tag Idea Why Modularity Is a Good Thing How to Use Custom Tags Finding Tags on the Developer Exchange NOTE NOTE How to "Install" a Custom Tag TIP NOTE NOTE NOTE NOTE Using Custom Tags NOTE Changing the Custom Tag Search Path NOTE NOTE Placing Custom Tags in the Current Directory Controlling Template Locations with <cfmodule> Introducing the <cfmodule> Tag TIP Calling Modules by Name NOTE NOTE Calling Modules by Template Location NOTE NOTE Writing Custom Tags That Display Information Writing Your First Custom Tag Introducing the attributes Scope NOTE NOTE NOTE Making Attributes Optional or Required Using <cfparam> to Establish Default Values NOTE NOTE NOTE Who Are You Developing For? NOTE Querying and Displaying Output TIP Custom Tags Versus <cfinclude> Custom Tags That Process Data NOTE Introducing the CALLER Scope Returning Variables to the Calling Template NOTE Variable Names as Tag Attributes Using <cfparam> with type="variableName" NOTE Setting a Variable Dynamically Custom Tags That Encapsulate Business Rules Custom Tags for General-Purpose Use NOTE NOTE Sharing Your Custom Tags NOTE Additional Custom Tag Topics Paired Custom Tags Associating Nested Custom Tags NOTE Passing Attributes with attributeCollection The REQUEST Scope Introducing ColdFusion Components About ColdFusion Components NOTE The Two Types of Components Your First CFC The Structure of a CFC File NOTE NOTE A Simple Example Using the CFC in ColdFusion Pages NOTE A More Complete CFC CFCs as Collections of Functions NOTE TIP TIP Using the FilmData CFC NOTE Separating Logic from Presentation Accessing a CFC via a URL NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE Accessing a CFC via a Form NOTE Exploring CFCs in Dreamweaver TIP NOTE NOTE NOTE NOTE TIP TIP Components that Hold Instance Data Introducing the THIS Scope NOTE An Instance Data CFC Example TIP TIP NOTE Storing CFCs in the APPLICATION Scope NOTE Storing CFCs in the SESSION Scope Instance Data as Properties NOTE NOTE NOTE NOTE CFCs, Shared Scopes, and Locking Learning More About CFCs Learning About Advanced CFC Concepts Chapter 24. Improving the User Experience Usability Considerations Put yourself in the User's Shoes TIP Easing the Browser's Burden NOTE NOTE Remembering Settings Remembering User Names and Passwords Other Helpful Settings to Remember Avoid the "Big Brother" Effect Creating Next-n Records Interfaces Advantages of Next-n Interfaces When to Create a Next-n Interface TIP Creating the Basic Interface NOTE Alternating Row Colors for Readability TIP Letting the User Browse Page by Page Adding Show All and Filter Options Returning Page Output Right Away with <cfflush> When to Clear the Buffer NOTE The Exception, Not the Rule Introducing the <cfflush> Tag Flushing the Output Buffer for Large Pages Flushing the Output Buffer for Long-Running Processes NOTE NOTE When You Can't Flush the Buffer TIP Chapter 25. Improving Performance Options in the ColdFusion Administrator Improving Query Performance with Caching NOTE Understanding Query Caching NOTE NOTE Using Cached Queries NOTE Refreshing Cached Queries Programmatically NOTE NOTE NOTE Limiting the Number of Cached Queries NOTE Controlling How Many Records Are Fetched at Once NOTE NOTE Caching Page Output Introducing the <cfcache> Tag Client-Side Page Caching NOTE TIP TIP Server-Side Page Caching NOTE ColdFusion-Optimized Caching NOTE NOTE Flushing the Page Cache NOTE Understanding the Issue Automatic White-Space Control Suppressing White-Space Output with <cfsilent> NOTE Suppressing Specific White Space with <cfsetting> Chapter 26. Integrating with Macromedia Flash Flash Integration Concepts Macromedia Flash MX 2004 The Flash 7 Player NOTE ColdFusion Components Flash Remoting ActionScript Your First Flash Movie What You Need to Install NOTE NOTE Creating a Movie NOTE Placing the Movie on a ColdFusion Page NOTE NOTE Using Flash Remoting NOTE ColdFusion Pages as Services NOTE Your First Flash Remoting Project NOTE NOTE TIP NOTE NOTE NOTE Creating the ColdFusion Code NOTE Testing the Example More About Returning Data to Flash NOTE Working with Recordsets in Flash About RecordSet Objects NOTE RecordSet Functions NOTE NOTE A Complete Example NOTE Calling CFC Methods from Flash NOTE ColdFusion Components as Services Calling CFC Methods NOTE Instantiated CFCs Other Cool Flash Remoting Features Debugging Flash Remoting Projects The Data Glue Object Incrementally Loading Recordsets NOTE TIP Security and Logging In from Flash TIP Other Integration Methods NOTE Chapter 27. Interacting with Email Sending Email from ColdFusion NOTE Introducing the <cfmail> Tag NOTE Specifying a Mail Server in the Administrator TIP Sending Email Messages TIP NOTE Sending Data-Driven Mail NOTE Sendin262-Formatted Mail Adding Custom Mail Headers TIP Adding Attachments NOTE TIP TIP NOTE Overriding the Default Mail Server Settings NOTE Retrieving Email with ColdFusion Introducing the <cfpop> Tag Retrieving the List of Messages NOTE NOTE NOTE Receiving and Deleting Messages Receiving Attachments NOTE Creating Automated POP Agents NOTE Chapter 28. Online Commerce Building E-commerce Sites Common Commerce-Site Elements NOTE NOTE NOTE NOTE Using a Secure Server Creating Storefronts Displaying Individual Items Collecting Items into a Store TIP Creating Shopping Carts Storing Cart Information Building a Shopping Cart TIP NOTE NOTE Encapsulating the Shopping Cart in a Custom Tag NOTE NOTE A ColdFusion Component Version of the Shopping Cart NOTE NOTE Payment Processing Payment-Processing Solutions NOTE Processing a Payment NOTE NOTE NOTE NOTE NOTE NOTE Processing a Complete Order Creating the Checkout Page Other Commerce-Related Tasks Order Tracking Order Fulfillment Cancellations, Returns, and Refunds Inventory Tracking Reporting Part 4: Advanced ColdFusion Part 5: APPENDICES Appendix A. Installing ColdFusion MX 7, Dreamweaver MX 2004, and the Sample Files Dreamweaver MX 2004 ColdFusion MX 7 The Different Flavors of ColdFusion MX 7 NOTE Pre-Installation Checklist Checking Your Hardware NOTE Choosing Your Hardware Checking Your Web Server Installing ColdFusion On Windows TIP Installing ColdFusion On Linux and Unix TIP The ColdFusion Report Builder is a Windows application (although reports created with it can be processed by all editions of ColdFusion on all platforms).The ColdFusion Report Builder is installed along with ColdFusion. In addition, the Report Builder installer is itself installed in /CFIDE/Installers (under the ColdFusion root) as CFReportBuilder Installer.exe. You can run this installer to manually install the Report Builder on development machines. Installing Dreamweaver Extensions Samples & Data Files What to Install CAUTION Installing the OWS Files IN THIS APPENDIXTag Groups by Function 977Alphabetical List of ColdFusion Tags 983ColdFusion tags are the CFML extensions t270. These tags are the instructions to ColdFusion to perform database queries, process results, generate output, control program flow, handle errors, send and receive email, and much more.In this chapter, the tags are presented in alphabetical order and are cross-referenced to related tags wherever appropriate. Tag Groups by Function Database Manipulation Data Output Extensibility Variable Manipulation Flow Control Debugging Tools Internet Protocols File Management Web Application Framework ColdFusion Forms Security CFML Utilities Verity Search Alphabetical List of ColdFusion Tags <cfabort> TIP <cfapplet> NOTE NOTE NOTE <cfapplication> <cfargument> <cfassociate> <cfbreak> <cfcache> NOTE <cfcalendar> <cfcase> <cfcatch> <cfchart> <cfchartdata> <cfchartseries> <cfcol> <cfcollection> NOTE NOTE NOTE <cfcomponent> NOTE <cfcontent> NOTE NOTE <cfcookie> NOTE TIP NOTE NOTE <cfdefaultcase> <cfdirectory> CAUTION <cfdocument> <cfdocumentitem> <cfdocumentsection> <cfdump> <cfelse> <cfelseif> <cferror> NOTE <cfexecute> NOTE NOTE <cfexit> <cffile> NOTE NOTE CAUTION <cfflush> NOTE <cfform> NOTE NOTE <cfformgroup> <cfformitem> <cfftp> NOTE CAUTION <cffunction> NOTE <cfgraph> <cfgraphdata> <cfgrid> NOTE <cfgridcolumn> <cfgridrow> <cfgridupdate> <cfheader> NOTE <cfhttp> NOTE <cfhttpparam> <cfif> <cfimpersonate> <cfimport> NOTE <cfinclude> NOTE CAUTION <cfindex> <cfinput> NOTE <cfinsert> NOTE TIP TIP <cfinvoke> NOTE NOTE NOTE <cfinvokeargument> NOTE NOTE <cfldap> <cflocation> NOTE NOTE NOTE <cflock> CAUTION <cflog> <cflogin> NOTE NOTE NOTE NOTE <cfloginuser> <cflogout> <cfloop> NOTE TIP NOTE <cfmail> NOTE NOTE NOTE NOTE NOTE <cfmailparam> <cfmailpart> <cfmodule> NOTE NOTE <cfntauthenticate> NOTE <cfobject> NOTE NOTE <cfobjectcache> <cfoutput> NOTE NOTE <cfparam> name <cfpop> NOTE <cfprocessingdirective> TIP NOTE NOTE <cfprocparam> <cfprocresult> <cfproperty> NOTE <cfquery> <cfqueryparam> TIP <cfregistry> NOTE CAUTION <cfreport> <cfreportparam> <cfrethrow> <cfreturn> <cfsavecontent> <cfschedule> NOTE <cfscript> <cfsearch> <cfselect> <cfservlet> <cfservletparam> <cfset> TIP <cfsetting> NOTE <cfsilent> <cfslider> NOTE <cfstoredproc> <cfswitch> NOTE <cftable> NOTE <cftextarea> <cftextinput> <cfthrow> <cftimer> NOTE <cftrace> NOTE <cftransaction> NOTE NOTE NOTE <cftree> NOTE <cftreeitem> <cftry> <cfupdate> NOTE TIP TIP <cfwddx> <cfxml> Appendix C. ColdFusion Function Reference The following sections list ColdFusion by topics, meaning that the functions in each section perform related tasks. String-Manipulation Functions The ColdFusion Date and Time functions enable you to perform date and time manipulations on table columns and user-supplied fields.Many of these functions work with date/time objects. A date/time object is a ColdFusion internal representation of a complete date and time. These objects are designed to facilitate the passing of date/time information between various ColdFusion functions and are not designed to be displayed as is. If you need to display a date/time object, you must use one of the date/time formatting functions.NOTE Year values of less than 100 are treated as 20th-century values, and 1900 is added automatically to them.Several of the ColdFusion date and time functions enable you to work with parts of the complete date/time objectto add days or weeks to a date, or to find out how many weeks apart two dates are, for example. These functions require you to pass a date/time part specifier that is passed as a string. (They must have quotation marks around them.) The complete list of specifiers is explained in Table C.3.Table C.3. ColdFusion Date/Time Specifiers SPECIFIERDESCRIPTIONDDayHHourMMonthNMinuteQQuarterSSecondLMillisecondWWeekday (day of week)WWWeekYDay of yearYYYYYearTable C.4 contains the available functions for date- and time-related processing.Table C.4. Date and Time Functions FUNCTIONDESCRIPTIONCreateDate()Returns a ColdFusion date/time object that can be used with other date-manipulation or formatting functionsCreateDateTime()Returns a ColdFusion date/time object that can be used with other date- and time-manipulation or formatting functionsCreateODBCDate()Returns a date in an ODBC date/time field that can safely be used in SQL statementsCreateODBCDateTime()Returns an ODBC date/time field that can safely be used in SQL statementsCreateODBCTime()Returns a time in an ODBC date/time field that can safely be used in SQL statementsCreateTime()Returns a time in a ColdFusion date/time object that can be used with other time-manipulation or formatting functionsCreateTimeSpan()Creates a date/time object that can be used to rapidly perform date- and time-based calculationsDateAdd()Adds or subtracts values to a date/time objectDateCompare()Compares two dates to determine whether they are the same or whether one is greater than the otherDateConvert()Converts local machine time to UTC (Universal Coordinated Time) time or vice versaDateDiff()Returns the difference between two datesDatePart()Returns the specified part of a passed dateDay()Returns a date/time object's day of month as a numeric valueDayOfWeek()Returns a date/time object's day of week as a numeric valueDayOfWeekAsString()Returns the English weekday name for a passed day-of-week numberDayOfYear()Returns a date/time object's day of year as a numeric valueDaysInMonth()Returns the number of days in a specified monthDaysInYear()Returns the number of days in a specified yearFirstDayOfMonth()Returns the day of year on which a specified month startsGetHTTPTimeString()Formats a ColdFusion date/time object according to the HTTP standard outlined in RFC 1123GetTimeZoneInfo()Returns a structure containing relevant server time zone informationHour()Returns a date/time object's hour as a numeric valueIsDate()Checks whether a string contains a valid dateIsLeapYear()Checks whether a specified year is a leap yearIsNumericDate()Checks whether a value passed as a date in the ColdFusion internal date format is in fact a legitimate dateMinute()Returns a date/time object's minute as a numeric valueMonth()Returns a date/time object's month as a numeric valueMonthAsString()Returns the English month name for a passed month numberNow()Returns a date/time object containing the current date and timeParseDateTime()Converts a date in string form into a ColdFusion date/time objectQuarter()Returns a date/time object's quarter as a numeric valueSecond()Returns a date/time object's second as a numeric valueWeek()Returns a date/time object's week in year as a numeric valueYear()Returns a date/time object's year as a numeric value Data Formatting Functions To assist you in performing calculations, ColdFusion comes with a complete suite of mathematical functions, random number-generation functions, and arithmetic expressions. As with all ColdFusion functions, these mathematical functions can be nested.Some of the mathematical functions take one or more numeric values as parameters. You can pass real values, integer values, and ColdFusion fields to these functions.Table C.6 lists the supported arithmetic expressions.Table C.6. ColdFusion Arithmetic Expressions EXPRESSIONDESCRIPTION+Addition-Subtraction*Multiplication/DivisionMODModular (finds remainder)\Integer division (both values must be integers)^PowerTable C.7 contains the available functions for mathematical processing.Table C.7. Mathematical Functions FUNCTIONDESCRIPTIONAbs()Absolute value of the passed numberAcos()Arccosine of the passed numberAsin()Arcsine of the passed number, in radiansAtn()Arctangent of the passed numberCeiling()The closest integer greater than the passed numberCos()Cosine of the passed numberDecrementValue()Number decremented by 1Exp()E to the power of the passed numberFix()The closest integer smaller than the passed number, if the passed number is greater than or equal to 0. Otherwise, the closest integer greater than the passed numberIncrementValue()Number incremented by 1Int()The closest integer smaller than the passed numberLog()Natural logarithm of the passed numberLog10()Base 10 log of the passed numberMax()The greater of two passed numbersMin()The smaller of two passed numbersPi()Value of pi as 3.14159265359Rand()A random number between 0 and 1Randomize()The random number generator seeded with the passed numberRandRange()A random integer value between two passed numbersRound()The integer closest (either greater or smaller) to the passed numberSgn()Signeither 1, 0, or 1, depending on whether the passed number is negative, 0, or positiveSin()Sine of the passed numberSqr()Square root of the passed numberTan()Tangent of the passed number International Functions Note that because ColdFusion is now a Java-based application, you must use Java standard locales, as opposed to the locales supported by ColdFusion 5.You will find information on standard locales here: http://www.inter-locale.com/index.jsp You must use the SetLocale() function to set the locale. You can retrieve the name of the locale currently in use with the GetLocale() function.To use ColdFusion's international support, you must use the LS functions listed later in this section. These functions behave much like the standard date, time, and formatting functions, but they honor the current locale setting.NOTE ColdFusion lists are an efficient way to manage groups of information. Lists are made up of elements, which are values separated by delimiting characters. The default delimiter is a comma, but you can change this to any character or string, as required. Lists are actually simple two-dimensional arrays. For more complex or multidimensional lists, use arrays instead.This list format is well suited for ColdFusion applications. It is both the format tha275 forms use to submit fields with multiple values and the format used by SQL to specify lists in SQL statements.When using the list-manipulation functions, remember the following:List-manipulation functions that add to, delete from, or change a list do not alter the original list passed to them. Rather, they return an altered list to you for manipulation. If you need to update the passed list itself, you must use <cfset> to replace the list with the newly modified list.All list functions accept as an optional last parameter a string with delimiters to be used in the processing of the list. If this parameter is omitted, the default comma delimiter is used.The number 1 is always the starting position in any list. When referencing list functions, remember that lists always start at position 1, never 0.When evaluating a list, be aware that ColdFusion will ignore any empty items in a list. If you have a list defined as "Laura, John, Sean, , ,Bryan", it will be evaluated as a four-element list, not a six-element list.NOTE Lists can be used in conjunction with the <cfloop> tag for processing.Table C.10 contains the available functions for list manipulationrelated processing.Table C.10. List-Manipulation Functions FUNCTIONDESCRIPTIONListAppend()Adds an element to the end of a listListChangeDelims()Changes a list's delimitersListContains()Performs a case-sensitive list search for an element containing specified textListContainsNoCase()Performs a case-insensitive list search for an element containing specified textListDeleteAt()Deletes an element from a listListFind()Performs a case-sensitive list search for a specific elementListFindNoCase()Performs a case-insensitive list search for a specific elementListFirst()Returns the first element in a listListGetAt()Gets a specific list element by indexListInsertAt()Inserts an element into a listListLast()Returns the last element in a listListLen()Returns the number of elements in a listListPrepend()Inserts an element at the beginning of a listListSort()Sorts a listListQualify()Returns the contents of a specified list with qualifying characters around each list elementListRest()Returns a list containing all the elements after the first elementListSetAt()Sets a specific list element by indexListValueCount()Performs a case-sensitive search and returns the number of matching elements in a listListValueCountNoCase()Performs a case-insensitive search and returns the number of matching elements in a list Array-Manipulation Functions Array elements can be added in any order. If you add an element 10 to an array that has only 5 elements, ColdFusion automatically creates elements 69 for you.Table C.11 contains the available functions for array manipulationrelated processing.Table C.11. Array-Manipulation Functions FUNCTIONDESCRIPTIONArrayAppend()Appends an element to an arrayArrayAvg()Returns the average numeric value in an arrayArrayClear()Deletes all data from an arrayArrayDeleteAt()Deletes a specific array elementArrayInsertAt()Inserts an element into an arrayArrayIsEmpty()Checks whether an array has any dataArrayLen()Returns the length of an arrayArrayMax()Returns the greatest numeric value in an arrayArrayMin()Returns the lowest numeric value in an arrayArrayNew()Creates a new arrayArrayPrepend()Inserts an element at the beginning of an arrayArrayResize()Resizes an arrayArraySet()Sets a specific array elementArraySort()Sorts an arrayArraySum()Returns the sum of numeric values in an arrayArraySwap()Swaps the values in two array elementsArrayToList()Converts a one-dimensional array to a listIsArray()Checks whether a variable is a valid ColdFusion arrayListToArray()Converts a list to a one-dimensional array Structure-Manipulation Functions ColdFusion uses queries to return sets of data. Most queries are created with the <cfquery> tag, but other tags (<cfpop> and <cfldap>) also return data in queries. Additionally, ColdFusion enables you to programmatically create your own queries using the QueryNew function and set query values using QuerySetCell.NOTE ColdFusion supports advanced security contexts that let you create complete security systems to secure your applications. Security is managed and maintained using the ColdFusion Administrator. After security is established, you can make a call to the <Cfauthenticate> tag to return security information. Use these security functions to interact with that security information.Table C.14 contains the available functions for security-related processing.Table C.14. Security Functions FUNCTIONDESCRIPTIONAuthenticatedContext()Deprecated (no longer in use)AuthenticatedUser()Deprecated (no longer in use)GetAuthUser()Returns the ID of the user currently logged in to the ColdFusion security frameworkIsAuthenticated()Deprecated (no longer in use)IsAuthorized()Deprecated (no longer in use)IsProtected()Deprecated (no longer in use)IsUserInRole()Checks to see if current user (logged in to the ColdFusion security framework) is in the specified role. Returns TRue or False System Functions Client variables enable you to store client information so it is available between sessions. Client variables can be accessed just like any other ColdFusion variables; standard variable access tools, such as <cfset>, can therefore be used to set variables. In addition, these functions provide special variable-manipulation capabilities.Table C.16 contains the available functions for client variable manipulationrelated processing.Table C.16. Client VariableManipulation Functions FUNCTIONDESCRIPTIONDeleteClientVariable()Deletes specified client variablesGetClientVariablesList()Returns a comma-delimited list of the read/write client variables available for use Expression Evaluation Functions ColdFusion provides a complete set of bit-manipulation functions for use by advanced developers only. These functions enable you to manipulate the individual bits within a 32-bit integer.NOTE These functions are provided to enable you to easily convert data from one type to another. This list is not all inclusive; some data-conversion functions are listed elsewhere throughout this appendix.Table C.19 contains the available functions for conversion-related processing.Table C.19. Conversion Functions FUNCTIONDESCRIPTIONJavaCast()Casts a variable for use within a Java objectJSStringFormat()Formats a specified string so that it is safe to use with JavaScripttoString()Converts any value, including binary values, into a stringtoScript()Converts a ColdFusion variable to a Java Script or Action Script variable. XML Functions The functions listed in table C.21 relate to the use of ColdFusion's Event Gateway feature.Table C.21. Event Gateway Functions FUNCTIONDESCRIPTIONGetGatewayHelper()Retrieves a Java "Gateway Helper" object for use with a ColdFusion event gatewaySendGatewayMessage()Sends a message through the specified event gateway SOAP Functions The following functions are listed here to give you access to some lesser-known but important functions in ColdFusion.Table C.23 contains the available miscellaneous functions.Table C.23. Miscellaneous Functions FUNCTIONDESCRIPTIONCreateObject()Instantiates COM, CORBA, Java objects, and ColdFusion componentsCreateUUID()Returns a 35-character string representation of a unique 128-bit numberGetBaseTagData()Returns an object containing data from a specified ancestor tagGetBaseTagList()Returns a comma-delimited list of base tag namesGetBaseTemplatePath()Returns the full path of the base templateGetContextRoot()Provides a path to the J2EE server context root for the current requestGetException()Retrieves a Java exception from a Java objectGetFunctionList()Returns a structure containing all of the built-in functions available in ColdFusionGetHTTPRequestData()Retrieves the HTTP request headers and body and makes them available for useGetK2ServerCollections()Deprecated (no longer in use)GetK2ServerDocCount()Deprecated (no longer in use)GetK2ServerDocCountLimit()Deprecated (no longer in use)GetPageContext()ColdFusion wrapper for the Java PageContext objectGetTickCount()Returns a tick count used to perform timing tests, with millisecond accuracyIsBinary()Tests whether a specified value is binaryIsBoolean()Determines whether a value can be converted to a Boolean valueIsCustomFunction()Checks whether a specified function is a user-defined functionIsDebugMode()Checks whether a page is being sent back to the user in debug modeIsDefined()Determines whether a specified variable existsIsK2ServerDocCountExceeded()Deprecated (no longer in use)IsK2ServerOnline()Deprecated (no longer in use)IsNumeric()Checks whether a specified value is numericIsObject()Determines whether the value is a specified type of objectIsSimpleValue()Checks whether a value is a string, a number, a TRUE/FALSE value, or a date/time objectParameterExists()Deprecated (no longer in use). Use IsDefined() insteadPreserveSingleQuotes()Instructs ColdFusion to not escape single quotation marks contained in values derived from dynamic parametersReleaseCOMObject()Releases COM object from memoryQuotedValueList()Returns a list of values in a specified query column, with all values enclosed within quotesToScript()Produces Javascript variables from ColdFusion variablesURLDecode()Decodes a URL-encoded stringURLEncodedFormat()Encodes a string in a format that can safely be used within URLsValueList()Returns a list of values in a specified query columnWriteOutput()Appends text to the page output stream In the following list, note that you must insert all examples between <cfoutput> and </cfoutput>. In addition, all examples must be enclosed with pound signs (##). Abs() Description: Acos() returns the arccosine of a passed number. This function takes only one numeric value as a parameter. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Acos(number) Example: The following example returns 1.53578917702, the arccosine of .035: #Acos(.035)# See also Asin(), Cos(), Pi(), Sin(), Tan() AddSOAPRequestHeader Description: AddSOAPResponseHeader() is used to include a SOAP response header in the Web Service's response. This function is used inside your ColdFusion-built Web Service. It takes four parameters, the last of which is optional.name is a string containing the name of the SOAP header you're requesting.value string or xml object containing the value of the header.nameSpace is a string containing the namespace for the header.mustUnderstand is the only optional parameter. It is a logical value which sets the SOAP mustUnderstand value for this header. Defaults to False.Syntax: AddSoapResponseHeader(headerName, headerValue, headerNameSpace[, mustUnserstand]) Example: The code in this example presents a function in a ColdFusion component being invoked as a webservice. If it is invoked in a context other than that of a Web Service request, it will throw an error. <!--- Declare function inside Web Service component ---> <cffunction name="doSomething" access="remote" output="false" returntype="string" displayname="does something" hint="This function does something"> <!--- Define argument ---> <cfargument name="someArg" required="true" type="string"> <!--- make up return value ---> <cfset retVal="the return value"> <cfset isSOAPRequest = isSOAP()> <cfif isSOAPRequest> <!--- get username form request header, as XML ---> <cfset xmlUser = getSOAPRequestHeader("http://someNameSpace/", ~CA "username", "TRUE")> <!--- Add AUTHORIZED VALUE header ---> <cfset addSOAPResponseHeader("http://www.someDomain.com/someNS", ~CA "respHead", "AUTHORIZED VALUE", false)> </cfif> <cfreturn retValue> </cffunction> See also AddSOAPRequestHeader(),GetSOAPRequestHeader(), GetSOAPResponseHeader(), GetSOAPRequest(), GetSOAPResponse(), IsSOAPRequest() ArrayAppend() You can set the values of explicit array elements using the <cfset> tag. See also ArrayInsertAt(), ArrayPrepend() ArrayAvg() ArrayAvg() works only with arrays containing numeric data. Do not use this function with arrays that contain text data. See also ArrayMin(), ArrayMax(), ArraySum() ArrayClear() ArrayClear() does not delete the actual array. Rather, it removes all the contents from it. The array itself remains and can be reused. See also ArrayDeleteAt(), ArrayIsEmpty() ArrayDeleteAt() Description: ArrayInsertAt() inserts an element into an array at a specified position, pushing over one place all existing elements with an index greater than the index of the element inserted. ArrayInsertAt() takes three parameters: the array into which to insert the element, the position at which to insert the element, and the data to be stored in that element. ArrayInsertAt() returns trUE if the operation is successful.Syntax: ArrayInsertAt(Array, Position, Value) Example: The following example inserts an element containing the word Alaska into the second position of an existing two-dimensional array; it then sets the abbreviation AK into the matching second dimension: <cfset result = #ArrayInsertAt(States[1], 2, "Alaska")#> <cfset States[2][2] = "AK"> See also ArrayAppend(), ArrayDeleteAt(), ArrayPrepend() ArrayIsEmpty() Description: ArrayLen() returns the length of a specified array. ArrayLen() takes a single parameter: the array to be checked.Syntax: ArrayLen(Array) Example: The following example reports the size of an array: The items array has #ArrayLen(items)# elements See also ArrayIsEmpty(), ArrayResize() ArrayMax() ArrayMax() works only with arrays containing numeric data. Do not use this function with arrays that contain text data. See also ArrayAvg(), ArrayMin(), ArraySum() ArrayMin() ArrayMin() works only with arrays containing numeric data. Do not use this function with arrays that contain text data. See also ArrayAvg(), ArrayMax(), ArraySum() ArrayNew() After an array is created, ColdFusion automatically expands it as necessary. Use the ArrayResize() function to resize an array manually. See also IsArray(), ListToArray() ArrayPrepend() You can set the values of explicit array elements using the <cfset> tag. See also ArrayAppend(), ArrayInsertAt() ArrayResize() Dynamically expanding arrays is a slow operation. You can dramatically optimize ColdFusion's array processing by resizing the array to the anticipated size immediately after creating it with ArrayNew(). See also ArrayLen(), ArraySet() ArraySet() Description: ArraySort() sorts the data in an array. ArraySort() takes three parameters: the array to be sorted, the sort type, and an optional sort order of either ascending or descending. If the sort order is omitted, the default order of ascending is used. ArraySort() supports three sort types, as listed in Table C.24.Table C.24. ArraySort() Sort Types TYPEDESCRIPTIONNumericSorts numericallyTextSorts text alphabetically, with uppercase before lowercaseTextNoCaseSorts text alphabetically; case is ignoredSyntax: ArraySort(Array, Type [, Order]) Example: The following example sorts an array alphabetically using a noncase-sensitive sort (also known as a dictionary sort): #ArraySort(Users, "textnocase")# NOTE Description: ArraySum() returns the sum of all values in an array. ArraySum() takes a single parameter: the array to be checked.Syntax: ArraySum(Array) Example: The following example reports the total cost of all items in an array: The total cost of all item in the list is #DollarFormat(ArraySum(items))# NOTE Description: ArraySwap() is used to swap the values in two array elements. ArraySwap() takes three parameters: the array itself and the positions of the two elements to be swapped. ArraySwap() returns trUE if the operation is successful.Syntax: ArraySwap(Array, Position1, Position2) Example: The following example swaps elements 10 and 11 in an array: #ArraySwap(Users, 10, 11)# See also ArraySet(), ArraySort() ArrayToList() Description: Asc() returns the ASCII value of the leftmost character of a string. The Asc() function will return 0 if the string being evaluated is empty.Syntax: Asc(character) Example: The following example returns 72, the ASCII value of the character H: Asc("Hello") TIP Description: Asin() returns the arcsine of a passed number in radians. This function takes only one numeric value as a parameter. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Asin(number) Example: The following example returns 0.0350071497753, the arcsine of .035: #Asin(.035)# See also Cos(), Pi(), Sin(), Tan() Atn() Deprecated. AuthenticatedUser() Description: Takes a string and converts it to a binary object and returns the binary object. When you have binary data that has been encoded into string format, use this function to convert it back into binary data. Use the binaryEncoding parameter to indicate the encoding algorithm that was used to encode the original binary data. It is intended primarily for use with data that has been encoded using BinaryEncode(). There are three encoding formats: Hex, UU (used in Unix platforms) and Base64.Encoding is commonly used to move binary data over text-based protocols like HTTP.Syntax: BinaryDecode(string, binaryEncoding) Example: This example takes a string variable that had been encoded with BinaryEncode() with Base64 encoding and decodes it back to a binary object so it can be written to disk. <cfset binGif = BinaryDecode( strGif, "Base64")> <cffile action="write" file="C:\cfusion\wwwroot\cfide\images\required2.gif" variable="binGif" addNewLine="No"> See also BinaryEncode(), CharsetEncode(), CharsetDecode(), IsBinary() BinaryEncode Description: BitAnd() returns the result of the logical addition two long integers with a bitwise AND operation. This function takes two 32-bit signed integer values as parameters.Syntax: BitAnd(number1, number2) Example: The following example returns 5 from 5 and 255: #BitAnd(5, 255)# See also BitNot(), BitOr(), BitXor() BitMaskClear() Description: BitMaskRead() returns the value of the length bits beginning with the starting number. This function takes three numeric values as parameters. The first parameter, number, is a 32-bit signed integer. The second and third parameters, start and length, must be integers between 0 and 31, inclusive.Syntax: BitMaskRead(number, start, length) Example: The following example returns 2 from 22, 3, and 31: #BitMaskRead(22, 3, 31)# See also BitMaskClear(), BitMaskSet() BitMaskSet() Description: BitNot() returns the bitwise NOT of an integer. This function takes only one numeric value as a parameter which must be a signed 32-bit integer.Syntax: BitNot(number) Example: The following example returns -23 from 22: #BitNot(22)# See also BitAnd(), BitOr(), BitXor() BitOr() Description: BitSHLN() returns number bitwise shifted left without rotation by count bits. This function takes two numeric values as parameters. The number parameter must be a signed 32-bit integer. The count parameter must be an integer between 0 and 31.Syntax: BitSHLN(number, count) Example: The following example returns 4480 from 35 and 7: #BitSHLN(35, 7)# See also BitSHRN() BitSHRN() Description: BitXor()returns the closest integer greater than the passed number. You pass two signed 32-bit integers as parameters.Syntax: BitXor(number1, number2) Example: The following example returns 1002 from 1000 and 2: #BitXor(1000, 2)# See also BitAnd(), BitNot(), BitOr() Ceiling() Description: CharsetDecode() converts string data to binary encoded data using a character set encoding that you specify. The CharsetDecode() function takes two parameters: the string value to be converted and the character encoding specification name and returns a binary object, encoded with that character set. You can use any character set that is recognized by your Java Runtime. Frequently used character sets include: • utf-8• shift_jis• utf-16• iso-2022-jp• iso-8859-1• euc-jp• windows-1252• euc-kr• us-ascii• euc-cn • big5Syntax: CharsetDecode(string, charset) Example: The following example produces a form into which you can enter a string of text from a different character set, in this case, the Ukrainian character set, Cp1123. Submit the form and it displays the string, converted to binary using Cp1123 and then converted back to string: <cfif isDefined("form.data")> <cfset binData = CharsetDecode(FORM.data, 'Cp1123')> <cfset strData = CharsetEncode(binData, 'Cp1123')> <p><strong>binary object dump:</strong> <cfdump var="#binData#"></p> <p><strong>Encoded back to string:</strong> <cfoutput>#strData#</cfoutput></p> <cfelse> <form method="post"> <p>Enter text from the Cp1123 (Ukranian) character set.</p> <input type="Text" name="data"> <input type="Submit"> <p>It will be converted to binary using Cp1123 when you submit the form.</p> </form> See also BinaryEncode(), BinaryDecode(), CharsetEncode(),IsBinary() CharsetEncode() Description: Chr() converts an ASCII value into a printable character. The Chr() function takes a single parameterthe ASCII value to be converted (valid ASCII values range from 0 to 255)and returns the specified ASCII value as a printable character.Syntax: Chr(number) Example: The following example returns the letter H, whose ASCII value is 72: #Chr(72)# See also Asc(), Val() Cjustify() Description: The Compare() function compares two string values. Compare() performs a case-sensitive comparison. This function returns a negative number if the first string is less than the second string, a positive number if the first string is greater than the second string, and 0 if the strings are the same.Syntax: Compare(String1, String2) Example: The following example returns a negative value because the first string is less than the second string: #Compare("Ben", "Bill")# NOTE You can create an alphabetical list of strings easily by sorting all the strings in increasing order with the Compare() function. See also CompareNoCase(), Find() CompareNoCase() The two comparison functions treat white space as characters to be compared. Therefore, if you compare two strings that are identical except for extra spaces at the end of one of them, the compare will not return 0. See also Compare(), Find() Cos() Description: The CreateDate() function returns a ColdFusion date/time object that can be used with other date-manipulation or formatting functions. CreateDate() takes three parameters: the date's year, month, and day.Syntax: CreateDate(Year, Month, Day) Example: The following example creates a date/time object based on three user-supplied fields: #CreateDate(birth_year, birth_month, birth_day)# TIP Because the CreateDate function takes no time values as parameters, the time portion of the created date/time object is set to all 0s. See also CreateDateTime(), CreateODBCDate(), CreateTime() CreateDateTime() When specifying the year using the CreateDateTime() function, be aware that ColdFusion will interpret the numeric values 029 as 21st-century years. The numeric values 3099 are interpreted as 20th-century years. See also CreateDate(), CreateODBCDateTime(), CreateTime(), ParseDateTime() CreateODBCDate() CreateODBCDate always creates an ODBC date/time field that has the time values set to 0s, even if the passed date/time object had valid time values.TIP CreateODBCDate() takes a date/time object as a parameter. If you want to pass individual date values as parameters, use the CreateDate() as the function parameter and pass it the values. See also CreateDate(), CreateODBCDateTime(), CreateODBCTime() CreateODBCDateTime() When specifying the year using the CreateODBCDateTime() function, be aware that ColdFusion will interpret the numeric values 029 as 21st-century years. The numeric values 3099 are interpreted as 20th-century years.TIP Description: The CreateODBCTime() function returns an ODBC date/time field that can safely be used in SQL statements. CreateODBCTime() takes a single parameter: a ColdFusion date/time object.Syntax: CreateODBCTime(Date) Example: The following example creates an ODBC date/time field for the current day (retrieved with the Now function): #CreateODBCTime(Now())# NOTE CreateODBCTime() takes a date/time object as a parameter. If you want to pass individual time values as parameters, use the CreateTime() as the function parameter and pass it the values.TIP Description: The CreateObject() function creates either a COM, CORBA, or Java object or a ColdFusion component. Note that the syntax varies with the type of object you're creating.ColdFusion components are special ColdFusion templates (named with the .cfc file extension) that contain CFML code to define functions (methods) and properties. They can be invoked and use in ColdFusion applications like other objects. They can also be invoked by other applications as Web Services.These tables contain details on this function's parameters, which vary with the type of object being created: Table C.25, Table C.26, Table C.27, and Table C.28.Table C.25. CreateObject() Parameters for COM PARAMETERDESCRIPTIONTypeRequired; "COM".ClassRequired; ProgID of the object to be invoked.ContextOptional; either InProc, Local, or Remote. Default value defined in registry.ServernameOptional, but required when Context = "Remote". Provides server name in either DNS or UNC format. The following forms are accepted: \\lanserver, lanserver, http://www.myserver.com, www.myserver.com, 127.0.0.1.Table C.26. CreateObject() Parameters for CORBA PARAMETERDESCRIPTIONTypeRequired; "CORBA".ClassRequired; if value of Context is "IOR", then this names the file that contains the sharing version of the Interoperable Object Reference (IOR). If value is "NameService", then this is the naming context of the naming service, delimited with forward slashes (e.g., "Macromedia/Department/object").ContextRequired; either "IOR" (to access CORBA server) or "NameService" to use a naming service to access the server. Only valid for VisiBroker.LocaleOptional; use is specific to VisiBroker orbs. Provides initialization arguments for init_orb(). Available in C++, Version 3.2. Its value must be of the form: "-ORBagentAddr 199.99.129.33 -ORBagentPort 19000". You must use a leading hyphen for each type/value pair.Table C.27. CreateObject() Parameters for Java Objects PARAMETERDESCRIPTIONTypeRequired; "Java"ClassRequired; names a valid Java classTable C.28. CreateObject() Parameters for ColdFusion Components PARAMETERDESCRIPTIONTypeRequired; "Component"ComponentNameRequired; names the .cfc file containing the CF componentSyntax for COM: CreateObject("COM", class, context, servername) Syntax for CORBA: CreateObject("CORBA", class, context, locale) Syntax for Java objects: CreateObject("JAVA", class) Syntax for ColdFusion components: #CreateObject("component", componentname)# NOTE COM objects are not supported on Unix platforms.NOTE Description: The CreateTime() function returns a ColdFusion date/time object that can be used with other time-manipulation or formatting functions. CreateTime() takes three parameters: the hour, minute, and second.Syntax: CreateTime(Hour, Minute, Second) Example: The following example creates a date/time object based on three ColdFusion fields: #CreateTime(act_hr, act_mn, act_se)# NOTE Description: CreateTimeSpan() creates a date/time object that can be used to rapidly perform date- and time-based calculations. CreateTimeSpan() takes four parameters: days, hours, minutes, and seconds. Any of these values can be set to 0 if not needed.Syntax: CreateTimeSpan(Days, Hours, Minutes, Seconds) Example: The following example creates a date/time object with a time exactly six hours from now: <cfset detonation# = Now() + CreateTimeSpan(0, 6, 0, 0)> TIP The CreateTimeSpan() function can be used in conjunction with the CACHEDWITHIN attribute of the <cfquery> tag. You can specify a period of time, using CreateTimeSpan(), in which the results of a query will be cached. This use of the CreateTimeSpan() function is effective only if you have enabled query caching in the ColdFusion Administrator. See also DateAdd() DateAdd() To subtract values from a date/time object, use the DateAdd function and pass a negative number of units. For example, -5 subtracts five units of whatever specifier was passed.TIP Description: DateCompare() enables you to compare two date values to see whether they are the same or whether one is greater than the other. DateCompare() takes two parameters: the dates to compare, which can be specified as date/time objects or string representations of dates. DateCompare() returns -1 if the first date is less than the second date, 0 if they are the same, and 1 if the first date is greater than the second date.Syntax: DateCompare(Date1, Date2) Example: The following example verifies that a user-supplied order ship date is valid (not already passed): <cfif DateCompare(ship_date, Now()) IS -1> We can't ship orders yesterday! </cfif> See also DateDiff(), DatePart() DateConvert() Description: DateDiff() returns the number of units of a passed specifier by which one date is greater than a second date. Unlike DateCompare(), which returns the greater date, DateDiff() tells you how many days, weeks, or months it is greater by. DateDiff() takes three parameters: The first is the date specifier (refer to Table C.3), and the second and third are the dates to compare.Syntax: DateDiff(Specifier, Date1, Date2) Example: The following example returns how many weeks are left in this year, by specifying today's date (using the Now() function) and the first date of next year (using the CreateDate function) as the two dates to compare: There are #DateDiff("WW", Now(), CreateDate(Year(Now())+1, 1, 1))# weeks left in this year! NOTE You can add or subtract the modified date/time object that DateDiff() returns from other date/time objects and use this value in the CACHEDWITHIN attribute of the <cfquery> tag. See also DateCompare(), DatePart() DateFormat() Unlike the TimeFormat() function mask specifiers, the DateFormat() function mask specifiers are not case-sensitive.NOTE Description: DatePart() returns the specified part of a passed date. DatePart() takes two parameters: The first is the date specifier (refer to Table C.3), and the second is the date/time object to process.Syntax: DatePart(Specifier, Date) Example: The following example returns the day of the week on which a user was born (and converts it to a string date using the DayOfWeekAsString function): You were born on a #DayOfWeekAsString(DatePart('W', dob))# See also DateCompare(), DateDiff(), Day(), DayOfWeek(), DayOfYear(), Hour(), Minute(), Month(), Quarter(), Second(), Week(), Year() Day() When specifying the year using the Day() function, be aware that ColdFusion will interpret the numeric values 029 as 21st-century years. The numeric values 3099 are interpreted as 20th-century years. See also DayOfWeek(), DayOfYear(), Hour(), Minute(), Month(), Quarter(), Second(), Week(), Year() DayOfWeek() When specifying the year using the DayOfWeek() function, be aware that ColdFusion will interpret the numeric values 029 as 21st-century years. The numeric values 3099 are interpreted as 20th-century years.TIP Description: DayOfWeekAsString() returns the English weekday name for a passed day-of-week number. DayOfWeekAsString() takes a single parameter: the day of week to be processed, with a value of 17.Syntax: DayOfWeekAsString(DayNumber) Example: The following example returns today's day of week: Today is day #DayOfWeekAsString(DayOfWeek(Now()))# of this week TIP Description: DayOfYear() returns a date/time object's day of year as a numeric value, taking into account leap years. DayOfYear() takes a single parameter: the date/time object to be processed.Syntax: DayOfYear(Date) Example: The following example returns today's day of year: Today is day #DayOfYear(Now())# of year #Year(Now())# TIP Always enclose date/time values in quotes when passing them to the DayOfYear() function as strings. Without quotes, the value passed is interpreted as a numeral representation of a date/time object. See also Day(), DayOfWeek(), Hour(), Minute(), Month(), Quarter(), Second(), Week(), Year() DaysInMonth() DaysInMonth() takes a date/time object as a parameter, and there is no equivalent function that takes a year and month as its parameters. Fortunately, this easily can be accomplished by combining the DaysInMonth() and CreateDate() functions. For example, to determine how many days are in February 2002, you can create a statement that looks like this: #DaysInMonth(CreateDate(2002, 2, 1))#.TIP Always enclose date/time values in quotes when passing them to the DaysInMonth() function as strings. Without quotes, the value passed is interpreted as a numeral representation of a date/time object. See also DaysInYear(), FirstDayOfMonth() DaysInYear() DaysInYear() takes a date/time object as a parameter, and there is no equivalent function that takes just a year as its parameter. Fortunately, this easily can be accomplished by combining the DaysInYear() and CreateDate functions. For example, you can create a statement that looks like this to determine how many days are in the year 2002: #DaysInYear (CreateDate(2002, 1, 1))#.TIP Always enclose date/time values in quotes when passing them to the DaysInYear() function as strings. Without quotes, the value passed is interpreted as a numeral representation of a date/time object. See also DaysInMonth(), FirstDayOfMonth() DE() Description: DecimalFormat() is a simplified number formatting function that outputs numbers with two decimal places, commas to separate the thousands, and a minus sign for negative values. DecimalFormat() takes a single parameter: the number to be displayed. The DecimalFormat() function will round numbers to the nearest hundredth.Syntax: DecimalFormat(Number) Example: The following example displays a table column in the decimal format: Quantity: #DecimalFormat(quantity)# TIP Description: The Decrypt() function enables you to decode strings based on a user-specified key using a symmetric keybased algorithm. This means that the same key that was used to encrypt the string (using Encrypt() and possibly, GenerateSecretKey()) must be used to decrypt the string.The Decrypt() function takes four parameters. The first parameter is the string on which to perform encryption or decryption. The second parameter is the key with which to encrypt or decrypt the string. The second two, algorithm and encoding are optional. But note that if you use an encoding type, you must also include an algorithm.The default value for algorithm is ColdFusion's own format, CFMX_COMPAT. It is the least secure. There are four other options; all are presented in Table C.30.Table C.30. Encryption/Decryption Algorithms VALUEDESCRIPTIONAESAdvanced Encryption StandardBLOWFISHCreated by Bruce SchneierCFMX_COMPATUsed by default and all earlier versions of ColdFusion starting with MXDESData Encryption StandardDESEDE"Triple DES"ColdFusion includes the Sun Java Cryptography Extension (JCE) default provider. This provides the algorithms listed in Table C.30 .You can install and use others.Syntax: Decrypt(encrypted_string, key[, algorithm[, encoding]]) Example: The following example encrypts a person's name, using the DES algorithm with the keygenerated by the function GenerateSecretKey(), and subsequently decrypts that same string: <cfset key=GenerateSecretKey("DES")> <cfset x=Encrypt("John", key, "DES", "Hex")> <cfset y=Decrypt(x, key, "DES", "Hex")> <p>Encrypted: <cfdump var="#x#"></p> <p>Decrypted: <cfdump var="#y#"></p> TIP Description: DeleteClientVariable() deletes the client variables whose names are passed as parameters. Unlike other ColdFusion variables, client variables persist over time and must be deleted with this function. DeleteClientVariable() takes a single parameter: the name of the variable to be deleted. DeleteClientVariable() returns TRUE if the variable was deleted. This function deletes a variable even if it did not previously exist. To ensure that a variable actually exists before using the DeleteClientVariable() function, test for its existence with IsDefined().Syntax: DeleteClientVariable(Variable) Example: The following example deletes a variable named login_name and sets a local variable with the function's return value: <cfset DeleteSuccessful = #DeleteClientVariable("login_name")#> See also GetClientVariablesList() DirectoryExists() Description: DollarFormat() is a simplified U.S. currency formatting function that outputs numbers with a dollar sign at the front, two decimal places, commas to separate the thousands, and a minus sign for negative values. DollarFormat() takes a single parameter: the number to be displayed.Syntax: DollarFormat(Number) Example: The following example displays the results of an equation (quantity multiplied by item cost) in the dollar format: Total cost: #DollarFormat(quantity*item_cost)# TIP DollarFormat() supports U.S. dollars only. Use the LSCurrencyFormat() function for international currency support. See also LSCurrencyFormat(), NumberFormat() Duplicate() CAUTION Description: The Encrypt() function enables you to encode strings based on a user-specified key using a symmetric-keybased algorithm. This means that the same key that was used to encrypt the string must be used to decrypt the string.The Encrypt() function takes four parameters. The first parameter is the string on which to perform encryption or decryption. The second parameter is the key (or text seed, in the case of the CFMX_COMPAT algorithm) with which to encrypt or decrypt the string. The second two, algorithm and encoding are optional. But note that if you use an encoding type, you must also include an algorithm.Note that you should use GenerateSecretKey() (when using any algorithm other than CFMX_COMPAT) to create the key. The CFMX_COMPAT algorithm uses user-defined text seed, rather than an encrypted key.The default value for algorithm is ColdFusion's own format, CFMX_COMPAT. It is the least secure. There are four other options; all are presented in Table C.30.Syntax: Encrypt(string, key[, algorithm[, encoding]] Example: See the Example for DeCrypt(). TIP Description: Exp() returns E to the power of a passed number. The constant e equals the base of the natural logarithm, that is 2.71828182845904. This function takes only one numeric value as a parameter. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Exp(number) Example: The following example returns 148.413159103, the natural logarithm of 5: #Exp(5)# See also Log(), Log10() ExpandPath() Description: Evaluate() is used to evaluate string expressions. Evaluate() takes one or more string expressions as parameters and evaluates them from left to right.Syntax: Evaluate(String1, ..) Example: The following example evaluates the variable A1 through A10: <cfloop index="i" from="1" to="10"> <cfoutput>A#I#: #Evaluate("a#i#")#</cfoutput> </cfloop> See also DE(), Iif() FileExists() Use the ExpandPath() function so you don't have to hard-code the filename passed to the FileExists() function; use ExpandPath() to convert the relative path to an actual filename. See also DirectoryExists() Find() Description: FindNoCase() performs a noncase-sensitive search. The first parameter is the string, and the second parameter is the target string, or string to be searched. The third, optional parameter can specify the position in the target string from which to start the search. This function returns the starting position of the first occurrence of the search string within the specified target string. If the search string is not found, 0 is returned.Syntax: FindNoCase(SearchString, TargetString [, StartPosition]) Example: The following example performs a noncase-sensitive search with the FindNoCase() function: #FindNoCase("AMERICA", "United States of America")# See also Find(), FindOneOf(), REFind(), REFindNoCase() FindOneOf() The FindOneOf() function is case-sensitive, and there is no noncase-sensitive equivalent function. To perform a noncase-sensitive FindOneOf() search, you first must convert both the search and target strings to either upper- or lowercase (using the UCase() or LCase() function). See also Find(), FindNoCase() FirstDayOfMonth() FirstDayOfMonth() takes a date/time object as a parameter, and no equivalent function exists that takes just a month and year as its parameters. Fortunately, this can easily be accomplished by combining the FirstDayOfMonth() and CreateDate() functions. For example, to determine the day of the year on which March 1999 started, you can create a statement that looks like this: #FirstDayOfMonth(CreateDate(1999, 3, 1))#.TIP Always enclose date/time values in quotes when passing them to the FirstDayOfMonth() function as strings. Without quotes, the value passed is interpreted as a numeral representation of a date/time object. See also DaysInMonth(), DaysInYear() Fix() Description: FormatBaseN() converts a number to a string using the base specified. Valid radix values are 236.Syntax: FormatBaseN(Number, Radix) Example: The following example converts a user-supplied number into hexadecimal notation: #FormatBaseN(Number, 16)# To convert a number to its binary format, you can do the following: #FormatBaseN(Number, 2)# See also InputBaseN() GenerateSecretKey() Description: GetBaseTagData() is used within subtags. It returns an object containing data from a specified ancestor tag. GetBaseTagData() takes two parameters: the name of the tag whose data you want returned, and an optional instance number. If no instance is specified, the default value of 1 is used.Syntax: GetBaseTagData(Tag [, InstanceNumber]) Example: The following example retrieves the data in a caller <cfhttp> tag: #GetBaseTagData(CFHTTP)# NOTE Description: GetBaseTagList() is used within subtags. It returns a comma-delimited list of base tag names. The returned list is in calling order, with the parent tag listed first.Syntax: GetBaseTagList() Example: The following example displays the top-level calling tag: <cfoutput>The top level tag is #ListFirst(GetBaseTagList())#</cfoutput> See also GetBaseTagData() GetBaseTemplatePath() Description: GetClientVariablesList() returns a comma-delimited list of the read/write client variables available to the template. The standard read-only system client variables, listed in Table C.31, are not returned. GetClientVariablesList() takes no parameters.Table C.31. Read-Only Client Variables VARIABLEDESCRIPTIONCFIDUnique ID assigned to this client.CFTokenUnique security token used to verify the authenticity of a CFID value.URLTokenText to append to URLs; contains both CFID and CFToken. (Appended automatically to <cflocation> URLs.)Syntax: GetClientVariablesList() Example: The following example retrieves the entire list of read/write client variables: #ListLen(GetClientVariablesList())# read-write client variables are currently active TIP Description: On J2EE server configurations, GetContextRoot() returns the path from the web root to the J2EE context root of the ColdFusion J2EE application. It is the same as calling getpageContext().getRequest().getContextPath(). If the page is in the default (root) context, an empty string is returned. It takes no parameters.Syntax: GetContextRoot() Example: This code returns the path to the documentation directory, relative to the J2EE context root. <cfset thisURL = "#getContextRoot()#/CFIDE/cfdocs/"> See also GetPageContext() GetCurrentTemplatePath() Description: GeTDirectoryFromPath() exTRacts the drive and directory (with a trailing backslash) from a fully specified path. GetdirectoryFromPath() takes a single parameter: the path to be evaluated.Syntax: GetDirectoryFromPath(Path) Example: The following example returns the directory portion of a current template's full file path: #GetDirectoryFromPath(ExpandPath("*.*") )# See also GetFileFromPath() GetException() Description: GetFileFromPath() extracts the filename from a fully specified path. GetFileFromPath() takes a single parameter: the path to be evaluated.Syntax: GetFileFromPath(Path) Example: The following example returns the filename portion of a temporary file: #GetFileFromPath(GetTempFile(GetTempDirectory(), "CF"))# See also GetDirectoryFromPath() GetFunctionList() Description: The GetGatewayHelper() function retrieves a Java "Gateway Helper" object for use with a ColdFusion event gateway. The object provides methods and properties that are specific to the gateway. Before you can use this, the event gateway must implement the Gateway Helper class.GetGatewayHelper() takes one parameter, gatewayID, which must be set to the value of one of the gateway IDs configured in the ColdFusion Administrator.Syntax: GetGatewayHelper(gatewayID) Example: The following creates an object named myGateway and will be used to interact with the gateway identified as "Book Club 5551212" in the ColdFusion Administrator: <cfset myGateway = #GetGatewayHelper("Book Club 5551212")#> See also SendGatewayMessage() GetHttpRequestData() Description: The GetHttpTimeString function formats a ColdFusion date/time object according to the HTTP standard outlined in RFC 1123. This function takes a single parameter: the date/time object to be formatted.Syntax: GetHttpTimeString(date_time) Example: The following example converts the current system time to a date/time format compatible with RFC 1123: #GetHttpTimeString(#CreateODBCDateTime(Now())#)# TIP Description: GetLocale() returns the name of the locale currently in use. The locale returned by the GetLocale() function is determined by the native operating system running ColdFusion Application Server.Syntax: GetLocale() Example: The following example saves the current locale to a local variable: <cfset current_locale = #GetLocale()#> See also SetLocale(), GetLocaleDisplayName() GetLocaleDisplayName() Description: The GetMetaData() function returns key/value pairs or structured XML data depending on the type of object it is used with. GetMetaData() is used with objects that support introspection, such as ColdFusion components and user-defined functions. It can also be used with query objects.The scope this is used in component bodies and function bodies at run-time to read and write variables present during the instantiation of the object.The metadata derived from ColdFusion components is presented as a structure of structures and arrays. The initial structure returned contains the keys presented in Table C.32. Note that other keys may be present for other types of objects.Table C.32. Metadata Derived from Components KEYDESCRIPTIONNameComponent namePathAbsolute path to the componentExtendsAncestor component metadata (Name, path and type)FunctionsArray of metadata (structures) for each component functionTypeType of object being reported on (e.g., "component")DisplayNameFrom the <cfcomponent> tag's displayName attributeHintFrom the <cfcomponent> tag's hint attributeOutputFrom the <cfcomponent> tag's output attributePropertiesAn array of metadata (structures) defined by the <cfcomponent> tag's <cfproperty> child tagsUserMetaDataUser-defined attributes of the <cfcomponent> tagThe metadata derived from functions contains at least the keys presented in Table C.33. Note that if the function doesn't employ some of the optional attributes, e.g., roles, hint, they will not be present in the metadata.Table C.33. Metadata Derived from Functions KEYDESCRIPTIONNameFunction nameParametersArray of structures (argument metadata)AccessFrom the <cffunction> tag's access attributeDisplayNameFrom the <cffunction> tag's displayName attributeHintFrom the <cffunction> tag's hint attributeOutputFrom the <cffunction> tag's output attributeReturnTypeFrom the <cffunction> tag's returnType attributeRolesFrom the <cffunction> tag's roles attributeUserMetaDataUser-defined attributes of the <cffunction> tagThe metadata derived from query objects produces an array of structures. There is one array element (containing one structures) for each field in the query object. The structures contain the elements described in Table C.34.Table C.34. Metadata Derived from Query objects KEYDESCRIPTIONNameFieldTypeNameData type nameIsCaseSensitiveTrue or FalseSyntax with objects: GetMetaData(Object) Syntax from within ColdFusion components: GetMetaData(this) Example: The following example returns the startup values from a passed variable: <!--- define function from which we'll get metadata ---> <cffunction name="myFunction" displayname="My Function" returntype="string" hint="This is a hint"> <cfargument name="ArgOne" type="string" required="Yes"> <cfreturn reverse(ArgOne)> </cffunction> <!--- get metadata ---> <cfset md = getMetaData(myFunction)> <!--- display metadata ---> <cfdump var="#md#"> See also CreateObject() GetMetricData() Description: The GetPageContext() function returns the current ColdFusion representation of the Java PageContext object. This object provides access to Java methods and properties that can be useful when integrating J2EE with ColdFusion. Some of these methods (e.g., include() and forward()) can be used like the corresponding JSP tags. This function takes no prameters.Syntax: GetPageContext() Example: The following example returns the startup values from a passed variable: <!--- Use pageContext() to determine the language of the current locale. Note that getRequest(), getLocale() and getDisplayLanguage() are Java functions. ---> <cfset thisContext = GetPageContext()> Current locale's language: <cfoutput> #thisContext.getRequest().getLocale().getDisplayLanguage()# </cfoutput>. See also GetContextRoot() GetProfileString() Description: The GetSOAPRequest() returns an XML object containing a SOAP header request. It can be called from within a Web Service function or from a client of the Web Service. It takes one parameteran object representation of the Web Servicewhich is required only if the function is being called from the Web Service client (as opposed to within the Web Service itself).webservice is an object pointing to a Web Service, created by CreateObject() or <cfobject>.Syntax: GetSOAPRequest([webservice]) Example: See example for AddSOAPRequestHeader() See also AddSOAPRequestHeader(), AddSOAPResponseHeader(), GetSOAPRequestHeader(), GetSOAResponse(), GetSOAPResponseHeader(), IsSOAPRequest() GetSOAPRequestHeader() Description: The GetSOAPResponseHeader() function retrieves the specified SOAP response, after invoking a Web Service. The SOAP response is retrieved as a ColdFusion XML object. It takes one parameter, an object representing the Web Service. Note that the Web Service must be invoked prior to calling GetSOAPResponse().webservice is a ColdFusion object representation of the Web Service.Syntax: GetSOAPResponse(webservice) Example: See the example in AddSOAPRequestHeader() for usage of GetSOAPResponse(). See also AddSOAPRequestHeader(), AddSOAPResponseHeader(), GetSOAPRequestHeader(), GetSOARequest(), GetSOAPResponseHeader(), IsSOAPRequest() GetSOAPResponseHeader() Description: The GetTempDirectory() function retrieves the full pathname of the temp directory on which ColdFusion Server is installed.Syntax: GetTempDirectory() Example: The following example returns the temp directory pathname: <cfoutput>#GetTempDirectory()#</cfoutput> See also GetTempFile() GetTempFile() To create a temporary file in the Windows temporary directory, pass the GetTempDirectory() function as the directory parameter. See also GetTempDirectory() GetTemplatePath() Deprecated. GetK2ServerDocCount() This function has been deprecated. GetTickCount() Description: The GetTimeZoneInfo() function returns a structure containing relevant time zone information from the machine on which the code is run. The GetTimeZoneInfo() function does not take any parameters, and the structure returned contains four elements with the keys outlined in Table C.35.Table C.35. GetTimeZoneInfoKeys Returned in Structure KEYDESCRIPTIONutcTotalOffsetReturns the difference in local time (time captured from the machine executing the code) from UTC (Universal Coordinated Time). A plus sign lets you know that the time zone you are comparing is west of UTC; a minus sign lets you know that the time zone you are comparing is east of UTC.utcHourOffsetReturns the difference in local time from UTC in hours.utcMinuteOffsetReturns the difference in local time from UTC in minutes, after the hours offset has been figured in. For some countries, such as those in North America, the minute offset is 0 because these countries' times are offset from UTC by exactly n hours. However, the times of some countries in the world are offset from UTC by n hours and n minutes.isDSTOnReturns TRUE if daylight saving time is on in the machine executing the code; otherwise, if daylight saving time is off, it returns FALSE.Syntax: GetTimeZoneInfo() Example: The following example uses GetTimeZoneInfo() to compare UTC offsets with the local time: <cfset myTime = GetTimeZoneInfo()> <cfoutput> The difference in local time from UTC in seconds is #myTime.utcTotalOffset#.<br> The difference in local time from UTC in hours is #myTime.utcHourOffset#.<br> The difference in local time from UTC in minutes is #mytime.utcMinuteOffset#.<br> </cfoutput> See also DateConvert(), CreateDateTime(), DatePart() GetToken() Use the ColdFusion list functions instead of GetToken() when working with strings that contain lists of data. See also Left(), Right(), Mid(), SpanExcluding(), SpanIncluding() Hash() The Hash() function is useful for converting sensitive data (such as user passwords) into a hexadecimal string for storage in the database. If you store the converted value in the database, you can then have users reenter their passwords, hash the value they enter, and compare the hexadecimal string returned with the hexadecimal value stored in the database. Hour() Description: displays text wit263 codes with a preformatte259 block (using the <pre> and </pre> tags). takes a single parameter: the text to be processed. When you evaluate a string with the function, all carriage returns are removed from the string and all special characters contained within the string are escaped.Syntax: HTMLCodeFormat(Text) Example: The following example uses preformatted text to display the code used to generate a dynamic Web page: #HTMLCodeFormat(page)# Description: converts supplied text into a safe format, with any HTML control characters converted to their appropriate entity codes. takes a single parameter: the text to be converted.Syntax: HTMLEditFormat(Text) Example: The following example displays th260 code used to render a dynamic Web page inside a bordered box: <table border> <tr> <td>#HTMLEditFormat(page)#</td> </tr> </table> TIP Description: IIf() evaluates a Boolean condition and evaluates one of two expressions depending on the results of that evaluation. If the Boolean condition returns TRUE, the first expression is evaluated; if the condition returns FALSE, the second expression is evaluated.Syntax: IIF(Boolean condition, Expression if TRUE, Expression if FALSE) Example: The following example determines whether #cnt# has a value of 1; it evaluates "A" if it does and "B" if it does not: #IIf("#cnt# IS 1", "A", "B")# See also DE(), Evaluate() IncrementValue() Description: InputBaseN() converts a string into a number using the base specified. Valid radix values are 236.Syntax: InputBaseN(String, Radix) Example: The following example converts the string containing the binary number 10100010 into its base 10 equivalent of 162: #InputBaseN("10100010", 2)# TIP Description: Insert() is used to insert text into a string and takes three parameters. The first parameter, SourceString, is the string you want to insert. The second parameter, TargetString, is the string into which you will insert SourceString. The third parameter, Position, is a numeric value that specifies the location in the TargetString at which to insert the SourceString. Insert() returns the modified string.Syntax: Insert(SourceString, TargetString, Position) Example: The following example inserts a field called area code in front of a phone number: #Insert(area_code, phone, 0)# TIP Description: Int() returns the closest integer whose value is less than the numeric parameter. This function takes only one numeric value as a parameter. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Int(number) Example: The following example returns 99, which is the closest integer less than the parameter value: #Int(99.9)# The next example returns -100 because -100 is the next integer less than the parameter value. #Int(-99.9)# See also Ceiling(), Fix(), Round() IsArray() Deprecated. IsAuthorized() Description: IsBinary() tests whether a specified value is a binary value. Returns TRUE if the specified value is binary and FALSE if it is not. The IsBinary() function takes a single parameter: the value to be evaluated.Syntax: IsBinary(value) Example: The following example checks whether a specified value is a binary value: #IsBinary(myValue)# See also ToBinary(), ToBase64(), IsNumeric() IsBoolean() Description: IsCustomFunction() is used to verify that a function being used is a user-defined function. IsCustomFunction() takes a single parameter: the function to be verified. It returns Yes if the function being evaluated is a user-defined function and No if it is not.Syntax: IsCustomFunction(function) Example: The following example checks the function UDF to determine whether it is in fact a user-defined function: #IsCustomFunction(UDF)# IsDebugMode() Description: IsDefined() determines whether a specified variable exists. IsDefined() returns trUE if the specified variable exists and FALSE if not. IsDefined() takes a single parameter: the variable for which to check. This parameter can be passed as a fully qualified variable, with a preceding variable type designator. The variable name must be enclosed in quotation marks; otherwise, ColdFusion checks for the existence of the variable's contents rather than of the variable itself.Syntax: IsDefined(Parameter) Example: The following example checks whether a variable of any type named USER_ID exists: <cfif IsDefined("USER_ID")> The next example checks to see whether a CGI variable named USER_ID exists and ignores variables of other types: <cfif IsDefined("CGI.USER_ID")> NOTE Description: IsDate() checks whether a string contains a valid date; it returns trUE if it does and FALSE if it doesn't. IsDate() takes a single parameter: the string to be evaluated.Syntax: IsDate(String) Example: The following example checks whether a user-supplied date string contains a valid date: <cfif IsDate(ship_date) IS "No"> You entered an invalid date! </cfif> NOTE When specifying the year using the IsDate() function, be aware that ColdFusion will interpret the numeric values 029 as 21st-century years. The numeric values 3099 are interpreted as 20th-century years. See also IsLeapYear(), LSIsDate(), ParseDateTime() IsK2ServerDocCountExceeded() This function has been deprecated and is no longer in use. IsLeapYear() IsLeapYear() takes a year, not a date/time object, as a parameter. To check whether a date stored in a date/time object is a leap year, use the Year() function to extract the year and pass that as the parameter to IsLeapYear(). See also IsDate() IsNumeric() Use the LSIsNumeric() function for international number support. See also InputBaseN(), LSIsNumeric(), Val() IsNumericDate() Description: The IsObject() function returns true if the specified variable is an object. If it is a basic ColdFusion variable type, the function returns False. Basic ColdFusion variable types include string, integer, float, date, structure, array, query, XML object, and user-defined function. The various object types you can test for are listed in Table C.37. This function can also optionally take component-specific argumentsarguments that differ depending on the type of object you're testing for.Table C.37. Object Types Used in IsObject OBJECT TYPESComponentJavaCorbaComTemplateWebserviceSyntax: IsObject(variable, type, component-specific-param) Example: The following example returns a value indicating whether or not it is running inside a component: <cfcomponent> <cffunction NAME="tester"> <cfreturn IsObject(this)> </cffunction> </cfcomponent> See also CreateObject() IsProtected() Description: IsSimpleValue() checks whether a value is a string, a number, a trUE/FALSE value, or a Date/Time value. IsSimpleValue() takes a single parameter: the value to be checked. IsSimpleValue() returns trUE if the value is a simple value and FALSE if not.Syntax: IsSimpleValue(Value) Example: The following example checks to see that a description field is a simple value: <cfif IsSimpleValue(Description)> See also Evaluate(), IsDefined() IsSOAPRequest() Description: The IsStruct() function returns TRUE if the variable being evaluated is a structure. The IsStruct() function takes a single parameter: the variable to be evaluated.Syntax: IsStruct(variable) Example: The following example checks to see whether the variable People is a structure: #IsStruct(People)# IsQuery() IsQuery() is particularly useful within custom tags that expect queries as parameters. IsQuery() can be used to check that a valid value was passed before any processing occurs. See also QueryAddRow() IsUserInRole() Note that the user must have been authenticated through use of the <cfloginuser> tag, which along with <cflogin> and <cflogout> is part of the ColdFusion security framework. <cfloginuser> enables you to indicate that the user is part of a role (which you define: Managers, Staff, Admin, and so on).Syntax: IsUserInRole(role) Example: The following example checks the current authenticated user to see if he or she is in the Managers role and provides different content based on return value. <cfif IsUserInRole("Managers")> <cfinclude template="FinancialReport.cfm"> <cfelse> <p>Access denied. </cfif> See also QueryAddRow() IsWDDX() IsWDDX() should be used to verify a WDDX packet before passing it to <cfwddx>. IsXML() Description: This function takes one parameter and indicates whether or not it is an attribute node in an XML DOM. It must be a node in which the XMLType value is Attribute. Note that the XMLSearch() function does return XML DOM attributes.Syntax: IsXMLAttribute(DOM attribute) Example: The IsXMLAttribute() function will return false here because, we're only passing it a variable, not an actual part of an XML DOM. <cfxml variable="myContact"> <contact id="4323251"> <name first="Joe" last="Shmo"> <phone id="1">333-232-2322</phone> <phone id="2">333-232-2321</phone> </name> </contact> </cfxml> <cfoutput>#IsXMLAttribute(myContact.contact.XmlAttributes.id)#</cfoutput> See also IsXMLNode() IsXMLDoc() Note that the ColdFusion XML document object was introduced starting with ColdFusion MX.Syntax: IsXMLDoc(document) Example: The following example checks whether a variable named myXMLDoc is a valid XML document object: <!--- Create an ColdFusion XML doc object ---> <cfxml variable="myXMLdoc"> <orders> <order orderid="1" orderdate="3/1/2001" shipaddress="1 Rue Street" shipcity="Brussels" shipzip="1234" shipstate="> <orderitem orderitemid="1" itemid="6" orderqty="2" itemprice="30.00"/> <orderitem orderitemid="2" itemid="1" orderqty="1" itemprice="17.50"/> <orderitem orderitemid="3" itemid="9" orderqty="1" itemprice="100.00"/> </order> <order orderid="2" orderdate="3/1/2001" shipaddress="21700 Northwestern Hwy" shipcity="Southfield" shipzip="48075" shipstate="Michigan"> <orderitem orderitemid="4" itemid="11" orderqty="10" itemprice="7.50"/> </order> </orders> </cfxml> <!--- Test to make sure it worked ---> <cfif IsXMLDoc(myXMLdoc)> <p><cfoutput>#IsXMLRoot("orderitem")#</cfoutput> <cfelse> <cfabort showerror="This is not a vaild XML document object"> </cfif> See also IsXML() IsXMLElem() Description: This function takes one parameter and indicates whether or not it is a node in an XML DOM. The function will return True if the parameter you pass it is the document object, an element in the object or an element in the XMLNodes array.Syntax: IsXMLnode(DOM node) Example: The IsXMLNode() function will return true here. <cfxml variable="myContact"> <contact id="4323251"> <name first="Joe" last="Shmo"> <phone id="1">333-232-2322</phone> <phone id="2">333-232-2321</phone> </name> </contact> </cfxml> <cfoutput>#IsXmlnode(myContact.contact.name.phone)#</cfoutput> See also IsXMLAttribute() IsXMLRoot() Description: The JavaCast() function is used to indicate that a ColdFusion variable should be converted to be passed as an argument to an overloaded method of a Java object. The JavaCast() function should be used only to pass scalar and string arguments. This function takes two parameters. The first is the data type the variable should be converted to prior to being passed. Possible valid data types are Boolean, int, long, float, double, string and null. The second parameter is the variable to be converted.Syntax: JavaCast(type, variable) Example: The following example converts the specified variable to the int data type: #JavaCast("int", myNum)# CFOBJECT() JSStringFormat() Description: LCase() converts a string to lowercase. LCase() takes a single parameterthe string to be convertedand returns the converted string.Syntax: LCase(String) Example: The following example converts a user-supplied string to lowercase: #LCase(string_field)# See also UCase() Left() Description: Len() returns the length of a specified string. Len() takes a single parameter: the string whose length you want to determine.Syntax: Len(String) Example: The following example returns the length of a user-supplied address field after it has been trimmed: #Len(Trim(address))# See also ToBinary(), Left(), Mid(), Right() ListAppend() Description: ListChangeDelims() returns a passed list reformatted to use a different delimiter. ListChangeDelims() takes two parameters: the first is the list to be reformatted, and the second is the new delimiter character.Syntax: ListChangeDelims(List, Delimiter) Example: The following example creates a new list containing the same elements as the original list but separated by plus signs: <cfset URLUsers = ListChangeDelims(Users, "+")> TIP Description: The ListContains() function performs a case-sensitive search through a list to find the first element that contains the specified search text. If the search text is found, the position of the element containing the text is returned. If no match is found, 0 is returned. It takes two parameters: the first parameter is the list to be searched, and the second parameter is the value for which to search.Syntax: ListContains(List, Value) Example: The following example returns the position of the first element that contains the text cash: Element #ListContains(Payments, "cash")# contains the word "cash" NOTE Description: The ListContainsNoCase() function performs a noncase-sensitive search through a list to find the first element that contains the specified search text. If the search text is found, the position of the element containing the text is returned. If no match is found, 0 is returned. It takes two parameters: the first parameter is the list to be searched, and the second parameter is the value for which to search.Syntax: ListContainsNoCase(List, Value) Example: The following example returns the position of the first element that contains the text cash (regardless of case): Element #ListContainsNoCase(Payments, "cash")# contains the word "cash" NOTE Description: ListDeleteAt() deletes a specified element from a list. ListDeleteAt() takes two parameters: the first is the list to be processed, and the second is the position of the element to be deleted. ListDeleteAt() returns a modified list with the specified element deleted. The specified element position must exist; an error message is generated if you specify an element beyond the range of the list.Syntax: ListDeleteAt(List, Position) Example: The following example deletes the second element in a list, but it first verifies that it exists: <cfif #ListLen(Users)# GTE 2> <cfset Users = ListDeleteAt(Users, 2)> </cfif> See also ListRest() ListFind() ListFind()finds only elements that exactly match the specified search text. To perform a search for substrings within elements, use the ListContains() function. See also ListContains(), ListContainsNoCase(), LindFindNoCase() ListFindNoCase() ListFindNoCase() finds only elements that exactly match the specified search text. To perform a search for substrings within elements, use the ListContainsNoCase()function. See also ListContains(), ListContainsNoCase(), ListFind() ListFirst() Description: ListGetAt() returns the list element at a specified position. ListGetAt() takes two parameters: The first is the list to process, and the second is the position of the desired element. The value passed as the position parameter must not be greater than the length of the list; otherwise, a ColdFusion error message is generated.Syntax: ListGetAt(List, Position) Example: The following example returns the name of the fourth selection from a field of book titles submitted by a user: The fourth title you selected is #ListGetAt(titles, 4)# See also ListFirst(), ListLast(), ListRest() ListInsertAt() Description: ListLast() returns the last element in a list. ListLast() takes a single parameter: the list to be processed.Syntax: ListLast(List) Example: The following example returns the last selection from a field of book titles submitted by a user: The last title you selected is #ListLast(titles)# See also ListFirst(), ListGetAt(), ListRest() ListLen() Description: ListPrepend() inserts an element at the beginning of a list, pushing any other elements to the right. ListPrepend() returns the new list with the prepended element. ListPrepend() takes two parameters: The first is the current list, and the second is the element to be prepended.Syntax: ListPrepend(List, Element) Example: The following example prepends John to an existing list of users and replaces the old list with the new one: <cfset Users = ListPrepend(Users, "John")> See also ListAppend(), ListInsertAt(), ListSetAt() ListSort() Description: ListToArray() converts a ColdFusion list to a one-dimensional array. ListToArray() takes two parameters: the list to be converted and an optional list delimiter. If no delimiter is specified, the default (comma) delimiter is used. ListToArray() creates a new array.Syntax: ListToArray(List [, Delimiter]) Example: The following example converts a list of users into an array: <cfset UserArray = #ListToArray(UserList)#> When evaluating a list, ColdFusion will ignore any empty items in a list. If you have a list defined as "Laura, John, Sean, , ,Bryan", it will be evaluated as a four-element list, not a six-element list. See also ArrayToList() ListQualify() Description: ListRest() returns a list containing all the elements after the first element. If the list contains only one element, an empty list (an empty string) is returned. ListRest() takes a single parameter: the list to be processed.Syntax: ListRest(List) Example: The following example replaces a list with the list minus the first element: <cfset Users = ListRest(Users)> See also ListDeleteAt() ListSetAt() Description: ListValueCount() searches a list for a specific value and returns the number of occurrences it finds of the specified value. The ListValueCount() function is case-sensitive. It takes three parameters. The first parameter is the list to search; the second parameter is the value for which to search the list. The third, optional parameter is the character used to delimit elements in the specified list. If the delimiter parameter is omitted, the default comma is used.Syntax: ListValueCount(list, value [, delimiters ]) Example: The following example searches through a list of users to see how many have the first name Laura: #ListValueCount(usersList, "Laura")# See also ListValueCountNoCase() ListValueCountNoCase() Description: LJustify() left-aligns a string within a field of a specified length. It does this by padding spaces after the specified text. LJustify() takes two parameters: the string to process and the desired string length.Syntax: #LJustify(String, Length)# Example: The following example left-justifies the string "First Name:" so that it is left-aligned within a 25-character-wide field: #LJustify("First Name:", 25)# See also CJustify(), LTrim(), RJustify(), RTrim(), Trim() Log() Description: Log10() returns the base 10 log of a passed number. This function takes only one numeric value as a parameter. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Log10(number) Example: The following example returns 0.698970004336, the natural logarithm of 5: #Log10(5)# See also Log(), Exp() LSCurrencyFormat() Unlike versions of ColdFusion prior to ColdFusion MX, the locales used for formatting are now defined by Java standard locale formatting rules on all platforms.TIP You can use the simpler DollarFormat() function for U.S. currency formatting. See also DollarFormat(), NumberFormat() LSDateFormat() Unlike versions of ColdFusion prior to ColdFusion MX, the locales used for formatting are now defined by Java standard locale formatting rules on all platforms.NOTE Description: LSEuroCurrencyFormat() returns a currency value formatted in the convention of the locale enabled on the executing machine, using the euro currency symbol. The LSEuroCurrencyFormat function takes two parameters. The first, currency-value, is the actual amount or value of the currency you want to format. The second parameter, type, is an optional parameter that enables you to specify a currency type of none, local, or international. If no currency type is specified, the default of local is used. Depending on which type you choose, ColdFusion will display the value with differing currency symbols. If none is chosen, the value is displayed as a simple numeric value. If local is chosen, the value is displayed in the convention of the locale that is set on the executing machine, displaying the symbol for the euro if an accommodating character set is installed. If international is chosen, then the value is displayed with EUR, the international symbol for the euro.Syntax: LSEuroCurrencyFormat(currency-value [,type]) NOTE Description: LSIsCurrency() checks whether a string contains a valid currency for the current locale; it returns trUE if it does and FALSE if it does not. LSIsCurrency() takes a single parameter: the string to be evaluated.Syntax: LSIsCurrency(String) NOTE Description: LSIsDate() checks whether a string contains a valid date for the current locale; it returns trUE if it does and FALSE if it does not. LSIsDate() takes a single parameter: the string to be evaluated.Syntax: LSIsDate(String) NOTE To check U.S. dates, you can use the IsDate() function. See also IsDate(), IsLeapYear(), LSParseDateTime(), ParseDateTime() LSIsNumeric() Unlike versions of ColdFusion prior to ColdFusion MX, the locales used for formatting are now defined by Java standard locale formatting rules on all platforms.Example: The following example checks to ensure that a user has entered a valid locale-specific age (numeric characters only): <cfif LSIsNumeric(age) IS "No"> You entered an invalid age! </cfif> NOTE Description: LSNumberFormat() enables you to display numeric values in a locale-specific, readable format. LSNumberFormat() is the locale-specific version of the NumberFormat function. LSNumberFormat() takes two parameters: the number to be displayed and an optional mask value. If the mask is not specified, the default mask of ,99999999999999 is used. The complete set of number masks is listed in Table C.35 in the description of the NumberFormat() function.If the mask you use can't format the specified number, this function returns the number unformatted.Syntax: LSNumberFormat(Number [, mask ]) NOTE To display numbers in any of the U.S. formats, you can use the NumberFormat() function.Example: The following example displays a submitted form field in the default format for the current locale: #LSNumberFormat(FORM.quantity)# See also DecimalFormat(), DollarFormat(), LSCurrencyFormat(), LSParseNumber(), NumberFormat() LSParseCurrency() Unlike versions of ColdFusion prior to ColdFusion MX, the locales used for formatting are now defined by Java standard locale formatting rules on all platforms.Example: The following example converts a user-supplied currency string into a number: <cfset sale_price = LSParseCurrency(FORM.sale_price)> See also LSCurrencyFormat(), LSParseNumber() LSParseDateTime() Unlike versions of ColdFusion prior to ColdFusion MX, the locales used for formatting are now defined by Java standard locale formatting rules on all platforms.Example: The following example converts a user-supplied string containing a date into a ColdFusion date/time object: <cfset ship_date = LSParseDateTime(FORM.ship_date)> NOTE CAUTION Description: The LSParseEuroCurrency() function converts a currency string that contains the euro symbol or sign to a number. This function attempts conversion of the string based on all three default currency formats (none, local, and international). This function takes a single parameter: the string to be converted.Syntax: LSParseEuroCurrency(currency-string) NOTE CAUTION Description: LSParseNumber() converts a locale-specific number in string form into a valid number. LSParseNumber() takes a single parameter: the string to be converted.Syntax: LSParseNumber(String) NOTE Description: LSTimeFormat() displays the time portion of a date/time object in a locale-specific, readable format. LSTimeFormat() is the locale-specific version of the TimeFormat() function. LSTimeFormat() takes two parameters: The first is the date/time object to be displayed, and the second is an optional mask value that enables you to control exactly how the data is formatted. If no mask is specified, a mask appropriate for the current locale is used. The complete set of date masks is listed in Table C.37, in the description of the TimeFormat() function.Syntax: LSTimeFormat(Date [, mask ]) NOTE You can use the simpler TimeFormat() function for U.S. times. See also LSDateFormat(), LSNumberFormat(), TimeFormat() LTrim() Description: Max() returns the greater of two passed numbers. This function takes two numeric values as parameters. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Max(number1, number2) Example: The following example returns 2, the greater value of 2 and 1: #Max(1, 2)# See also Min() Mid() Description: Min() returns the smaller of two passed numbers. This function takes two numeric values as parameters. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Min(number1, number2) Example: The following example returns 1, the smaller value of 2 and 1: #Min(1, 2)# See also Max() Minute() When specifying the year using the Minute() function, be aware that ColdFusion will interpret the numeric values 029 as 21st-century years. The numeric values 3099 are interpreted as 20th-century years.TIP Description: Month() returns a date/time object's month as a numeric value with possible values of 112. Month() takes a single parameter: the date/time object to be processed.Syntax: Month(Date) Example: The following example returns the current month: It is month #Month(Now())# of year #Year(Now())# See also Day(), DayOfWeek(), DayOfYear(), Hour(), Minute(), Quarter(), Second(), Week(), Year() MonthAsString() Description: Now() returns a date/time object containing the current date and time precisely to the second. Now() takes no parameters.Syntax: Now() Example: The following example returns the current date and time formatted for correct display: It is now #DateFormat(Now())# #TimeFormat(Now())# NOTE Description: NumberFormat() enables you to display numeric values in a readable format. NumberFormat() takes two parameters: the number to be displayed and an optional mask value. If the mask is not specified, the default mask of ",99999999999999" is used. The complete set of number masks is listed in Table C.38.Table C.38. NumberFormat() Mask Characters MASKDESCRIPTION_Optional digit placeholder9Optional digit placeholder (same as _ but shows decimal place more clearly).Specifies the location of the decimal point0Forces padding with 0s()Displays parentheses around the number if it is less than 0+Displays a plus sign in front of positive numbers and a minus sign in front of negative numbers-Displays a minus sign in front of negative numbers and leaves a space in front of positive numbers,Separates thousands with commasCCenters the number within mask widthLLeft-justifies the number within mask width$Places a dollar sign in front of the number^Specifies the location for separating left and right formattingSyntax: NumberFormat(Number [, mask ]) Example: To demonstrate how the number masks can be used, Table C.39 lists examples of various masks being used to format the numbers 1453.876 and 1453.876.Table C.39. Number Formatting Examples MASKRESULTNOTESNumberFormat(1453.876,1454No decimal point is specified in the "9999") mask, so the number is rounded to the nearest integer value.NumberFormat(-1453.876,1454No decimal point is specified in the "9999") mask, so the number is rounded to the nearest integer value.NumberFormat(1453.876,1453.88Even though a decimal point is "9999.99") provided, the number of decimal places specified is less than needed; the decimal portion must be rounded to the nearest integer value.NumberFormat(1453.876,1453.88The number is positive, so the "(9999.99)") parentheses are ignored.NumberFormat(-1453.876,(1453.88)The number is negative, so "(9999.99)") parentheses are displayed around the number.NumberFormat(1453.876,1453.88The number is positive, so the "-9999.99") minus sign is ignored.NumberFormat(-1453.876,-1453.88The number is negative, so "-9999.99")a minus sign is displayed.NumberFormat(1453.876,+1453.88The number is positive, so a "+9999.99")plus sign is displayed.NumberFormat(-1453.876,-1453.88The number is negative, so a "+9999.99")minus sign is displayed.NumberFormat(1453.876,$1453.88Using the dollar sign as the first "$9999.99") character of the mask places a dollar sign at the beginning of the output.NumberFormat(1453.876,1453.876Position six of the mask is a carat "C99999^9999") character, so the decimal point is positioned there even though fewer than six digits appear before the decimal point. This enables you to align columns of numbers at the decimal point.NOTE Description: ParagraphFormat() converts text with embedded carriage returns for correc275 display. HTML ignores carriage returns in text, so they must be converted t270 paragraph markers (the <p> tag) to be displayed correctly. ParagraphFormat() takes a single parameter: the text to be processed.Syntax: ParagraphFormat(Text) Example: The following example displays a converted text file inside a form <textarea> field: <textarea name="comments">#ParagraphFormat(comments)#</textarea> TIP Deprecated. ParseDateTime() When using the ParseDateTime() function with a POP conversion method, one of two POP conversion methods can be specified. The first of these methods, POP, converts the date/time string passed from a POP mail server to GMT for the U.S. locale. The second POP conversion method available, STANDARD, provides no conversion on the date/time string passed and simply returns the time string as it was retrieved from the POP mail server.Example: The following example converts a user-supplied string containing a date into a ColdFusion date/time object: <cfset ship_date = ParseDateTime(FORM.ship_date) > NOTE Description: Pi() returns the value of Pi as 3.14159265359. It takes no parameters.Syntax: Pi() Example: The following example displays the value of pi: Pi equals #Pi()#. See also Asin(), Cos(), Sin(), Tan() PreserveSingleQuotes() Description: Quarter() returns a date/time object's quarter as a numeric value with possible values of 14. Quarter() takes a single parameter: the date/time object to be processed.Syntax: Quarter(Date) Example: The following example returns the current quarter: We are in quarter #Quarter(Now())# of year #Year(Now())# TIP Always enclose date/time values in quotes when passing them to the Quarter() function as strings. Without quotes, the value passed is interpreted as a numeral representation of a date/time object. See also Day(), DayOfWeek(), DayOfYear(), Hour(), Minute(), Month(), Second(), Week(), Year() QueryAddColumn() Description: QueryAddRow() adds a row to an existing ColdFusion query. QueryAddRow() takes two parameters: the query to which to add a row and an optional number of rows to add. If the number of rows is omitted, the default number of 1 is used.Syntax: QueryAddRow(Query [, Number]) Example: The following example creates a new query called Users and adds 10 rows to it: <cfset Users = QueryNew("FirstName, LastName")> <cfset temp = QueryAddRow(Users, 10)> See also QueryNew(), QuerySetCell() QueryNew() Description: QuerySetCell() is used to set the values of specific cells in a table. QuerySetCell() takes four parameters: the query name, the column name, the value, and an optional row number. If the row number is omitted, the cell in the last query row is set.Syntax: QuerySetCell(Query, Column, Value [, Row]) Example: The following example sets the FirstName column in the third row to the value Ben: <cfset temp = QuerySetCell(Users, "FirstName", "John", 3)> NOTE Description: QuotedValueList() drives one query with the results of another. It takes a single parameterthe name of a query columnand return a list of all the values in that column. QuotedValueList() returns a list of values that are each enclosed within quotation marks and separated by commas.Syntax: QuotesValueList(Column) Example: The following example passes the results from one query to a second query: SELECT * FROM Customers WHERE CustomerType IN (#QuotedValueList(CustType.type)#) NOTE The values returned by QuotedValueList() is in the standard ColdFusion list format and can therefore be manipulated by the list functions.TIP Description: Rand() takes one optional parameter, algorithm, and returns a random number between 0 and 1. The algorithm parameter can be one of the following values: CFMX_COMPAT, SHA1PRNG, IBMSecureRandom. CFMX_COMPAT is the default and will cause Rand() to mimic the behavior of ColdFusion MX and earlier versions. SHA1PRNG uses the Sun Java algorithm of the same name, and IBMSecureRandom is for use on WebSphere servers.Syntax: Rand([algorithm]) Example: The following example returns a random number: #Rand("SHA1PRNG")# See also Randomize(), RandRange() Randomize() Description: RandRange() returns a random integer value between the two passed numbers. This function requires two numeric parameters and enables you to optionally specify the randomization algorithm. You can pass real values, integer values, and ColdFusion fields to this function.The algorithm parameter can be one of the following values: CFMX_COMPAT, SHA1PRNG, IBMSecureRandom. CFMX_COMPAT is the default and will cause Randomize() to mimic the behavior of ColdFusion MX and earlier versions. SHA1PRNG uses the Sun Java algorithm of the same name, and IBMSecureRandom is for use on WebSphere servers.Syntax: RandRange(number1, number2[,algorithm]) Example: The following example returns a random integer value between 5 and 10, just as it would have been produced in ColdFusion MX or earlier: #RandRange(5, 10, "CFMX_COMPAT")# See also Randomize(), Rand() REFind() Regular expressions enable you to perform complex searches through text strings with relative ease. Rather than forcing you to provide the exact text for which you are searching, using the REFind and REFindNoCase functions gives you the flexibility of searching for dynamic data. Suppose you wanted to search a string for the first occurrence of any character except vowels. In this case, using REFindNoCase would make your job much easier. See also REFindNoCase(), FindOneOf(), GetToken(), Left(), Mid(), Right() REFindNoCase() Regular expressions enable you to perform complex searches through text strings with relative ease. Rather than forcing you to provide the exact text for which you are searching, using the REFindNoCase() function gives you the flexibility of searching for dynamic data. Suppose you wanted to search a string for the first occurrence of any character except vowels. See also REFind(), FindOneOf(), GetToken(), Left(), Mid(), Right() ReleaseCOMObject() Description: RemoveChars() returns a string with specified characters removed from it. This function is the exact opposite of the Mid() function. RemoveChars() takes three parameters: The first is the string from which to remove the characters; the second is the starting position of the characters to be removed; and the third is the number of characters to be removed. If no characters are found in the string being evaluated, the RemoveChars function returns 0.Syntax: RemoveChars(String, StartPosition, Length) Example: The following example returns a field with characters 10 through 14 removed: #RemoveChars(product_code, 10, 5)# See also Left(), Mid(), Right() RepeatString() Description: Replace() enables you to replace text within strings with alternative text. Replace() does a simple text comparison to locate the text to be replaced. It takes four parameters. The first parameter is the string to be processed; the second is the text to be replaced; the third is the text to replace it with. The fourth parameter is optional and specifies the scope of the replacements. Possible scope values are "ONE" to replace the first occurrence only, "ALL" to replace all occurrences, and "RECURSIVE" to replace all occurrences recursively.Syntax: Replace(String, WhatString, WithString [, Scope]) Example: The following example replaces all occurrences of the text "US" in an address field with the text "USA": #Replace(address, "US", "USA", "ALL")# This next example replaces the area code "(313)" with the area code "(810)", and because no scope is specified, only the first occurrence of "(313)" is replaced: #Replace(phone, "(313)", "(810)")# TIP Description: REReplace() enables you to perform case-sensitive searches and replace text within strings with alternative text using regular expressions. It takes four parameters. The first parameter is the string to be processed; the second is the text to be replaced; the third is the text to replace it with. The fourth parameter is optional and specifies the scope of the replacements. Possible scope values are "ONE" to replace the first occurrence only, "ALL" to replace all occurrences, and "RECURSIVE" to replace all occurrences recursively.Syntax: REReplace(String, WhatString, WithString [, Scope]) Example: The following example returns Cohn, by replacing the capital letter J with the capital letter C. The lowercase n was ignored because REReplace() is case-sensitive. #REReplace("John","J|N","C","ALL")# See also Replace(), REReplace(), ReplaceList() REReplaceNoCase() Description: ReplaceList() replaces all occurrences of elements in one string with corresponding elements in another. Both sets of elements must be specified as comma-delimited values, and an equal number of values must exist in each set. ReplaceList takes three parameters. The first is the string to be processed; the second is the set of values to be replaced; and the third is the set of values with which to replace them.Syntax: ReplaceList(String, FindWhatList, ReplaceWithList) Example: The following example replaces all occurrences of state names with their appropriate abbreviations: #ReplaceList(address, "CA, IN, MI", "California, Indiana, Michigan")# TIP Unlike other replacement functions, the ReplaceList() function takes no scope parameter. ReplaceList() replaces all occurrences of matching elements. See also Replace() Reverse() Description: Right() returns the specified rightmost characters from the end of a string. Right() takes two parameters: the string from which to extract the characters and the number of characters to extract.Syntax: Right(String, Count) Example: The following example returns the last seven characters of a phone number column: #Right(phone_number, 7)# TIP Description: RJustify() right-aligns a string within a field of a specified length. It does this by padding spaces before the specified text. RJustify() takes two parameters: the string to process and the desired string length.Syntax: RJustify(string, length) Example: The following example right-justifies the contents of a field named Zip so that it is right-aligned within a 10-character-wide field: #RJustify(Zip, 10)# See also CJustify(), LJustify(), LTrim(), RTrim(), Trim() Round() Description: RTrim()TRims white space (spaces, tabs, and new-line characters) from the end of a string. RTrim() takes a single parameter: the string to be trimmed.Syntax: RTrim(String) Example: The following example trims spaces from the end of a user-supplied field: #RTrim(first_name)# See also CJustify(), LJustify(), LTrim(), RJustify(), Trim(), StripCR() Second() Always enclose date/time values in quotes when passing them to the Second() function as strings. Without quotes, the value passed is interpreted as a numeral representation of a date/time object. See also Day(), DayOfWeek(), DayOfYear(), Hour(), Minute(), Month(), Quarter(), Week(), Year() SendGatewayMessage() Description: SetLocale() sets the name of the locale to be used by any subsequent calls to the LS functions. SetLocale() also returns the name of the currently active locale so that it can be saved if necessary.Syntax: SetLocale(locale) Example: The following example sets the locale to British English and saves the current locale to a local variable: <cfset previous_locale = #SetLocale("English (UK)")#> See also GetLocale(),GetLocaleDisplayName() SetProfileString() Description: SetVariable() sets a specified variable to a passed value.Syntax: SetVariable(Variable, Value) Example: The following example sets variable #cnt# to the value returned by the passed expression: #SetVariable("cnt", "A")# Sgn() Description: Sin() returns the sine of a passed number. This function takes only one numeric value as a parameter. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Sin(number) Example: The following example returns -0.756802495308, the sine of 4: #Sin(4)# See also Asin(), Atn(), Cos(), Pi(), Tan() SpanExcluding() The SpanExcluding() function is case sensitive, and there is no non-case-sensitive equivalent function. To perform a non-case-sensitive extraction, you first must convert both the search and target strings to either upper- or lowercase (using the UCase() or LCase() function). See also SpanIncluding() SpanIncluding() The SpanIncluding()function is case sensitive, and there is no non-case-sensitive equivalent function. To perform a non-case-sensitive extraction, you first must convert both the search and target strings to either upper- or lowercase (using the UCase() or LCase()function). See also SpanExcluding() Sqr() Description: StripCR() removes all carriage return characters from a string. StripCR() takes a single parameter: the string to be processed.Syntax: StripCR(String) Example: The following example removes carriage returns for a field to be displayed in a preformatted text block: <pre>#StripCR(comments)#</pre> TIP Description: StructAppend() appends one structure to another. StructAppend() takes three parameters: the two structures (the second is appended to the first), and an overwrite flag specifying whether to overwrite existing items. StructAppend() always returns YES.Syntax: StructAppend(struct1, struct2, flag) Example: The following example appends a structure overwriting any existing items: #StructAppend(keys, newkeys, TRUE)# See also Duplicate(), StructNew(), StructCopy() StructClear() StructClear() does not delete the actual structure. Rather, it removes all of its contents. The structure itself remains and can be reused. See also StructDelete(), StructIsEmpty() StructCopy() On the surface, StructCopy() appears similar to the Duplicate() function. The main difference is that when using the Duplicate() function to copy a structure, you are creating a completely new copy of the specified structure, with no reference to the original. StructCopy() assigns any nested structures, objects, or query values to the new structure by making reference to the original. See also Duplicate(), StructClear() StructCount() Description: StructDelete() deletes an item from a structure. StructDelete() takes three parameters: the structure, the name of the key to be deleted, and an optional flag that specifies how to handle requests to delete a key that does not exist. StructDelete() returns YES if the operation is successful and NO if not. If an attempt is made to delete a key that does not exist, and the IndicateNotExisting flag is not set to trUE, the StructDelete() returns YES.Syntax: StructDelete(Structure, Key [, IndicateNotExisting]) Example: The following example deletes the name key from a user structure: #StructDelete(user, name)# See also StructClear(), StructKeyExists(), StructIsEmpty() StructFind() Description: The StructFindKey() function searches recursively through a structure to find any keys that match the specified search text. If matching keys are found, they are returned in an array. This function takes three parameters: the first is the structure (or array) to be searched, the second is the key for which to search, the third is a scope flag specifying ONE to find the first match or ALL to find all matches.Syntax: StructFindKey(Structure, Key, Scope) Example: The following example returns all keys that match a user specified string: <cfset results=StructFindKey(prods, FORM.search, "ALL")> See also StructFind(), StructFindValue() StructFindValue() Description: StructGet() gets an array of structures from a specified path. StructGet() takes a single parameter: the path to be used.Syntax: StructGet(Path) Example: The following example gets a structure from a specified path: <cfset struct=StructGet("catalog.product.widgets")> See also StructNew() StructInsert() Description: StructIsEmpty() checks whether a structure has data. StructIsEmpty() takes a single parameter: the structure to be checked. StructIsEmpty() returns trUE if the array is empty and FALSE if not.Syntax: StructIsEmpty(Structure) Example: The following example reports whether a structure is empty: <cfoutput>Strucure empty: #YesNoFormat(StructIsEmpty(Users))#</cfoutput> See also StructClear(), StructCount(), StructKeyExists() StructKeyArray() The array the StructKeyArray() function returns is in no particular order. To sort the array, use the ArraySort() function. Also, remember that if the structure you are attempting to evaluate with the StructKeyArray() function does not exist, ColdFusion throws an error. See also StructClear(), StructDelete(), StructFind(), StructUpdate() StructKeyExists() Description: StructKeyList() returns a list of keys in the specified ColdFusion structure. The StructKeyList() function takes two parameters. The first parameter is the structure to be evaluated. The second, optional parameter is the delimiter to separate each list item that is returned.Syntax: StructKeyList(structure [,delimiter]) Example: The following example retrieves a list of keys, delimited by a comma, from the specified structure: #StructKeyList(MyStructure ,",")# See also StructKeyArray(), StructClear() StructNew() Description: The StructSort() function returns an array of structure keys sorted as needed. The StructSort() function takes four parameters. The first is the structure to sort. The second is an optional path to append to keys to reach the element to sort by. The third is the sort type, either NUMERIC, TEXT (the default), or TEXTNOCASE. The fourth is the sort order (ASC or DESC).Syntax: StructSort(structure, path, sort, order) Example: The following example displays a list of keys sorted using defaults: <cfoutput>#ArrayToList(StructSort(products))# </cfoutput> StructUpdate() Description: Tan() returns the tangent of a passed number. This function takes only one numeric value as a parameter. You can pass real values, integer values, and ColdFusion fields to this function.Syntax: Tan(number) Example: The following example returns 1.15782128235, the tangent of 4: #Tan(4)# See also Atn(), Asin(), Cos(), Sin(), Pi() TimeFormat() Unlike the DateFormat() function mask specifiers, the TimeFormat() function mask specifiers are case-sensitive on the hour mask.NOTE Description: The ToBase64() function returns the Base64 representation of a specified string or binary object. Base64 format converts a string or an object to printable characters that can then be sent as text in e-mail or stored in a database. The ToBase64() function can take two parameters. The first is the string or binary value to be encoded. The second parameter, encoding, is optional and is used when working with binary data. It indicates how string data is to be encoded and can be set to US-ASCII, ISO-8859-1, UTF-8, or UTF-16.Syntax: ToBase64(string or binary_value, encoding) Example: The following example converts a simple text string to Base64-encoded format: #ToBase64("Laura is a pretty girl")# NOTE Description: The ToBinary() function either converts a Base64-encoded string to a binary representation. The ToBinary() function also takes a single parameter: the Base64-encoded string to be converted.Syntax: ToBinary(encoded_string or binary_value) Example: The following example reads the contents of an image file into memory, converts the image file to a Base64-encoded string, and then converts the file from a Base64-encoded string back to a binary value: <cffile ACTION="READ" file="FULL PATH OF THE IMAGE FILE" variable="ImgFile"> <cfset EncodedImage = ToBase64(ImgFile)> <cfset BinaryImage = ToBinary(EncodedImage)> TIP When converting a Base64-encoded string back to its original state, you first must convert this string to a binary object. After you've done that, you can use the ToString() function to convert the resulting binary object back into a string. See also ToBase64(), IsBinary(), ToString() ToScript() Description: The ToString() function attempts to convert any value, including binary values, into a string. If the value specified can't be converted into a string, the ToString() function throws an exception error. The ToString() function takes two parameters. The first is the value to be converted to a string. The second is the name of the encoding scheme. This can be used when working with binary data and can be set to US-ASCII, ISO-8859-1, UTF-8 or UTF-16.Syntax: ToString(any_value, encoding) Example: The following example converts the specified value into a string: #ToString(BinaryData, "ISO-8859-1")# trim() Description: UCase() converts a string to uppercase. UCase() takes a single parameterthe string to be convertedand returns the converted string.Syntax: UCase(String) Example: The following example converts the contents of a table column called States to uppercase: #UCase(State)# See also LCase() URLDecode() Description: URLEncodedFormat() encodes a string in a format that can safely be used within URLs. URLs can't contain spaces or any non-alphanumeric characters. The URLEncodedFormat() function replaces spaces with a plus sign; non-alphanumeric characters are replaced with equivalent hexadecimal escape sequences. URLEncodedFormat() takes a single parameterthe string to be encodedand returns the encoded string.Syntax: URLEncodedValue(String) NOTE Description: Val() converts the beginning of a string to a number. Val() takes a single parameter: the string to be processed. Conversion is possible only if the string begins with numeric characters. If conversion is impossible, 0 is returned.Syntax: Val(String) Example: The following example extracts the hour portion from a time field: Hour: #Val(time)# TIP Description: The WriteOutput() function appends text to the page output stream, regardless of the setting specified in a given CFSETTING block. The WriteOutput() function takes a single parameter: the string to be output to the page.Syntax: WriteOutput(string) Example: The following example writes the specified output to the page output stream: #WriteOutput("Users Processed: Sean, Misty, Parker, Laura, Peggy, Delane")# ValueList() The ValueList()function is typically used only when constructing dynamic SQL statements.TIP As a general rule, you always should try to combine both of the queries into a single SQL statement, unless you need to manipulate the values in the list. The time it takes to process one combined SQL statement is far less than the time it takes to process two simpler statements. See also ValueList() Week() When specifying the year using the Week() function, be aware that ColdFusion will interpret the numeric values 029 as 21st-century years. The numeric values 3099 are interpreted as 20th-century years.TIP Description: Wrap() is used to wrap text to a specific line length. It requires two parametersthe text to wrap and the length to wrap it to. You can optionally use the third parameter to indicate whether or not you want any carriage-return or line-feed characters in the text to be removed (this defaults to False).Syntax: Week(textValue, length[, Strip]) Example: The following example wraps a line to 25 characters: <cfset myText = "The quick brown fox jumped in the hen house ~CA and ate some good lookin chicks."> <pre><cfoutput>#Wrap(myText, 25)#</cfoutput></pre> XMLChildPos() Description: Returns the XML document object (first parameter) with a new child element created (specified in the third parameter). You can optionally include a namespace URI as the second parameter. It will generate an xmlns attribute in each element of this type that is created. (Namespaces are used to avoid ambiguities that arise when different XML documents being processed share elements with the same name.)CF will automatically add the xmlns attribute to elements when you have included the namespace prefix in the childName parameter for those elements and the namespace parameter for (corresponding to that prefix) somewhere else in the xml.Syntax: XMLElemNew(XMLDocObj[, nameSpace], childName) Example: The following example adds the element named "order" to the Orders XML document object: <cfscript> myOrders.Order.XmlChildren[1] = XmlElemNew(myOrders,"OrderLine"); </cfscript> XMLFormat() Description: The XMLGetNodeType() function takes one parametera node from an XML object (or the object itself)and returns one of several constant values that indicating the type of node it is. The possible return values are:ATTRIBUTE_NODECDATA_SECTION_NODECOMMENT_NODEDOCUMENT_FRAGMENT_NODEDOCUMENT_NODEDOCUMENT_TYPE_NODEELEMENT_NODEENTITY_NODEENTITY_REFERENCE_NODENOTATION_NODEPROCESSING_INSTRUCTION_NODETEXT_NODE Syntax: XMLGetNodeType(nodeObject) Example: The following example creates an XML object. It then displays the types of nodes represented by the document itself and other nodes: <cfxml variable="xmlPeople"> <?xml version="1.0" encoding="UTF-8"?> <people> <person id="123"> <name type="first">joe</name> <name type="last">blow</name> <phone type="home">323-232-1111</phone> <children> <child firstName="Frank" /> <child firstName="Betty" /> </children> </person> </people> </cfxml> <cfoutput> <p>root ojbect: #XMLGetNodeType(xmlPeople)#</p> <p>person node: #XMLGetNodeType(xmlPeople.people.person)#</p> <cfset myPersonArray = xmlPeople.people.person.XMLNodes> <cfloop from="1" to="#arraylen(myPersonArray)#" index="ii"> <p>#myPersonArray[ii].XMLName#: #XMLGetNodeType(myPersonArray[ii])#</p> </cfloop> </cfoutput> XMLNew() Description: The XMLParse() function converts a string of XML into an XML document object. It takes up to three parameters: the string value, a value of YES or NO, indicating case sensitivity and a reference to a DTD to validate the XML with.The validator can be presented in several forms:The URL of a DTD or XML Schema fileThe name of a DTD or XML Schema fileA string containing the DTD or SchemaUse an empty string value for validator if the XML file you're parsing contains a DTD or Schema identifier.Syntax: XMLParse(string[, CaseSensitive], validator]]) Example: The following example converts the specified string to a format that is safe to use with XML: <!--- Read XML document into a variable. ---> <cffile action="READ" file="c:\neo\wwwroot\ows\c\Orders.xml" variable="myXMLfile"> <!--- Create new CF XML document object ---> <cfset x=XMLParse(myXMLfile, "no")> <!--- Display new CF XML document object ---> <cfdump var="#x#"> NOTE Description: The XMLSearch() function uses an XPath expression to search an XML document object. It returns an array of matching object nodes that match the search criteria.Syntax: XMLSearch(XMLDocObj, XPath_exp) Example: The following example reads an XML file into a string and converts it to an XML document object. It then searches for the "order" elements in the "orders" node. It then outputs the name for each order that it found: <cffile action="READ" file="c:\neo\wwwroot\ows\c\Orders.xml" variable="myXMLfile"> <cfscript> myXMLdoc = XMLParse(myXMLfile); someElements = XMLSearch(myXMLdoc, "/orders/order"); for (i = 1; i LTE ArrayLen(someElements); i = i + 1) { WriteOutput( "Child " & i & " = " & someElements[i].XMLName & "<br />"); } </cfscript> XMLTransform() Description: You supply XMLValidate() with an XML Schema or a DTD and it will validate an XML object or XML text. It takes two parameters, xmlDoc and optionally, validator. The xmlDoc can be:A string containing an XML documentThe name of an XML fileA URL (using http, https, ftp or file protocols)An XML document object The validator parameter can be:A string containing a DTD or SchemaThe name of a DTD or Schema fileThe URL of a DTD or Schema file (can use http, https, ftp or file protocols) It returns a structure containing the elements described in Table C.42Table C.42. XMLValidate() Return Structure ELEMENTDESCRIPTIONerrorsAn array containing error messages from the validator.fatalErrorsAn array containing fatal error messages from the validator.statusTrue if the XML is valid. False if it isn't.warningAn array containing warning messages from the validator.Note that if you omit the validator parameter and the XML does not identify a DTD or Schema (with a <!DOCTYPE> tag), XMLValidate() will return an error message in the errors element of the return value structure. If the XML includes a <!DOCTYPE> tag that specifies a DTD or Schema and you provide a validator parameter too, the validator parameter will be used to validate the XML, ignoring the <!DOCTYPE> tag.Syntax: XMLValidate(XMLDcoument[, validator]) Example: The example below uses a local Schema file, person.xsd, and validates a local xml file with it. The .xsd file is presented, then the .xml and then the code that employs XMLValidate(). <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns: xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="person"> </xs:element> <xs:element name="people"> <xs:complexType> <xs:sequence> <xs:element ref="person" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> Here's the .xml file: <?xml version="1.0" encoding="UTF-8"?> <people> <person>This is a person</person> </people> And here's the code to do the validation: <cfset validStruct=XMLValidate( ~CA "C:\blackstone\wwwroot\ows\c\person.xml", ~CA "http://localhost:8500/ows/c/person.xsd")> Was persons.xml validated successfuly by pseron.xsd? <cfoutput>#validStruct.status#</cfoutput> <p>Dump of validStruct returned by XMLValidate()<br> <cfdump var="#validStruct#"></p> See also IsXMLDoc() Year() Description: YesNoFormat() converts TRUE and FALSE values to Yes and No. YesNoFormat() takes a single parameterthe number, string, or expression to evaluate. When evaluating numbers, YesNoFormat() treats 0 as NO and any nonzero value as YES.Syntax: YesNoFormat(Value) Example: The following example converts a table Boolean value to a Yes or No string: Member: <cfoutput>#YesNoFormat(member)#</cfoutput> Appendix D. Special ColdFusion Variables and Result Codes Special ColdFusion Variables and Result Codes NOTE ATTRIBUTE Variables CALLER Variables CGI Variables NOTE NOTE TIP NOTE <cfcatch> Variables <cfcollection action="list"> Query Columns <cfdirectory action="list"> Query Columns NOTE <cffile action="upload"> Variables <cfftp> Variables NOTE <cfftp action="ListDir"> Query Columns NOTE <cfhttp> Variables NOTE <cfldap action="query"> Query columns NOTE <cfpop action="GetHeaderOnly|GetAll"> Query Columns <cfquery> Variables <cfregistry> Query Variables NOTE <cfsearch> Results Variables NOTE <cfservlet> Variables <cfstoredproc> Variables CLIENT Variables COOKIE Variables ERROR Variables FORM Variables Query Variables NOTE REQUEST Variables SERVER Variables NOTE SESSION Variables TIP ThisTag Variables URL Variables Appendix E. Verity Search Language Using Angle Brackets Around Operators Operators Are Not Case Sensitive Using Prefix Instead of Infix Notation Searching for Special Characters as Literals Understanding Concept Operators Understanding Evidence Operators NOTE NOTE Understanding Proximity Operators Understanding Relational Operators NOTE Understanding Search Modifiers Understanding Score Operators Appendix F. ColdFusion MX 7 Directory Structure NOTE NOTE CAUTION bin bin/connectors cache CFX CFX/examples CFX/include CFX/java/distrib/examples NOTE charting charting/cache charting/fonts charting/styles CustomTags db db/slserver55 jintegra/bin NOTE lib NOTE TIP logs NOTE Mail Mail/Spool Mail/Undelivr META-INF runtime runtime/bin runtime/jre runtime/lib runtime/logs runtime/servers/coldfusion/SERVER-INF stubs verity verity/collections wwwroot wwwroot/cfdocs wwwroot/CFIDE wwwroot/CFIDE/adminapi wwwroot/CFIDE/gettingstarted wwwroot/CFIDE/installers wwwroot/CFIDE/scripts/xsl TIP Appendix G. Sample Application Data Files Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index Index

توضیحات
افزودن یادداشت جدید





  • Sending Email from ColdFusion


    ColdFusion's main purpose is to create dynamic, data-driven Web pages. But it also provides a set of email-related tags that let you send email messages that are just as dynamic and data-driven as your Web pages. You can also write ColdFusion templates that check and retrieve email messages, and even respond to them automatically.

    NOTE

    <cfmail> sends standard, Internet-style email messages using the Simple Mail Transport Protocol (SMTP). SMTP isn't explained in detail in this book; for now, all you need to know about SMTP is that it's the standard for sending email on the Internet. Virtually all email programs, such as Netscape, Outlook Express, Eudora, and so on send standard SMTP mail. The exceptions are proprietary messaging systems, such as Lotus Notes or older Microsoft Mail (MAPI-style) clients. If you want to learn more about the underpinnings of the SMTP protocol, visit the World Wide Web Consortium's Web site at www.wc3.org .

    Introducing the <cfmail> Tag


    You can use the <cfmail> tag to send email messages from your ColdFusion templates. After the server is set up correctly, you can use <cfmail> to send email messages to anyone with a standard Internet-style email address. As far as the receiver is concerned, the email messages you send with <cfmail> are just like messages sent via a normal email sending program, such as Netscape, Outlook Express, Eudora, or the like.

    . Text is the default, which means that the message will be sent as a normal, plain-text message. means tha275 tags within the message will be interpreted a274, so you can specify fonts and include images in the email message. See "," later in this chapter.

    wrapText

    Optional. If specified, the text in your email will automatically wrap according to the number passed in. A typical value for wrapText is 72. The default value is to not wrap text.

    mailerID

    Optional. Can be used to specify the X-Mailer header that is sent with the email message. The X-Mailer header is meant to identify which software program was used to send the message. This header is generally never seen by the recipient of the message but can be important to systems in between, such as firewalls. Using the mailerID, you can make it appear as if your message is being sent by a different piece of software. If you find that your outgoing messages are being filtered out when sent to certain users, try using a mailerID that matches another mail client (such as Outlook Express or some other popular, end-user mail client).

    mimeAttach

    Optional. A document on the server's drive that should be included in the mail message as an attachment. This is an older way to specify attachments, maintained for backward compatibility. It's now recommended that you use the <cfmailparam> tag to specify attachments. For details, see "Adding Attachments," later in this chapter.

    charset

    Optional. This specifies the character encoding that will be used in the email. It defaults to the value set in the ColdFusion Administrator.

    spoolEnable

    Optional. Controls whether the email message should be sent right away, before ColdFusion begins processing the rest of the template. The default value is Yes, which means that the message is created and placed in a queue. The actual sending will take place as soon as possible, but not necessarily before the page request has been completed. If you use spoolEnable="No", the message will be sent right away; ColdFusion won't proceed beyond the <cfmail> tag until the sending has been completed. In other words, No forces the mail sending to be a synchronous process; Yes (the default) lets it be an asynchronous process.

    NOTE

    Some additional <cfmail> attributes are introduced later in this chapter (see Table 27.2 in the "Sending Data-Driven Mail" section and Table 27.4 in the "Overriding the Default Mail Server Settings" section).

    Table 27.2. Additional <cfmail> Attributes for Sending Data-Driven Email Messages

    ATTRIBUTE

    PURPOSE

    query

    Optional. A query to use for sending data-driven email. Very similar to the QUERY attribute of the <cfoutput> tag.

    startRow

    Optional. A number that indicates which row of the query to consider when sending data-driven email. The default is to start at the first row. Equivalent to the startRow attribute of the <cfoutput> tag.

    maxRows

    Optional. A maximum number of query rows to consider when sending data-driven email. Equivalent to the maxRows attribute of the <cfoutput> tag.

    group

    Optional. A column name from the query that indicates groups of records. Additional output or processing can occur when each new group is encountered. You can indicate nested groups by providing a comma-separated list of column names. Equivalent to the group attribute of the <cfoutput> tag.

    groupCaseSensitive

    Optional. Whether to consider text case when determining when a new group of records has been encountered in the column(s) indicated by group. Equivalent to the groupCaseSensitive attribute of the <cfoutput> tag.

    Table 27.4. Additional <cfmail> Attributes for Overriding the Mail Server Settings

    ATTRIBUTE

    PURPOSE

    server

    Optional. The host name or IP address of the mail server ColdFusion should use to actually send the message. If omitted, this defaults to the Mail Server setting on the Mail/Mail Logging page of the ColdFusion Administrator. If you are using the Enterprise edition of ColdFusion, a list of mail servers can be provided here.

    port

    Optional. The port number on which the mail server is listening. If omitted, this defaults to the Server Port setting on the Mail/Mail Logging page of the ColdFusion Administrator. The standard port number is 25. Unless your mail server has been set up in a nonstandard way, you should never need to specify the port.

    timeout

    Optional. The number of seconds ColdFusion should spend trying to connect to the mail server. If omitted, this defaults to the Connection Timeout setting on the Mail/Mail Logging page of the ColdFusion Administrator.

    Specifying a Mail Server in the Administrator


    Before you can actually use the <cfmail> tag to send email messages, you need to specify a mail server in the ColdFusion Administrator. This is the mail server with which ColdFusion will interact to actually send the messages generated by your templates.

    To set up ColdFusion to send email, follow these steps:


    1.

    If you don't know it already, find out the host name or IP address for the SMTP mail server ColdFusion should use to send messages. Usually, this is the same server your normal email client program (Outlook Express, Eudora, and so on) uses to send your own mail, so you typically can find the host name or IP address somewhere in your mail client's Settings or Preferences. Often, the host name starts with something such as mail or smtp, as in mail.orangewhipstudios.com .

    2.

    Open the ColdFusion Administrator, and navigate to the Mail page, as shown in Figure 27.1.

    Figure 27.1. Before messages can be sent, ColdFusion needs to know which mail server to use.

    [View full size image]

    3.

    Provide the mail server's host name or IP address in the Mail Server field.

    4.

    Check the Verify Mail Server Connection option.

    5.

    If your mail server operates on a port other than the usual port number 25, provide the port number in the Server Port field. (This usually isn't necessary.)

    6.

    Save your changes by clicking the Submit Changes button.


    TIP

    These settings can be overridden in individual ColdFusion templates by the <cfmail> tag. See the "Overriding the Default Mail Server Settings" section, later in this chapter.

    For more information about the other Mail Server options shown in Figure 27.1, see Chapter 29, "ColdFusion Server Configuration."

    Sending Email Messages


    Sending an email message via a ColdFusion template is easy. Simply code a pair of opening and closing <cfmail> tags, and provide the to, from, and subject attributes as appropriate. Between the tags, type the actual message that should be sent to the recipient.

    Of course, you can use ColdFusion variables and functions between the <cfmail> tags to build the message dynamically, using the # sign syntax you're used to. You don't need to place <cfoutput> tags within (or outside) the <cfmail> tags; your # variables and expressions will be evaluated as if there were a <cfoutput> tag in effect.

    TIP

    As you look through the examples in this chapter, you will find that the <cfmail> tag is basically a specially modified <cfoutput> tag. It has similar behavior (variables and expressions are evaluated) and attributes (group, maxrows, and so on, as listed in Table 27.4).

    Sending a Simple Message

    Listing 27.1 shows how easy it is to use the <cfmail> tag to send a message. The idea behind this template is to provide a simple form for people working in Orange Whip Studios' personnel department. Rather than having to open their normal email client programs, they can just use this Web page. It displays a simple form for the user to type a message and specify a recipient, as shown previously in Figure 27.1. When the form is submitted, the message is sent.

    Listing 27.1. PersonnelMail1.cfmSending Email with ColdFusion


    <!--- 
    Filename: PersonnelMail1.cfm
    Author: Nate Weiss (NMW)
    Purpose: A simple form for sending email
    --->
    &l275>
    <head>
    <title>Personnel Office Mailer</title>
    <!--- Apply simple CSS formatting to <th> cells --->
    <style>
    th {background:blue;color:white;text-align:right}
    </style>
    </head>
    <body>
    <h2>Personnel Office Mailer</h2>
    <!--- If the user is submitting the Form... --->
    <cfif isDefined("FORM.subject")>
    <!--- We do not want ColdFusion to suppress whitespace here --->
    <cfprocessingdirective suppressWhitespace="No">
    <!--- Send the mail message, based on form input --->
    <cfmail
    subject="#FORM.subject#"
    from="personnel@orangewhipstudios.com"
    to="#FORM.toAddress#"
    bcc="personneldirector@orangewhipstudios.com"
    >This is a message from the Personnel Office:
    #FORM.messageBody#
    If you have any questions about this message, please
    write back or call us at extension 352. Thanks!</cfmail>
    </cfprocessingdirective>
    <!--- Display "success" message to user --->
    <p>The email message was sent.<br>
    By the way, you look fabulous today. 
    You should be in pictures!<br>
    <!--- Otherwise, display the form to user... ---> 
    <cfelse>
    <!--- Provide simple form for recipient and message --->
    <cfform action="#cgi.script_name#" method="post">
    <table cellPadding="2" cellSpacing="2">
    <!--- Table row: Input for Email Address --->
    <tr>
    <th>EMail Address:</th>
     <td>
    <cfinput type="text" name="toAddress" required="yes" size="40"
    message="You must provide an email address.">
    </td>
    </tr>
    <!--- Table row: Input for E-mail Subject --->
    <tr>
    <th>Subject:</th>
    <td>
    <cfinput type="text" name="subject" required="yes" size="40"
    message="You must provide a subject for the email.">
    </td>
    </tr>
    <!--- Table row: Input for actual Message Text --->
    <tr>
    <th>Your Message:</th>
    <td>
    <cftextarea name="messageBody" cols="30" rows="5" wrap="hard"
    required="yes" message="You must provide a message body." />
    </td>
    </tr>
    <!--- Table row: Submit button to send message --->
    <tr>
    <td>&nbsp;</td>
    <td>
    <cfinput type="submit" name="submit" value="Send Message Now">
    </td>
    </tr>
    </table>
    </cfform>
    </cfif> 
    </body>
    </html>

    There are two parts to this listing, divided by the large <cfif>/<cfelse> block. When the page is first visited, the second part of the template executes, which displays the form shown in Figure 27.2.

    Figure 27.2. Creating a Web- based mail-sending mechanism for your users is easy.

    When the form is submitted, the first part of the template kicks in, which actually sends the email message with the <cfmail> tag. The message's subject line and "to" address are specified by the appropriate form values, and the content of the message itself is constructed by combining the #FORM.messageBody# variable with some static text. Additionally, each message sent by this template is also sent to the personnel director as a blind carbon copy, via the bcc attribute.

    Around the <cfmail> tag, the <cfprocessingdirective> tag is used to turn off ColdFusion's default white-space-suppression behavior. This is needed in this template because the <cfmail> tag that follows is written to output the exact text of the email message, which includes "newlines" and other white space characters that should be included literally in the actual email message. Without the <cfprocessingdirective> tag, ColdFusion would see the newlines within the <cfoutput> tags as evil white space, deserving to be ruthlessly suppressed.


    For more information about white-space suppression and the <cfprocessingdirective> tag, see the "Controlling White Space" section in Chapter 25, "Improving Performance."

    " section, because white space isn't significant i269.

    Using Friendly Email Addresses

    The email address provided to the to, from, cc, and bcc attributes can be specified as just the email address itself (such as bforta@orangewhipstudios.com), or as a combination of the address and the address's friendly name. The friendly name is usually the person's real-life first and last names.

    To specify a friendly name along with an email address, place the friendly name between double quotation marks, followed by the actual email address between angle brackets. So, instead of


    bforta@orangewhipstudios.com

    you would provide


    "Ben Forta" <bforta@orangewhipstudios.com>

    To provide such an address to the from, to, cc, or bccattribute of the <cfmail> tag, you must double up each double quotation mark shown above, assuming that you are already using double quotation marks around the whole attribute value. So, you might end up with something such as the following:


    <cfmail
    subject="Dinner Plans"
    from=""Nate Weiss" <nweiss@orangewhipstudios.com>"
    to=""Belinda Foxile" <bfoxile@orangewhipstudios.com>">

    If you find the use of the doubled-up double quotation marks confusing, you could surround the fromand to attributes with single quotation marks instead of double quotation marks, which would allow you to provide the double-quotation characters around the friendly name normally, like so:


    <cfmail
    subject="Dinner Plans"
    from='"Nate Weiss" <nweiss@orangewhipstudios.com>'
    to='"Belinda Foxile" <bfoxile@orangewhipstudios.com>'>

    Now, when the message is sent, the "to" and "from" addresses shown in the recipient's email program can be shown with each person's real-life name along with their email address. How the friendly name and email address are actually presented to the user is up to the email client software.

    The version of the PersonnelMail.cfm template shown in Listing 27.2 is nearly the same as the one from Listing 27.1, except that this version collects the recipient's friendly name in addition to their email address. Additionally, this version uses a bit of JavaScript to attempt to pre-fill the email address field based on the friendly name. When the user changes the value in the FirstName or LastName field, the ToAddress field is filled in with the first letter of the first name, plus the whole last name.

    NOTE

    There isn't space to go through the JavaScript code used in this template in detail. It's provided to give you an idea of one place where JavaScript can be useful. Consult a JavaScript reference or online tutorial for details. One good place to look is the JavaScript section of the Reference tab of the Code panel in Dreamweaver.

    Limiting Input

    This version of the form makes it impossible to send messages to anyone outside of Orange Whip Studios, by simply hard-coding the @orangewhipstudios.com part of the email address into the <cfmail> tag itself. Also, it forces the user to select from a short list of Subject lines, rather than being able to type their own Subject, as shown in Figure 27.3.

    Figure 27.3. Web-based forms can make sending email almost foolproof.

    In a real-world application, you probably would make different choices about what exactly to allow users to do. The point is that by limiting the amount of input required, you can make it simpler for users to send consistent email messages, thus increasing the value of your application. This can be a lot of what differentiates Web pages that send mail from ordinary email programs, which can be more complex for users to learn.

    Listing 27.2. PersonnelMail2.cfmProviding Friendly Names Along with Email Addresses


    <!--- 
    Filename: PersonnelMail2.cfm
    Author: Nate Weiss (NMW)
    Purpose: A simple form for sending email
    --->
    &l275>
    <head>
    <title>Personnel Office Mailer</title>
    <!--- Apply simple CSS formatting to <th> cells --->
    <style>
    th {background:blue;color:white;
    font-family:sans-serif;font-size:12px;
     text-align:right;padding:5px;}
    </style>
    <!--- Function to guess email based on first/last name ---> 
    <script language="javaScript">
    function guessemail() {
    var guess;
    with (document.mailForm) {
    guess = firstName.value.substr(0,1) + lastName.value;
    toAddress.value = guess.toLowerCase();
    };
    };
    </script>
    </head>
    <!--- Put cursor in FirstName field when page loads --->
    <body <cfif not isDefined("FORM.subject")>
    onLoad="document.mailForm.firstName.focus()"
    </cfif>>
    <!--- If the user is submitting the form... --->
    <cfif isDefined("FORM.subject")>
    <cfset recipEmail = listFirst(FORM.toAddress, "@")
     & "@orangewhipstudios.com">
    <!--- We do not want ColdFusion to suppress whitespace here --->
    <cfprocessingdirective suppressWhitespace="no">
    <!--- Send the mail message, based on form input --->
    <cfmail
    subject="#FORM.subject#"
    from=""Personnel Office" <personnel@orangewhipstudios.com>"
    to=""#FORM.firstName# #FORM.lastName#" <#recipEmail#>"
    bcc="personneldirector@orangewhipstudios.com"
    >This is a message from the Personnel Office:
    #uCase(FORM.subject)#
    #FORM.messageBody#
    If you have any questions about this message, please
    write back or call us at extension 352. Thanks!</cfmail>
    </cfprocessingdirective>
    <!--- Display "success" message to user --->
    <p>The email message was sent.<br>
    By the way, you look fabulous today. 
    You should be in pictures!<br>
    <!--- Otherwise, display the form to user... ---> 
    <cfelse>
    <!--- Provide simple form for recipient and message --->
    <cfform action="#cgi.script_name#" name="mailForm" method="post">
    <table cellPadding="2" cellSpacing="2">
    <!--- Table row: Input for Recipient's Name --->
    <tr>
     <th>Recipient's Name:</th>
    <td>
    <cfinput type="text" name="firstName" required="yes" size="15"
    message="You must provide a first name."
    onChange="guessEmail()">
    <cfinput type="text" name="lastName" required="yes" size="20"
    message="You must provide a first name."
    onChange="guessEmail()">
    </td>
    </tr>
    <!--- Table row: Input for EMail Address --->
    <tr>
    <th>EMail Address:</th>
    <td>
    <cfinput type="text" name="toAddress" required="yes" size="20"
    message="You must provide the recipient's email."
    >@orangewhipstudios.com
    </td>
    </tr>
    <!--- Table row: Input for EMail Subject --->
    <tr>
    <th>Subject:</th>
    <td>
    <cfselect name="subject">
    <option>Sorry, but you have been fired.
    <option>Congratulations! You got a raise!
    <option>Just FYI, you have hit the glass ceiling.
    <option>The company dress code, Capri Pants, and you
    <option>All your Ben Forta are belong to us.
    </cfselect> 
    </td>
    </tr>
    <!--- Table row: Input for actual Message Text --->
    <tr>
    <th>Your Message:</th>
    <td>
    <cftextarea name="messageBody" cols="30" rows="5" wrap="hard"
    required="yes" message="You must provide a message body." /> 
    </td>
    </tr>
    <!--- Table row: Submit button to send message --->
    <tr>
    <td>&nbsp;</td>
    <td>
    <cfinput type="submit" name="submit" value="Send Message Now">
    </td>
    </tr>
    </table>
    </cfform>
    </cfif> 
    </body>
    </html>

    Figure 27.4 shows what an email message generated by Listing 27.2 might look like when received and viewed in a typical email client (here, Thunderbird).

    Figure 27.4. Providing a friendly name along with an email address makes for an email message that feels more personal.

    [View full size image]

    Sending Data-Driven Mail


    In the last section, you saw that <cfmail> can be thought of as an extended version of the <cfoutput> tag because ColdFusion variables and expressions are evaluated without the need for an explicit <cfoutput> within the <cfmail>. The similarity between the two tags doesn't end there. They also share attributes specific to the notion of looping over query records. This capability enables you to send data-driven email messages using nearly the same syntax and techniques that you use to output data-drive269 code.

    NOTE

    You may be thinking that a few of these additional attributes aren't really necessary. In today's ColdFusion, you usually can achieve the same results using a <cfloop> tag around a <cfmail> tag to send out multiple messages or using <cfloop> within <cfmail> to include queried information in the message itself. However, the <cfmail> tag appeared in CFML before the <cfloop> tag existed, which is one reason why these attributes exist today.

    Including Query Data in Messages

    By adding a query attribute to the <cfmail> tag, you can easily include query data in the email messages your application sends. Adding the query attribute to <cfmail> is similar to adding query to a <cfoutput> tagthe content inside the tags will repeat for each row of the query.

    Chapter 10, "Creating Data-Driven Pages," for more information about grouping query results.

    Listing 27.3 shows how the <cfmail> tag can be used with the query and group attributes to send data-driven email messages. This example creates a CFML custom tag called <cf_SendOrder Confirmation>, which takes one attribute called orderID, like this:


    <!--- Send Confirmation E-Mail, via Custom Tag --->
    <cf_SendOrderConfirmation
    orderID="3">

    The idea is for the tag to compose an order-confirmation type of email message for the person who placed the order, detailing the items they purchased and when. If you've ever bought something online, you probably received such a confirmation email immediately after placing your order. This custom tag is used in Chapter 28, "Online Commerce," after a user makes an actual purchase.

    Chapter 23, "Building Reusable Components," for information about the CustomTags folder and CFML custom tags in general.

    Listing 27.3. SendOrderConfirmation1.cfmSending a Data-Driven Email Message


    <!--- 
    Filename: SendOrderConfirmation1.cfm
    Author: Nate Weiss (NMW)
    Purpose: Sends an email message to the person who placed an order
    --->
    <!--- Tag attributes --->
    <cfparam name="ATTRIBUTES.orderID" type="numeric">
    <!--- Retrieve order information from database --->
    <cfquery datasource="ows" name="getOrder">
    SELECT 
    c.ContactID, c.FirstName, c.LastName, c.Email,
    o.OrderDate, o.ShipAddress, o.ShipCity, 
    o.ShipState, o.ShipZip, o.ShipCountry,
    oi.OrderQty, oi.ItemPrice,
    m.MerchName,
    f.MovieTitle
    FROM 
    Contacts c,
    MerchandiseOrders o,
    MerchandiseOrdersItems oi, 
    Merchandise m,
    Films f
    WHERE 
    o.OrderID = #ATTRIBUTES.orderID#
    AND c.ContactID = o.ContactID
     AND m.MerchID = oi.ItemID
    AND o.OrderID = oi.OrderID
    AND f.FilmID = m.FilmID
    ORDER BY
    m.MerchName
    </cfquery>
    <!--- Re-Query the GetOrders query to find total $ spent --->
    <!--- The DBTYPE="Query" invokes CF's "Query Of Queries" --->
    <cfquery dbtype="query" name="getTotal">
    SELECT SUM(ItemPrice * OrderQty) AS OrderTotal
    FROM GetOrder
    </cfquery>
    <!--- We do not want ColdFusion to suppress whitespace here --->
    <cfprocessingdirective suppressWhitespace="no">
    <!--- Send email to the user --->
    <!--- Because of the GROUP attribute, the inner <CFOUTPUT> --->
    <!--- block will be repeated for each item in the order --->
    <cfmail query="getOrder" group="ContactID" groupCasesensitive="no"
    startrow="1" subject="Thanks for your
     order (Order number #ATTRIBUTES.orderID#)"
    to=""#FirstName# #LastName#" <#Email#>"
    from=""Orange Whip Online Store" <orders@orangewhipstudios.com>"
    >Thank you for ordering from Orange Whip Studios.
    Here are the details of your order, which will ship shortly.
    Please save or print this email for your records.
    Order Number: #ATTRIBUTES.orderID#
    Items Ordered: #recordCount#
    Date of Order: #dateFormat(OrderDate, "dddd, mmmm d, yyyy")#
    #timeFormat(OrderDate)#
    ------------------------------------------------------
    <cfoutput>
    #currentRow#. #MerchName# 
    (in commemoration of the film "#MovieTitle#")
    Price: #LSCurrencyFormat(ItemPrice)#
    Qty: #OrderQty#
    </cfoutput>
    ------------------------------------------------------
    Order Total: #lsCurrencyFormat(getTotal.OrderTotal)#
    This order will be shipped to:
    #FirstName# #LastName#
    #ShipAddress#
    #ShipCity#
    #ShipState# #ShipZip# #ShipCountry#
    If you have any questions, please write back to us at
    orders@orangewhipstudios.com, or just reply to this email.
    </cfmail>
    </cfprocessingdirective>

    Chapter 21. However, getting the total via the query of queries feature is a quick and convenient way to obtain the total, using familiar SQL-style syntax.

    ," later in the chapter, for details.

    Now the <cfmail> tag is used to actually send the confirmation message. Because the query attribute is set to the getOrder query, the columns in that query can be freely referred to in the to attribute and the body of the email message itself. Columns specific to each item ordered are referred to within the <cfoutput> block. Columns specific to the order in general are referred to outside the <cfoutput> block, which will be repeated only once because there is only one group of records as defined by the group attribute (that is, all the query records have the same ContactID value).

    Chapter 28, "Online Commerce," after a user makes an actual purchase.

    Sending Bulk Messages

    You can easily use ColdFusion to send messages to an entire mailing list. Simply execute a query that returns the email addresses of all the people the message should be sent to, then refer to the email column of the query in the <cfmail> tag's to attribute.

    Listing 27.4 shows how easy sending a message to a mailing list is. This listing is similar to the Personnel Office Mailer templates from earlier (refer to Listings 27.1 and 27.2). It enables the user (presumably someone within Orange Whip Studios' public relations department) to type a message that will be sent to everyone on the studio's mailing list.

    Listing 27.4. SendBulkEmail.cfmSending a Message to Everyone on a Mailing List

    [View full width]


    <!--- 
    Filename: SendBulkEmail.cfm
    Author: Nate Weiss (NMW)
    Purpose: Creates form for sending email to everyone on the mailing list
    --->
    &l275>
    <head>
    <title>Mailing List</title>
    <!--- Apply simple CSS formatting to <TH> cells --->
    <style>
    th {background:blue;color:white;
    font-family:sans-serif;font-size:12px;
    text-align:right;padding:5px;}
    </style>
    </head>
    <!--- Put cursor in FirstName field when page loads --->
    <body>
    <!--- Page Title --->
    <h2>Send Message To Mailing List</h2>
    <!--- If the user is submitting the form... --->
    <cfif isDefined("FORM.subject")>
    <!--- Retrieve "mailing list" records from database --->
    <cfquery datasource="ows" name="getList">
    SELECT FirstName, LastName, EMail 
    FROM Contacts
    WHERE MailingList = 1
    </cfquery>
    <!--- Send the mail message, based on form input --->
    <cfmail query="getList" subject="#FORM.subject#"
    from=""Orange Whip Studios" <mailings@orangewhipstudios.com>"
    to=""#FirstName# #LastName#" <#EMail#>"
    bcc="personneldirector@orangewhipstudios.com"
    >#FORM.messageBody#
    ----------------------------------------------------
    We respect your privacy here at Orange Whip Studios.
    To be removed from this mailing list, reply to this
    message with the word "Remove" in the subject line.
    ----------------------------------------------------
    </cfmail>
    <!--- Display "success" message to user --->
    <p>The email message was sent.<br>
    By the way, you look fabulous today. 
    You should be in pictures!<br>
    <!--- Otherwise, display the form to user... ---> 
    <cfelse>
     <!--- Provide simple form for recipient and message --->
    <cfform action="#CGI.script_name#" name="mailForm" method="POST">
    <table cellPadding="2" cellSpacing="2">
    <!--- Table row: Input for email Subject --->
    <tr>
    <th>Subject:</th>
    <td>
    <cfinput type="text" name="subject" required="yes" size="40" 
    message="You must provide a subject for the email.">
    </td>
    </tr>
    <!--- Table row: Input for actual Message Text --->
    <tr>
    <th>Your Message:</th>
    <td>
    <cftextarea name="messageBody" cols="30" rows="5" wrap="hard"
    required="yes" message="You must provide a message body." /> 
    </td>
    </tr>
    <!--- Table row: Submit button to send message --->
    <tr>
    <td>&nbsp;</td>
    <td>
    <cfinput type="submit" name="submit" 
    value="Send Message Now" onClick="return confirm
    ('Are you sure? This message will be sent to 
    everyone on the mailing list. This is your
     last chance to cancel the bulk mailing.')">
    </td>
    </tr>
    </table>
    </cfform>
    </cfif> 
    </body>
    </html>

    Like Listing 27.11in the "Creating Automated POP Agents" section of this chapterdemonstrates how ColdFusion can respond to these remove requests.

    Sendin262-Formatted Mail


    As noted in , which enables you to use ordinary HTML tags to add formatting, images, and other media elements to your mail messages.

    The following rules apply:

    • The recipient's email client program must b260 enabled. Most modern email clients, such as Outlook Express or Mozilla Thunderbird, know how to display the contents of email messages a274. However, if the message is read in a program that isn'275 enabled, the user will see the message literally, including the actua267 tags.

    • The mail message should be a well-forme259 document, including . opening and closing &l275>, <head>, and <body> tags.

    • All references to external URLs must be fully qualified, absolute URLs, including the http:// or https://. In particular, this includes the HRef attribute for links and the src attribute for images.


    The version of the <cf_SendOrderConfirmation> tag in attribute. If the tag is called with u274="Yes", a269-formatted version of the confirmation email is sent, including small pictures of each item that was ordered (see is No or is omitted, the email is sent as plain text (as in the previous version). note

    Figure 27.5. As long as the recipient's email program support274, your messages can include formatting, images, and so on.

    Listing 27.5. SendOrderConfirmation2.cfmUsin262 Tags to Format a Mail Message


    <!--- 
    Filename: SendOrderConfirmation2.cfm
    Author: Nate Weiss (NMW)
    Purpose: Sends an email message to the person who placed an order
    --->
    <!--- Tag attributes --->
    <cfparam name="ATTRIBUTES.orderID" type="numeric">
    <cfparam name="ATTRIBUTES.u274" type="boolean" default="yes">
    <!--- Local variables --->
    <cfset imgSrcPath = "http://#CGI.HTTP_HOST#/ows/images">
    <!--- Retrieve order information from database --->
    <cfquery datasource="ows" name="getOrder">
    SELECT 
    c.ContactID, c.FirstName, c.LastName, c.Email,
     o.OrderDate, o.ShipAddress, o.ShipCity, 
    o.ShipState, o.ShipZip, o.ShipCountry,
    oi.OrderQty, oi.ItemPrice,
    m.MerchName, m.ImageNameSmall,
    f.MovieTitle
    FROM 
    Contacts c,
    MerchandiseOrders o,
    MerchandiseOrdersItems oi, 
    Merchandise m,
    Films f
    WHERE 
    o.OrderID = #ATTRIBUTES.OrderID#
    AND c.ContactID = o.ContactID
    AND m.MerchID = oi.ItemID
    AND o.OrderID = oi.OrderID
    AND f.FilmID = m.FilmID
    ORDER BY
    m.MerchName
    </cfquery>
    <!--- Display an error message if query returned no records --->
    <cfif getOrder.recordCount eq 0>
    <cfthrow message="Failed to obtain order information."
    detail="Either the Order ID was incorrect,
     or order has no detail records.">
    <!--- Display an error message if email blank or not valid ---> 
    <cfelseif (getOrder.Email doesn't contain "@") 
    OR (getOrder.Email doesn't contain ".")>
    <cfthrow message="Failed to obtain order information."
    detail="Email addresses need to have an @
     sign and at least one 'dot'.">
    </cfif>
    <!--- Query the GetOrders query to find total $$ --->
    <cfquery dbtype="query" name="getTotal">
    SELECT SUM(ItemPrice * OrderQty) AS OrderTotal
    FROM GetOrder
    </cfquery>
    <!--- *** If we are sendin262-Formatted Email *** --->
    <cfif ATTRIBUTES.u274>
    <!--- Send Email to the user --->
    <!--- Because of the GROUP attribute, 
    the inner <CFOUTPUT> --->
    <!--- block will be repeated for each 
    item in the order --->
    <cfmail query="getOrder" group="ContactID"
     groupCasesensitive="No"
    subject="Thanks for your order (Order number 
    #ATTRIBUTES.orderID#)"
    to=""#FirstName# #LastName#" <#Email#>"
    from=""Orange Whip Online Store" <orders@
    orangewhipstudios.com>"
    type="HTML">
    &l275>
    <head>
    <style type="text/css">
    body {font-family:sans-serif;font-size:12px;color:navy}
     td {font-size:12px}
    th {font-size:12px;color:white;
    background:navy;text-align:left}
    </style>
    </head>
    <body>
    <h2>Thank you for your Order</h2>
    <p><b>Thank you for ordering from 
    <a >Orange Whip Studios</a>.</b><br>
    Here are the details of your order, which will ship shortly.
    Please save or print this email for your records.<br>
    <p>
    <strong>Order Number:</strong> #ATTRIBUTES.orderID#<br>
    <strong>Items Ordered:</strong> #recordCount#<br>
    <strong>Date of Order:</strong> 
    #dateFormat(OrderDate, "dddd, mmmm d, yyyy")#
    #timeFormat(OrderDate)#<br>
    <table>
    <cfoutput>
    <tr valign="top">
    <th colspan="2">
    #MerchName#
    </th>
    </tr>
    <tr> 
    <td>
    <!--- If there is an image available... --->
    <cfif ImageNameSmall neq ">
    <img src="#imgSrcPath#/#ImageNameSmall#"
      width="50" height="50" border="0">
    </cfif> 
    </td>
    <td>
    <em>(in commemoration of the film "#MovieTitle#")</em><br>
    <strong>Price:</strong> #lsCurrencyFormat(ItemPrice)#<br>
    <strong>Qty:</strong> #OrderQty#<br>&nbsp;<br>
    </td>
    </tr> 
    </cfoutput>
    </table>
    <p>Order Total: #lsCurrencyFormat(getTotal.OrderTotal)#<br>
    <p><strong>This order will be shipped to:</strong><br>
    #FirstName# #LastName#<br>
    #ShipAddress#<br>
    #ShipCity#<br>
    #ShipState# #ShipZip# #ShipCountry#<br>
     <p>If you have any questions, please write back to us at
    <a href="orders@orangewhipstudios.com">orders@orangewhipstudios.com</a>, 
    or just reply to this email.<br>
    </body>
    </html>
    </cfmail>
    <!--- *** If we are NOT sendin262-Formatted Email *** --->
    <cfelse>
    <!--- We do not want ColdFusion to suppress whitespace here --->
    <cfprocessingdirective suppressWhitespace="no">
    <!--- Send email to the user --->
    <!--- Because of the GROUP attribute, the inner <CFOUTPUT> --->
    <!--- block will be repeated for each item in the order --->
    <cfmail query="getOrder" group="ContactID" groupCasesensitive="No"
    subject="Thanks for your order (Order number #ATTRIBUTES.OrderID#)"
    to=""#FirstName# #LastName#" <#Email#>"
    from=""Orange Whip Online Store" <orders@orangewhipstudios.com>"
    >Thank you for ordering from Orange Whip Studios.
    Here are the details of your order, which will ship shortly.
    Please save or print this email for your records.
    Order Number: #ATTRIBUTES.orderID#
    Items Ordered: #recordCount#
    Date of Order: #dateFormat(OrderDate, "dddd, mmmm d, yyyy")#
    #timeFormat(OrderDate)#
    ------------------------------------------------------
    <cfoutput>
    #currentRow#. #MerchName# 
    (in commemoration of the film "#MovieTitle#")
    Price: #lsCurrencyFormat(ItemPrice)#
    Qty: #OrderQty#
    </cfoutput>
    ------------------------------------------------------
    Order Total: #lsCurrencyFormat(getTotal.OrderTotal)#
    This order will be shipped to:
    #FirstName# #LastName#
    #ShipAddress#
    #ShipCity#
    #ShipState# #ShipZip# #ShipCountry#
    If you have any questions, please write back to us at
    orders@orangewhipstudios.com, or just reply to this email.
    </cfmail>
    </cfprocessingdirective>
    </cfif>

    . If so, <cfmail> is used with type="HTML" to send a269-formatted message. If not, a separate <cfmail> tag is used to send a plain-text message. Note that the <cfprocessingdirective> tag is needed only around the plain-text version of the message becaus260 isn't sensitive to white space.

    As already noted, a fully qualified URL must be provided for images to be correctly displayed in email messages. To make this easier, a variable called imgSrcPath is defined at the top of the template, which will always hold the fully qualified URL path to the ows/images folder. This variable can then be used in the src attribute of any <img> tags within the message. For instance, assuming that you are visiting a copy of ColdFusion server on your local machine, this variable will evaluate to something such as http://localhost/ows/images/.

    Appendix D, "Special ColdFusion Variables and Result Codes."

    In addition, type="HTML" only if you know the recipient is using a269-enabled email client program.

    Adding Custom Mail Headers


    All SMTP email messages contain a number of mail headers, which give Internet mail servers the information necessary to route the message to its destination. Mail headers also provide information used by the email client program to show the message to the user, such as the message date and the sender's email address.

    ColdFusion allows you to add your own mail headers to mail messages, using the <cfmailparam> tag.

    TIP

    You can see what these mail headers look like by using an ordinary email client program. For instance, in Outlook Express, highlight a message in your Inbox, select Properties from the File menu, and then click the Details tab.

    Introducing the <cfmailparam> Tag

    ColdFusion provides a tag called <cfmailparam> that can be used to add custom headers to your mail messages. It also can be used to add attachments to your messages, which is discussed in the next section. The <cfmailparam> tag is allowed only between opening and closing <cfmail> tags. tex275).

    contentID

    Specifies an identifier for the attached file. This is used to identify the file that an img or other tag in the email uses.

    disposition

    This attribute describes how the file should be attached to the email. There are two possible values, attachment and inline. The default, attachment, means the file is added as attachment. If you specify inline, the file will be included in the message.

    Adding Attachments


    As noted in Table 27.3, you can also use the <cfmailparam> tag to add a file attachment to a mail message. Simply place a <cfmailparam> tag between the opening and closing <cfmail> tags, specifying the attachment's filename with the file attribute. The filename must be provided as a fully qualified file-system path, including the drive letter and volume name. It can't be expressed as a relative path or URL.

    NOTE

    The filename you provide for a file must point to a location on the ColdFusion server's drives (or a location on the local network). It can't refer to a location on the browser machine. ColdFusion has no way to grab a document from the browser's drive. If you want a user to be able to attach a file to a <cfmail> email, you first must have them upload the file to the server. See Chapter 34, "Interacting with the Operating System," for details about file uploads.

    TIP

    The attachment doesn't have to be in your Web server's document root. In fact, you might want to ensure that it's not, if you want people to be able to access it only via email, rather than via the Web.

    To add a Word document called BusinessPlan.doc as an attachment, you might include the following <cfmailparam> tag between your opening and closing <cfmail> tags:


    <!-- Attach business plan document to message --->
    <cfmailparam
    file="c:\OwsMailAttachments\BusinessPlan.doc">

    TIP

    To add multiple attachments to a message, simply provide multiple <cfmailparam> tags, each specifying one file.

    NOTE

    As noted in Table 27.1, you also can use the older mimeattach attribute of the <cfmail> tag to add an attachment, instead of coding a separate <cfmailparam> tag. However, it's recommended that you use <cfmailparam> instead because it's more flexible (it allows you to add more than one attachment to a single message).

    Overriding the Default Mail Server Settings


    Earlier in this chapter, you learned about the settings on the Mail/Mail Logging page of the ColdFusion Administrator (refer to Figure 27.1). These settings tell ColdFusion which mail server to communicate with to send the messages that your templates generate. In most situations, you can simply provide these settings once, in the ColdFusion Administrator, and forget about them. ColdFusion will use the settings to send all messages.

    However, you might encounter situations in which you want to specify the mail server settings within individual <cfmail> tags. For instance, your company might have two mail servers set up, one for bulk messages and another for ordinary messages. Or you might not have access to the ColdFusion Administrator for some reason, perhaps because your application is sitting on a shared ColdFusion server at an Internet service provider (ISP).

    To specify the mail server for a particular <cfmail> tag, add the server attribute, as explained in Table 27.4. You also can provide the port and timeout attributes to completely override all mail server settings from the ColdFusion Administrator.

    NOTE

    If you need to provide these attributes for your <cfmail> tags, consider setting a variable called APPLICATION.mailServer in your Application.cfc file and then specifying server="#APPLICATION.mailServer#" for each <cfmail> tag.

    • / 281