Generating Graphs - 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

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





  • Generating Graphs


    We'll start with an overview of the charting features included in ColdFusion. ColdFusion comes with a series of tags that will allow you to:

    • Create many different types of graphs, including pie charts, bar graphs, line graphs, and scatter charts.

    • Format your graphs options that control fonts, colors, labels, and more.

    • Display the graphs on any ColdFusion page as JPEG images, PNG images, or interactive Flash charts.

    • Allow users to drill down on data shown in your charts. For instance, you could have people click the wedges in a pie chart, revealing the data represented in that wedge.

    • Combine several different charts, displaying them together on the page. For instance, you might create a scatter chart that shows individual purchases over time, and then add a line chart on top of it that shows users' average spending.

    • Save the charts to the server's drive for later use.

    Building Simple Charts


    Now that you have an idea of what you can do with ColdFusion's charting features, let's get started with some basic examples. Most of the time, you will create charts with just two CFML tags, <cfchart> and <cfchartseries>.

    NOTE

    In ColdFusion 5, you created graphs with <cfgraph>, whereas you now create them with <cfchart>. If you already use <cfgraph> in your applications, your <cfgraph> code should continue to work in ColdFusion MX or later, although the graphs may look slightly different. In any case, you should start using <cfchart> as soon as possible, since <cfgraph> has been retired and may not work in future versions of the product.

    Introducing <cfchart> and <cfchartseries>

    To display a chart on a ColdFusion page, you use the <cfchart> tag. This tag controls the height, width, and formatting of your chart, but it doesn't display anything. Within the <cfchart> tag, you use the <cfchartseries> tag, which determines the type of chart (like bar or pie) and the actual data to show on the chart.

    NOTE

    Actually, you will occasionally want to place multiple <cfchartseries> tags within a <cfchart> tag. See the "Combining Multiple Chart Series" section, later in this chapter.

    Table 16.1 shows the most important attributes for the <cfchart> tag, and Table 16.2 shows the most important attributes for <cfchartseries>.

    Table 16.1. Basic <cfchart> Tag Syntax

    ATTRIBUTE

    DESCRIPTION

    chartwidth

    Optional. The width of the chart, in pixels. The default is 320.

    chartheight

    Optional. The height of the chart, in pixels. The default is 240.

    xaxistitle

    Optional. The text to display along the chart's x-axis.

    yaxistitle

    Optional. The text to display along the chart's y-axis.

    url

    Optional. The URL of a page to send the user to when various sections of the chart are clicked. You can pass variables in the URL so you know what part of the chart the user clicked. See "Drilling Down from Charts," later in this chapter.

    format

    Optional. The type of image format in which the chart should be created. The valid choices are flash (the default), jpg, and png.

    seriesplacement

    Optional. For charts that have more than one data series, you can use this attributecluster, stacked, percent, or defaultto control how the series are combined visually. Use cluster if the data series represent related pieces of information that should be presented next to one another, rather than added together visually. Use stacked or percent if the data series represent values that should be added up to a single whole value for each item you're plotting. See "Combining Multiple Chart Series," later in this chapter.

    Table 16.2. Basic <cfchartseries> Syntax

    ATTRIBUTE

    DESCRIPTION

    type

    Required. The type of chart to create. Usually, you will set this to either bar, line, area, or pie. Other chart types are cone, curve, cylinder, scatter, step, and pyramid. The ColdFusion documentation includes some nice pictures of these more unusual types of graphs.

    query

    Optional. The name of a query that contains data to chart. If you don't provide a query attribute, you will need to provide <cfchartdata> tags to tell ColdFusion the data to display in the chart.

    valuecolumn

    Required if a query is provided. The name of the column that contains the actual value (the number to represent graphically) for each data point on the chart.

    itemcolumn

    Required if a query is provided. The name of the column that contains labels for each data point on the chart.

    NOTE

    Because these tags have a large number of attributes (more than 40 in all), we are introducing only the most important attributes in this table. Others are introduced later in this chapter.

    NOTE

    In this chapter, you will often see the term data point. Data points are the actual pieces of data that are displayed on a chart. If you're creating a pie chart, the data points are the slices of the pie. In a bar chart, the data points are the bars. In a line or scatter chart, the data points are the individual points that have been plotted on the graph.

    NOTE

    You don't have to have a query object to create a chart. You can also create data points manually using the <cfchartdata> tag. See "Plotting Individual Points with <cfchartdata>," near the end of this chapter.

    Creating Your First Chart

    Listing 16.1 shows how to use <cfchart> and <cfchartseries> to create a simple bar chart. The resulting chart is shown in Figure 16.1. As you can see, it doesn't take much code to produce a reasonably helpful bar chart. Anyone can glance at this chart and instantly understand which films cost more than the average, and by how much.

    Listing 16.1. Chart1.cfmCreating a Simple Bar Chart from Query Data


    <!---
    Name:        Chart1.cfm
    Author:      Nate Weiss & Ben Forta
    Description: Basic bar chart
    Created:     01/10/05
    --->
    <!--- Get information from the database --->
    <cfinvoke component="ChartData"
    method="GetBudgetData"
    returnvariable="ChartQuery"
    maxrows="10">
    &l275>
    <head>
    <title>Chart: Film Budgets</title>
    </head>
    <body>
    <h2>Chart: Film Budgets</h2>
    <!--- This defines the size and appearance of the chart --->
    <cfchart chartwidth="750"
    chartheight="500"
    yaxistitle="Budget">
    <!--- within the chart --->
    <cfchartseries type="bar"
    query="chartquery"
    valuecolumn="amountbudgeted"
    itemcolumn="movietitle">
    </cfchart>
    </body>
    </html>

    Figure 16.1. It's easy to create simple charts with <cfchart> and <cfchartdata>.

    [View full size image]

    First, an ordinary <cfinvoke> tag is used to select invoke a CFC method that returns film and budget information from the database. Then a <cfchart> tag is used to establish the size of the chart, and to specify that the word Budget appear along the y-axis (that is, at the bottom of the chart). Finally, within the <cfchart> block, a <cfchartseries> tag is used to create a bar chart. ColdFusion is instructed to chart the information in the ChartQuery record set, plotting the data in the AmountBudgeted column and using the MovieTitle column to provide a label for each piece of information.

    NOTE


    For this example and the next few listings, we are using maxrows="10" (passed to the <cfquery> tag) to limit the number of films displayed in the chart to ten. This keeps the pictures of the graphs simple while you're learning how to use the charting tags. Just eliminate the maxrows attribute to see all films displayed in the chart.

    The charts created here are Macromedia Flash charts, as that is the default chart format generated by ColdFusion. Charts may also be generated as static images (in JPG and PNG formats), although static charts aren't as functional or feature rich.

    TIP

    Data is presented in the chart in the order in which it's retrieved from the database. To change the order, just sort the query differently using the appropriate SQL ORDER BY clause.

    Changing the Chart Type

    The first chart we created was a bar chart. It's easy to change your code so that it displays a different kind of graph. Just change the type attribute of the <cfchartseries> tag. Figure 16.2 shows the pie chart created by the Chart2.cfm, the code for which is shown in Listing 16.2. The differences are that type="Pie: is used in the <cfchartseries> tag.

    Listing 16.2. Chart2.cfmCreating a Simple Pie Chart from Query Data


    <!---
    Name:        Chart2.cfm
    Author:      Nate Weiss & Ben Forta
    Description: Basic pie chart
    Created:     01/10/05
    --->
    <!--- Get information from the database --->
    <cfinvoke component="ChartData"
    method="GetBudgetData"
    returnvariable="ChartQuery"
    maxrows="10">
    &l275>
    <head>
    <title>Chart: Film Budgets</title>
    </head>
    <body>
    <h2>Chart: Film Budgets</h2>
    <!--- This defines the size and appearance of the chart --->
    <cfchart chartwidth="750"
    chartheight="500"
    yaxistitle="Budget">
     <!--- within the chart --->
    <cfchartseries type="pie"
    query="chartquery"
    valuecolumn="amountbudgeted"
    itemcolumn="movietitle">
    </cfchart>
    </body>
    </html>

    Figure 16.2. Changing the chart type is simply a matter of changing the type attribute.

    [View full size image]

    Formatting Your Charts


    Now that you understand the basics of how to produce simple charts, let's learn some formatting options to make your charts look better and more closely meet your users' needs. In general, your goal should be to make the charts as easy on the eyes as possibleit helps people concentrate on the data.

    Adding Depth with 3D Charts

    One of the easiest ways to make a basic chart look more sophisticated is to give it a 3D look. Table 16.3 shows the <cfchart> options available for adding a 3D effect to your charts. Get out the red-and-blue glasses!

    Table 16.3. <cfchart> Options for a 3D Effect

    ATTRIBUTE

    DESCRIPTION

    show3d

    Whether to show the chart with a 3D effect. The default is No.

    xoffset

    The amount that the chart should be rotated on the x-axis. In other words, this controls to what extent the chart appears to be viewed from the side. You can use a value anywhere from -1 to 1, but in general you will want to experiment with low, positive numbers (between .01 and .3) for best results. A value of 0 means no 3D effect horizontally. The default is .1.

    yoffset

    Similarly, the amount that the chart should be turned around its y-axis. This controls the extent the chart seems to be viewed from the top. Again, you will probably want to experiment with low, positive numbers (between .01 and .3) for best results. A value of 0 means no 3D effect vertically. The default is .1.

    NOTE

    Whether the 3D effect makes a chart easier to read depends on the situation. It tends to look nice in simple creations, especially bar charts with relatively few data points. Once a chart displays many data points, the 3D effect becomes distracting.

    NOTE

    The xoffset and yoffset attributes have no discernible effect on pie charts. You can make a pie chart display with a 3D appearance using show3d="Yes", but you can't control the offsets.

    Listing 16.3 shows how to produce a 3D graph by adding these attributes to the code from Listing 16.1. The xoffset and yoffset have been tweaked to make the bars look like they are being looked at from the top a bit more than from the side. The results are shown in Figure 16.3.

    Listing 16.3. Chart3.cfmAdding a 3D Appearance


    <!---
    Name:        Chart3.cfm
    Author:      Nate Weiss & Ben Forta
    Description: 3D bar chart
    Created:     01/10/05
    --->
    <!--- Get information from the database --->
    <cfinvoke component="ChartData"
    method="GetBudgetData"
    returnvariable="ChartQuery"
    maxrows="10">
    &l275>
    <head>
    <title>Chart: Film Budgets</title>
    </head>
    <body>
    <h2>Chart: Film Budgets</h2>
    <!--- This defines the size and appearance of the chart --->
    <cfchart chartwidth="750"
    chartheight="500"
    yaxistitle="Budget"
    show3d="yes"
             xoffset=".03"
    yoffset=".06">
    <!--- within the chart --->
    <cfchartseries type="bar"
    query="chartquery"
    valuecolumn="amountbudgeted"
    itemcolumn="movietitle">
    </cfchart>
    </body>
    </html>

    Figure 16.3. Add 3D chart effects to better display chart details.

    [View full size image]

    Controlling Fonts and Colors

    ColdFusion provides a number of formatting attributes that you can use to control fonts, colors, and borders. Some of the attributes are applied at the <cfchart> level and others at the <cfchartseries> level, as listed in Figure 25.1). The tip message includes the label and value of the data point, as well as the series label, if given (see Table 25.5). If you want the tip to be shown only when the user clicks a data point, you can use tipstyle="mouseDown", but this works only if format="flash". If you don't want any tip to be shown at all, use tipstyle="off".

    pieslicestyle

    Relevant only for pie charts. If sliced (the default) is used, the pie is shown with its slices separated by white space (this effect is sometimes called exploded). If solid is used, the pie is shown with its slices together in a circle, the way you normally think of a pie chart. Unfortunately, there is no way to explode just one slice at a time, which is a common way to present pie charts. In general, you will probably want to use pieslicestyle="solid".

    Table 16.5. <cfchartseries> Formatting Options

    ATTRIBUTE

    DESCRIPTION

    seriescolor

    A color to use for the main element of the data series.

    serieslabel

    A label or title for the data series.

    paintstyle

    A style to use when filling in solid areas on the chart for this series. The default is plain, which uses solid colors. You can also use raise, which gives each area a raised, button-like appearance; shade, which shades each area with a gradient fill; or light, which is a lighter version of shade.

    colorlist

    Relevant for pie charts only. A comma-separated list of colors to use for the slices of the pie. The first slice will have the first color in the list, the second slice will have the second color, and so on.

    markerstyle

    Relevant only for line, curve, and scatter charts. The look of the marker that appears at each data point. Can be set to rectangle (the default), triangle, diamond, circle, letter, mcross, snow, or rcross.

    NOTE

    All of the attributes that control color can accept Web-style hexadecimal color values, such as FFFFFF for white or 0000FF for blue. In addition, any of the following named colors can be used: Aqua, Black, Blue, Fuchsia, Gray, Green, Lime, Maroon, Navy, Olive, Purple, Red, Silver, Teal, White, and Yellow.

    Listing 16.4 and Figure 16.4 (below) show how some of these formatting attributes can be combined to improve the appearance of the bar charts you have seen so far.

    Figure 16.4. The ColdFusion charting tags provide extensive control over chart formatting.

    [View full size image]

    Controlling Grid Lines and Axis Labels

    One of the most important aspects of nearly any chart are the numbers and labels that surround the actual graphic on the x- and y-axes. The graphic itself is what lends the chart its ability to convey a message visually, but it's the numbers surrounding the graphic that give it a context. ColdFusion provides you with a number of options for controlling the scale of each axis (that is, the distance between the highest and lowest values that could be plotted on the chart), and for controlling how many different numbers are actually displayed along the axes.

    Figure 25.1 (the horizontal lines) and Figure 25.2 (the vertical lines). The default is Yes.

    showxgridlines

    Whether to display grid lines for the x-axis. The default is No.

    sortxaxis

    Sorts the data in the x-axis (that is, the labels) alphabetically. In general, I recommend that you use order by to reorder the records within a normal <cfquery> tag, before your code gets to the <cfchart> tag; that approach will be much more flexible (see the "Sorting the Data First" section earlier in this chapter).

    labelformat

    The format for the labels along the y-axis (in our examples so far, the labels that show the increasing amounts of money). You can set this to number (the default), currency (which on English-language systems adds a dollar sign [$]), percent (which multiplies by 100 and adds a percent sign [%]), or date (appropriate only if the data you're plotting are dates).

    NOTE


    You can't adjust the scale in such a way that it would obscure or chop off any of the actual data being shown in the chart. If your scalefrom value is higher than the lowest data point on the graph, ColdFusion will use the data point's value instead. For instance, if the lowest budget being plotted in one of the budget chart examples is $34,000 and you provide scalefrom="50000", ColdFusion will start the scale at $34,000. The inverse is also true; if you provide a scaleto value that is lower than the highest data point, that point's value will be used instead.

    Listing 16.4 shows how formatting, axis, and grid line options can be added to a chart to give it more appeal, and the axis labels have been formatted as currency. (Figure 16.4). You can't see the colors in this book, but different shades of light blue have been used for the data background and the overall chart background. The text is in a dark navy type, and the bars of the chart themselves have a green gradient. Also note that the number of grid lines (that is, the number of numbered tick marks along the horizontal axis) has been set to 6 with the gridlines attribute. This means that there will be five tick marks (in addition to the first one), evenly distributed across the range.

    Listing 16.4. Chart4.cfmAdd Formatting, Grid Line, and Axis Options


    <!---
    Name:        Chart4.cfm
    Author:      Nate Weiss & Ben Forta
    Description: Extensive chart formatting
    Created:     01/10/05
    --->
    <!--- Get information from the database --->
    <cfinvoke component="ChartData"
    method="GetBudgetData"
    returnvariable="ChartQuery"
    maxrows="10">
    &l275>
    <head>
    <title>Chart: Film Budgets</title>
    </head>
    <body>
    <h2>Chart: Film Budgets</h2>
    <!--- This defines the size and appearance of the chart --->
    <cfchart chartwidth="750"
    chartheight="450"
    yaxistitle="Budget"
    <!--- 3D appearance --->
    show3d="yes"
    xoffset=".04"
    yoffset=".04"
    <!--- Fonts and colors --->
    showborder="yes"
    foregroundcolor="003366"
    backgroundcolor="99dddd"
    databackgroundcolor="66bbbb"
    tipbgcolor="ffff99"
    fontsize="11"
    fontbold="yes"
             fontitalic="yes"
    <!--- gridlines and axis labels --->
    scalefrom="0"
    scaleto="1500000"
    gridlines="6"
    showygridlines="yes"
    labelformat="currency">
    <!--- within the chart --->
    <cfchartseries type="bar"
    seriescolor="green"
    serieslabel="Budget Details:"
    query="chartquery"
    valuecolumn="amountbudgeted"
    itemcolumn="movietitle"
    paintstyle="light">
    </cfchart>
    </body>
    </html>

    NOTE

    When providing hexadecimal color values, the traditional number sign (#) is optional. If you provide it, though, you must escape the # by doubling it, so ColdFusion doesn't think you're trying to reference a variable. In other words, you could provide backgroundcolor="99DDDD" or backgroundcolor="##99DDDD" as you prefer, but not backgroundcolor= "#99DDDD".

    Using Multiple Data Series


    Now that you've been introduced to the basic principles involved in creating and formatting charts, we'd like to explain some of the more advanced aspects of ColdFusion charting support. In the next section, you will learn how to combine several chart types into a single graph. Then you will learn how to create charts that users can click, so they can drill down on information presented in the graph.

    Combining Multiple Chart Series

    So far, all the charts you've seen have contained only one <cfchartseries> tag. This makes sense, considering that the charts have presented only one set of information at a time. But it's also possible to create charts that represent more than one set of information, simply by adding additional <cfchartseries> tags within the <cfchart> block. The additional <cfchartseries> tags can each display different columns from the same query, or they can display information from different queries or data sources altogether.

    The bar chart examples so far all show the budget for each film. It might be helpful to show not only the budget for each film but also the actual expenses to date, so that a glance at the chart will reveal which films are over budget and by how much.

    Figure 16.5 shows just such a chart. There are now two bars for each film, clustered in pairs. One bar shows the budget for the film and the other shows the actual expenses for the film to date, as recorded in the Expenses table. Listing 16.5 shows the code used to produce this chart.

    Listing 16.5. Chart5.cfmPlotting Two Related Sets of Data


    <!---
    Name:        Chart5.cfm
    Author:      Nate Weiss & Ben Forta
    Description: Using multiple data series
    Created:     01/10/05
    --->
    <!--- Get information from the database --->
    <cfinvoke component="ChartData"
    method="GetExpenses"
    returnvariable="ChartQuery"
    maxrows="5">
    &l275>
    <head>
    <title>Chart: Film Budgets</title>
    </head>
    <body>
    <h2>Chart: Film Budgets</h2>
    <!--- This defines the size and appearance of the chart --->
    <cfchart chartwidth="750"
    chartheight="450"
    yaxistitle="Budget"
             seriesplacement="cluster"
    <!--- 3D appearance --->
    show3d="yes"
    xoffset=".01"
    yoffset=".03"
    <!--- Fonts and colors --->
    showborder="yes"
    databackgroundcolor="dddddd"
    fontbold="yes"
    fontitalic="yes"
    <!--- gridlines and axis labels --->
    scaleto="800000"
    gridlines="5"
    showxgridlines="yes"
    showygridlines="no"
    labelformat="currency">
    <!--- Budget chart --->
    <cfchartseries type="horizontalbar"
    seriescolor="99ff99"
    serieslabel="Amount Budgeted:"
    query="chartquery"
    valuecolumn="amountbudgeted"
    itemcolumn="movietitle">
    <!--- Expenses chart --->
    <cfchartseries type="horizontalbar"
    seriescolor="ff4444"
    serieslabel="Actual Expenses:"
    query="chartquery"
    valuecolumn="expensetotal"
    itemcolumn="movietitle"
    paintstyle="light">
    </cfchart>
    </body>
    </html>

    Figure 16.5. Multiple data series can be used in a single chart.

    [View full size image]

    Nearly any time you have multiple columns of information in the same query, you can display them using code similar to that used in this listing. The unspoken assumption is that the data in the first row of the AmountBudgeted and ExpenseTotal columns are related to the same real-world item. In this case, that real-world item is the first film.

    Combining Series of Different Types

    You're free to use different type values (line, bar, area, scatter, and so on) for each <cfchartseries> tag in the same chart. For instance, you might want to modify Listing 16.5 so that one series uses area and the other line. Line graphs are generally used to represent a single concept that changes over time, rather than blocks of individual data like film budgets, but in this particular case the result is rather effective. You're invited to experiment with different combinations of bar charts to see the various possibilities for yourself.

    NOTE


    You can't combine pie charts with other types of charts. Any <cfchartseries> tags that try to mix pie charts with other types will be ignored.

    You can also experiment with the seriesplacement attribute to tell ColdFusion to change the way your chart series are combined. For instance, you can use seriesplacement="stacked" to have the bars shown stacked (as seen in Figure 16.6).

    Figure 16.6. Multiple data series can be used in a single chart.

    [View full size image]

    Drilling Down from Charts


    The <cfchart> tag supports a URL attribute that you can use to create clickable charts, where the user can click the various data points in the chart to link to a different page. Of course, the page you bring users to when they click the chart is up to you. Generally, the idea is to allow users to zoom in or drill down on the data point they clicked.

    For instance, if a chart displays information about film expenses, as in the examples above, then clicking one of the expense bars might display a269 table that lists the actual expense records. Or it might bring up a second chart, this one a pie chart that shows the distribution of the individual expenses for that particular film. In either case, your clickable chart can be thought of as a navigation element, not unlike a toolbar or a set o261 links. It's a way for users to explore your data visually.

    Creating a Clickable Chart

    To create a clickable chart, simply add a URL attribute to the <cfchart> tag. When the user clicks one of the data points in the chart (the slices of a pie chart, the bars in a bar chart, the points in a line graph, and so on), they will be sent to the URL you specify. So, if you want the browser to navigate to a ColdFusion page called FilmExpenseDetail.cfm when a chart is clicked, you would use url="FilmExpenseDetail.cfm". You can use any type of relative or absolute URL that is acceptable to use in a norma267 link.

    For the detail page to be dynamic, however, it will need to know which data point the user clicked. To make this possible, ColdFusion lets you pass the actual data that the user is clicking as URL variables. To do so, include any of the special values shown in Table 16.7 in the url attribute. ColdFusion will create a dynamic URL for each data point by replacing these special values with the actual data for that data point.

    Table 16.7. Special Values for Passing in <cfchart> URLs

    VARIABLE

    DESCRIPTION

    $value$

    The value of the selected row (that is, the value in the valuecolumn attribute of the <cfchartseries> tag for the data point that was clicked). This is typically the value that you're most interested in passing in the URL.

    $itemlabel$

    The label of the selected row (that is, the value in the itemcolumn for the data point that was clicked).

    $serieslabel$

    The series label (that is, the value of the serieslabel attribute of the <cfchartseries> tag). It's usually only necessary to include this value in the URL if you have multiple <cfchartseries> tags in your chart; this value becomes the way that the target page knows which series the user clicked.

    For instance, consider the following <cfchartseries> tag:


    <cfchartseries type="pie"
    query="ChartQuery"
    valuecolumn="AmountBudgeted"
    itemcolumn="MovieTitle"
    url="FilmExpenseDetail.cfm?MovieTitle=$itemlabel$">

    When the user clicks the slices in this pie chart, the title of the film they clicked on will be passed to the FilmExpenseDetail.cfm page as a URL parameter named MovieTitle. Within FilmExpenseDetail. cfm, the value will be available as URL.MovieTitle, which can be used just like any other variable in the URL scope.

    Listing 16.6 shows how the URL attribute can be used to create a clickable chart. This listing creates a pie chart that breaks down the overall budget for Orange Whip Studios by film. When users click a slice of the pie, they are presented with the detail page shown in Figure 16.7. You'll see the code for the detail page in a moment.

    Listing 16.6. Chart6.cfmCreating Chart with Drill-Down Functionality


    <!---
    Name:        Chart6.cfm
    Author:      Nate Weiss & Ben Forta
    Description: Display a pie chart with drill-down support
    Created:     01/10/05
    --->
    <!--- Get information from the database --->
    <cfinvoke component="ChartData"
    method="GetExpenses"
    returnvariable="ChartQuery"
    maxrows="10">
    &l275>
    <head>
    <title>Chart: Film Budgets</title>
    </head>
    <body>
    <h2>Chart: Film Budgets</h2>
    <!--- This defines the size and appearance of the chart --->
    <cfchart chartwidth="550"
             chartheight="300"
    pieslicestyle="solid"
    show3d="yes"
    yoffset=".9"
    url="FilmExpenseDetail.cfm?MovieTitle=$ITEMLABEL$">
    <!--- Within the chart --->
    <cfchartseries type="pie"
    query="chartquery"
    valuecolumn="amountbudgeted"
    itemcolumn="movietitle">
    </cfchart>
    </body>
    </html>

    Figure 16.7. Graph details can be displayed using chart drill-down functions.

    [View full size image]

    Creating the Detail Page

    Creating the detail page shown in There is one bit of unpleasantness to deal with, though. Unfortunately, <cfchart> doesn't provide a straightforward way to pass a unique identifier in URLs generated by <cfchart>. The only things you can pass are the actual label and value of the data point displayed on the graph (with the special $ITEMLABEL$ and $VALUE$ values, respectively).

    So, for the example at hand (see Listing 16.7), the only pieces of information that can be passed to the FilmExpenseDetail.cfm page are the film's title and budget, since those are the only values that the chart is aware of. Ordinarily, it would be far preferable to pass the FilmID in the URL, thereby eliminating any problems that would come up if there were two films with the same title. Since this isn't currently possible in ColdFusion, the film will have to be identified by its title (and budget) alone.

    NOTE

    Keep this limitation in mind when creating drill-down applications with <cfchart>. If a data point can't be safely and uniquely identified by the combination of the label and value displayed in the graph, you probably won't be able to implement drill-down.

    Listing 16.7. FilmExpenseDetail.cfmDetail Page Displayed on Drill-Down


    <!---
    Name:        FilmExpenseDetail.cfm
    Author:      Nate Weiss & Ben Forta
    Description: Movie drill-down
    Created:     01/10/05
    --->
    <!--- These URL parameters will be passed by the chart --->
    <cfparam name="URL.MovieTitle" type="string">
    <!--- Get information from the database --->
    <cfinvoke component="ChartData"
    method="GetFilmID"
    returnvariable="FilmID"
    movietitle="#URL.MovieTitle#">
    <!--- Show an error message if we could not determine the FilmID --->
    <cfif FilmID IS -1>
    <cfthrow message="Could not retrieve film information."
    detail="Unknown movie title provided.">
    </cfif>
    <!--- Now that we know the FilmID, we can select the --->
    <!--- corresponding expense records from the database --->
    <cfinvoke component="ChartData"
    method="GetExpenseDetails"
    returnvariable="ExpenseQuery"
    filmid="#FilmID#">
    &l275>
    <head>
    <title>Expense Detail</title>
    </head>
    <body>
    <cfoutput>
    <!--- page heading --->
    <h3>#URL.MovieTitle#</h3>
    <!--- html table for expense display --->
    <table border="1" width="500">
    <tr>
    <th width="100">Date</th>
    <th width="100">Amount</th>
    <th width="300">Description</th>
    </tr>
    <!--- for each expense in the query... --->
    <cfloop query="expensequery">
    <tr>
    <td>#LSDateFormat(ExpenseDate)#</td>
    <td>#LSCurrencyFormat(ExpenseAmount)#</td>
    <td>#Description#</td>
    </tr>
    </cfloop>
    </table>
    </cfoutput>
    </body>
    </html>

    The purpose of the method invocation is to determine the FilmID that corresponds to the Movie Title parameter passed to the page (from the chart in Listing 16.6). As a precautionary measure, the Budget parameter is also included in the query criteria. This means that if two films happen to have the same title, they can still be correctly identified as long as their budgets are different. For the rest of the page, FilmID holds the ID number for the film and can be used to retrieve any related information from the database.

    NOTE

    If no films are retrieved from the database (or if more than one is retrieved), an error message is displayed with the <cfthrow> tag.

    Drilling Down to another Chart

    You may want to drill down to a different chart that shows a different view or subset of the data, rather just drilling down to a simpl260 page. The second chart page, in turn, could drill down to another page, and so on. You could use any of the drill-down techniques discussed in this section to put together such a multilayered data-navigation interface.

    Additional Charting Topics


    The remainder of this chapter introduces various topics related to ColdFusion charting features.

    Plotting Individual Points with <cfchartdata>

    The most common way to provide the actual data to a <cfchartseries> tag is to specify a QUERY attribute, then tell ColdFusion which columns of the query to look in by specifying itemcolumn and valuecolumn attributes. All of the examples you've seen so far in this chapter have supplied their data in this way.

    It's also possible to omit the query, itemcolumn, and valuecolumn attributes and instead plot the data points individually using the <cfchartdata> tag, nested within your <cfchartseries>. The <cfchartdata> approach can come in handy if you want to permanently hard-code certain data points onto your charts, if you need to format your data in a special way, or if you come across a situation where you can't extract the desired data from a query in a completely straightforward manner.

    Table 16.8 shows the syntax for the <cfchartdata> tag.

    Table 16.8. <cfchartdata> Syntax

    ATTRIBUTE

    DESCRIPTION

    item

    The item associated with the data point you're plotting, such as a film title, a category of purchases, or a period of timein other words, the information you would normally supply to the itemcolumn attribute of the <cfchartseries> tag.

    value

    The value of the data point (a number). This is what you would normally supply to the valuecolumn attribute of <cfchartseries>.

    For instance, if you have a query called ChartQuery with two columns, ExpenseDate and ExpenseAmount, and you wanted to make sure the date was formatted to your liking when it was displayed on the chart, you could use:


    <cfchartseries type="line">
    <cfloop query="ChartQuery">
    <cfchartdata item="#DateFormat(ExpenseDate, 'm/d/yy')#"
    value="#ExpenseAmount#">
    </cfloop>
    </cfchartseries>

    instead of:


    <cfchartseries type="line"
    query="ChartQuery"
    valuecolumn="ExpenseAmount"
    itemcolumn="ExpenseDate">

    This technique is also useful when creating charts based on data that are not query based. Using <cfchartdata> you can pass any data to a chart.

    Using Charts with Flash Remoting

    It's possible to use the name attribute to capture the binary content of a chart and then make it available to the Macromedia Flash Player via Flash Remoting. This capability allows you to create a FlashChapter 26, "Integrating with Macromedia Flash," for general information about connecting ColdFusion to Flash via Flash Remoting.

    Controlling the Chart Cache

    ColdFusion automatically caches charts for later use. Conceptually, the chart cache is the charting equivalent of the query-caching feature you will learn about in Chapter 25, "Improving Performance." Its purpose is to improve performance by automatically reusing the results of a <cfchart> tag if all of its data and attributes are the same, rather than having to re-render each chart for every page request.

    The Charting page of the ColdFusion Administrator contains a number of options that you can use to tweak the chart cache's behavior:

    • Cache type.
      You can set this to Disk Cache (the default value) or Memory Cache. The Memory Cache setting will perform better under a high load, but it will require more of the server's memory to do so. The Disk Cache setting may not perform quite as quickly, but it will not have much of an impact on the server's RAM. We recommend leaving this value alone unless you're specifically experiencing performance problems with <cfchart> under a heavy load.

    • Maximum number of images in cache.
      You can increase this number to allow ColdFusion to store more charts in its cache, thereby improving performance if your application is serving up a number of different charts. If you're using the Memory Cache option, keep in mind that this will cause even more of the server's memory to be used for chart caching.

    • Maximum number of chart requests.
      This is the maximum number of <cfchart> tags that you want ColdFusion to be willing to process at the same time. Under a high load, a higher number here may improve responsiveness for individual page requests, but it will put more strain on your server.

    • Disk cache location.
      If you're using the Disk Cache option, you may want to adjust this value. It's the location in which ColdFusion stores charts for later reuse.

    For more information about the ColdFusion Administrator, see Chapter 29, "ColdFusion Server Configuration."

    • / 281