ColdFusion MX Bible phần 7 pot

704 Part V ✦ Integrating ColdFusion MX with Other Technologies If instead you need to retrieve a file from a remote server via HTTP rather than FTP, that’s one use of CFHTTP. We learned that we can extract a CSV or other tabular-formatted file and retrieve it into ColdFusion as a query result set. That’s not a feature that many know about. More typically, it’s used to “grab” the HTML output of a web page and pull that into a variable within our ColdFusion template. From there we saw that we could parse the HTML to select and perhaps display just some portion of the page. Finally, we also saw that we could use CFHTTP to simulate submission of a form, in particular by use of the CFHTTPPARAM tag. ✦✦✦ 36546228 ch31.F 1/30/03 12:15 PM Page 704 Extending Your ColdFusion MX Applications ✦✦✦✦ In This Part Chapter 32 Adding Useful ColdFusion MX Features to Your Application Chapter 33 Charting Data with ColdFusion MX Chapter 34 Leveraging Nifty Custom Tags Chapter 35 Tools to Enhance the Development Environment ✦✦✦✦ PART VI VI 37546228 PP06.F 1/30/03 12:15 PM Page 705 37546228 PP06.F 1/30/03 12:15 PM Page 706 Adding Useful ColdFusion MX Features to Your Application I n this chapter, we introduce some features in ColdFusion that you may consider using to enhance your application. They’re not new to ColdFusion MX, but they’re certainly classics, and they’re often misunderstood (or plain missed) by many CF developers. Each may involve some coordination with the CF Administrator, but we cover what you need to know so that you can effectively address any considerations that they may raise. The first, CFSCHEDULE, enables you to create automation processes that execute at scheduled intervals. This can prove very useful if you have some process that needs to run repeatedly or at some point in the future. We discuss both setting up and using the scheduling features. The second, CFFILE, is one of the richest of all CF tags in that it can perform many different functions, which can be broken into three broad areas. As suggested by its name, it enables the manipulation of files on the CF server. In one respect, it enables the processing of files as a whole (moving them, deleting them, and so on). In another respect, it enables you to read from and write to files. Finally, it also enables you to upload files from the client via a special HTTP form feature. We discuss each of these. The third feature, Verity Indexing, enables you to create a searchable library of files on your server, which can be especially useful if you have a large number of HTML documents, word-processing files, spreadsheets, presentations, and Acrobat PDF files, to name just a few. The process of creating, populating, and searching an index of such files is quite straightforward and may be one of the under- utilized features in CF. We show you the basics and point you to other resources to learn still more, including how to leverage the Verity index capability to add more power to database searching as well. 32 32 CHAPTER ✦✦✦✦ In This Chapter Running unattended tasks by using CFSCHEDULE or the Administrator Scheduled Task facility Reading, writing, manipulating, and uploading files by using CFFILE Creating searchable file libraries or query results by using Verity Indexing ✦✦✦✦ 38546228 ch32.F 1/30/03 12:16 PM Page 707 708 Part VI ✦ Extending Your ColdFusion MX Applications Running Unattended Tasks by Using CFSCHEDULE or the Administrator Scheduled Task Page Have you ever wanted to execute some part of your application in an automated fashion, such that it occurs after some length of time or at some recurring point in a business cycle? Maybe you want to archive the records of customers who haven’t placed an order in the past 12 months or you want to send an e-mail to members whose expiration date is approaching. You may also want to set up a scheduled task to repopulate a Verity index each day or week. (We discuss Verity indexes in the section “Creating Searchable File Libraries or Query Results by Using Verity Indexing,” later in this chapter.) The good news is that, if you have a ColdFusion template that performs some desired pro- cessing to be executed in an unattended, perhaps repeated manner, you can indeed schedule it by using the CFSCHEDULE tag. You can also use the Scheduled Tasks feature available in the ColdFusion Administrator, if you have access to that. The feature can execute any available URL — it’s really not limited to just CF pages nor even to those only on your own server. You can also choose to store any HTML output from the execution of the scheduled task for later viewing. This could prove handy if you need to cre- ate a report from a Web page for a user who doesn’t have access to the application. This scheduled-task feature was originally used by many to create static output of dynamic pages that may be visited by a large number of users but that contained content that didn’t change often. Rather than point users to the dynamic CFML-generated page, they would use the scheduled-task capability to create a separate HTML file and then point users to that HTML file. This rather tedious process is obviated by the CFCACHE tag. (See the ColdFusion documen- tation for more information on that tag.) The documentation for the scheduler, however, still refers to this outmoded process as one of the uses for the feature, without mentioning CFCACHE. Certainly, if for some reason you can’t use the CFCACHE tag, knowing that this scheduled-task feature is available is useful. The scheduled-task feature in ColdFusion is separate from a similar capability that may be available in your operating system. Windows has its own notion of scheduled tasks, and Unix has chron jobs. Although these features are generally used to execute some sort of system command or batch file on a scheduled basis, they may not be available to you as a developer. They’re also not designed to execute CF templates (although they can indeed do that, but dis- cussing that feature is beyond the scope of this book). Remember, too, that the CF Scheduled Task feature enables you to execute a Web page, that is, any URL that can be called from the server that’s hosting ColdFusion. An operating-system scheduler, on the other hand, generally just executes locally available commands. Adding a scheduled task You can set up a scheduled task either in the ColdFusion Administrator (if you have access to it) or by using the CFSCHEDULE tag (if it isn’t disabled by the CF Administrator). We look briefly at each method in this and the following section. New Feature 38546228 ch32.F 1/30/03 12:16 PM Page 708 709 Chapter 32 ✦ Adding Useful ColdFusion MX Features to Your Application Although many readers do not have access to the CF Administrator pages, we show the use of that interface first. In the following section, we show how to set up and manage a sched- uled task by using the tag-based approach. Each is capable of the same results. Figure 32-1 shows the Administrator’s interface for the scheduler. After you first open the Administrator, the scheduler interface is listed (curiously) in the left navigational toolbar, under Debugging & Logging, as Scheduled Tasks. The page that this link takes you to offers a form where you can add, edit, or delete tasks. Figure 32-1: CF Administrator’s interface for scheduled tasks. To create a new task, click the Schedule New Task button. Figure 32-2 shows the form that appears for creating a new task, where you indicate which template you want to run, when you want to run it, how often, and several other characteristics that may be necessary. The figure doesn’t show all available fields on the form, but if you scroll down in the Administrator, you see them all. We discuss the most important ones in this section. See the online Help available within the Administrator for the others. The Task Name field is where you just type a simple phrase of your choosing to label the task. Notice that it’s not the URL of the actual page to be executed, as a field for that information comes further down on the form. The minimum information required to add a new task goes into the Duration fields (Start Date and an optional End Date), the Frequency options (choos- ing among One-time, Recurring, or Daily Every to indicate how often and when to run the task), and the URL field (the page to be executed). 38546228 ch32.F 1/30/03 12:16 PM Page 709 710 Part VI ✦ Extending Your ColdFusion MX Applications Figure 32-2: CF Administrator interface for adding a new scheduled task. The URL that you provide must be a fully qualified URL (starting with http://). The Administrator interface and the CFSCHEDULE tag that we discuss in the following section do not make any presumptions about the location of the code to be executed. If the code is on the same Web server as that serving this ColdFusion Administrator, you can use http://localhost or http://127.0.0.1 as the domain (before the rest of the URL). Indeed, this suggests that you can use the scheduler to execute any URL at all, including those on some other server on the network. You may be required to provide additional information about the execution of the task. If the URL that you’re executing requires Web-server authentication (a login and password), for example, you need to provide that here, as well in the available User Name and Password fields. Failure to provide a URL in the URL field may cause more confusion for scheduling tasks than any other problem. You may assert that you can browse the URL in your browser without providing a username/password. First, however, you need to realize that the scheduling facil- ity is executing the URL on your behalf as if it were the client. (It runs the equivalent of a CFHTTP request on your behalf.) So although you may find you can browse the URL without an authentication prompt, that may be because you provided such authentication earlier in your current browser session. Naturally, that has no effect on the scheduler that’s running the task. If a page to be executed requires authentication, you must provide a username and password for the scheduled task. Also, and more troubling for some, you must take into account the fact that the scheduler (and indeed CFHTTP) can’t perform anything other than basic (plain-text) Web-server authentication. If the URL that you want to execute calls for digest authentication or inte- grated Windows authentication on IIS, you cannot execute that URL with a scheduled task. Caution Note 38546228 ch32.F 1/30/03 12:16 PM Page 710 711 Chapter 32 ✦ Adding Useful ColdFusion MX Features to Your Application Other information that you may want to provide for a new task (not shown in Figure 32-2) includes any needed proxy server information and an optional timeout that you may want to provide to cause a long-running scheduled task to give up if it may take too long to execute. And if you’re interested in retaining the output from the task, you have an option to publish the output to a path/filename of your choosing. That section also offers a resolve-URL option that, like CFHTTP, can convert relative URLs found in the HTML output of the requested page into absolute ones. Using the CFSCHEDULE tag to add a task Because most developers can’t access the ColdFusion Administrator, a CFSCHEDULE tag is availablethat can perform all the same functions of the Administrator interface. Each of the options listed on the figures in the preceding section are available for the CFSCHEDULE tag via similarly named attributes (using the attribute action=”update”, which either adds or updates a scheduled task). The following code provides an example of how to use the CFSCHEDULE tag to schedule a task called DeleteExpiredMembers so that it runs a template at www.somedomain.com/ members/DeleteExpired.cfm at 12:10 p.m. starting 6/28/2002 and continuing on a monthly basis for an indefinite duration (because no enddate is provided). The output of that tem- plate is to be written to the file D:\inetpub\wwwroot\members\deletelog.txt, as the fol- lowing example shows: <cfschedule action=”update” task=”DeleteExpiredMembers” operation=”httprequest” url=”http://www.somedomain.com/members/DeleteExpired.cfm” startdate=”6/28/2002” starttime=”12:10pm” interval=”monthly” resolveurl=”no” publish=”yes” file=”deletelog.txt” path=”D:\inetpub\wwwroot\members\”> Again, as we mention in the preceding section, you need to provide a complete URL even if the code that you’re executing is on the same server as ColdFusion MX. Be aware that use of the CFSCHEDULE tag itself can be disabled in the ColdFusion Administrator so that it can’t be used in any templates on the server. See Chapter 44 for more information. Finally, you can update or delete (or run immediately) any scheduled task, either from the Administrator interface, as shown in Figure 32-1, or from the CFSCHEDULE tag. See Chapter 47 for more information. Reading, Writing, Manipulating, and Uploading Files by Using CFFILE It is common that ColdFusion developers will need to perform some sort of file processing (reading and writing) or file manipulation (move, copy, delete, and so on). If you need to read the contents of a file, want to create (or append to) a file to hold some sort of text, or need to manipulate files on the ColdFusion Server, you want to know about the CFFILE tag. Another very different kind of capability is enabled via CFFILE, and its one that has no corre- lation to typical file processing. If you’ve ever wanted to create a process whereby visitors to your site could upload files from their local machines to your ColdFusion server, you should Note 38546228 ch32.F 1/30/03 12:16 PM Page 711 712 Part VI ✦ Extending Your ColdFusion MX Applications be happy to know that you can do that by using CFFILE. This kind of capability can be used to send photos of people on a membership site or of houses on a real estate site. It can also be used to upload a user’s resume in its native word-processing format. This third capability is much more involved than the first two, so we’re going to discuss the simpler processes first. Reading/writing files on the server Although the ColdFusion markup language (CFML) is a full-featured language with many capa- bilties of traditional languages (flow control, conditional expressions, rich variables and data structures), you need to keep in mind that it’s primarily a language for creating Web pages dynamically. As such, the capability to read and write files isn’t exactly a top priority for most Web developers. Indeed, you may often be better off resorting to some other language that may be better suited to the task. Still, in certain instances, reading in a file’s contents by using CFML may make sense. Perhaps you’re processing a CSV (comma-separated value) file, for example, that you extracted from another program or database. Or maybe you’re given an XML file. (See Chapter 30 for more information on XML.) Using CFFILE is one way that you could read the contents of such a file into ColdFusion’s memory to process it as a simple variable. Better tools than CFFILE may be available for processing CSV and other regularly delimited files. See the Chapter 55 for more information on the CFHTTP tag’s available name attribute, which enables it to read a CSV file and convert it into a ColdFusion query result set. (See the entry on the delimiter and textqualifier attributes for information about defining something other than the default comma as a delimiter and using something other than double quotes as the text qualifier.) The Java libraries underlying CF MX also enable you to use Java to process such files. For more information, see the Macromedia TechNote at www.macromedia.com/handlers/index.cfm?ID=22250. Reading a file on the server If you need or want to read a file’s contents into a ColdFusion variable, the CFFILE tag offers a very simple mechanism to do so. To read the contents of a file named test.txt in the directory c:\temp\ so that they are stored in a ColdFusion variable named holdfile, for example, the tag you would use is as follows: <cffile action=”read” file=”C:\TEMP\TEST.TXT” variable=”holdfile”> This code reads the entire file into the single variable. From there, you can do with it what- ever you want, including using the variable in a CFQUERY tag to insert the contents into a database. More likely, you may want to manipulate the contents now in the variable by using any of ColdFusion’s many string-manipulation functions, such as paragraphformat(), or find(). If you try to output the variable’s value to the screen by using CFOUTPUT, make sure that the file contents are not pure text (but are HTML). If they’re plain text, the browser ignores white spaces between words and lines of text, and it also ignores line breaks and carriage returns, causing the file to appear compressed into one large block of text. You can improve the appearance in that case by using the ColdFusion formatting function, paragraphformat(). Note 38546228 ch32.F 1/30/03 12:16 PM Page 712 713 Chapter 32 ✦ Adding Useful ColdFusion MX Features to Your Application The following code sample reads the contents of the CF server’s application.log (one of CF’s many administrative log files) and displays it on-screen. Notice the use of the para- graphformat() function to enhance the appearance of the output, as follows: <cffile action=”read” file=”C:\CFusionMX\logs\application.log” variable=”getlog”> <cfoutput>#paragraphformat(getlog)#</cfoutput> Unless the CF Administrator takes steps to change installation defaults, the CFFILE tag can be used to read, write, move, and so on any file on any drive accessible to the ColdFusion Server (or accessible to the user under which the server is running in environments that pro- vide such process authorization). See the section, “Possible tag restrictions,” later in this chapter, for more information. Reading a binary file If the contents of the file that you want to read are binary in nature (an image or a word-pro- cessing file format), you want to use action=”readbinary”. You can still read the contents into a ColdFusion variable, but you can’t use CFOUTPUT to display the value, because CFOUTPUT can display only data that can be converted to a string-data format. You can store the data into a database column or write it to another file (by using CFFILE action=”write”, as we discuss in the next section). Writing to a file on the server Just as you can read an entire file’s contents to a ColdFusion variable, you can perform the reverse action as well, writing a variable (or any string, really) to a text file. As an example, the file that you read into ColdFusion in the section, “Reading a file on the server,” can be written out to another path/name as follows: <cffile action=”write” file=”c:\temp\testoutput.txt” output=”#getlog#” addnewline=”no”> Of course, for this code to execute, you need a variable called getlog to be defined before the tag executes. And if the file named in the FILE attribute doesn’t already exist, it is created. Additional attributes are available to the tag that aren’t needed but may be useful, including the option to specify file attributes ( readonly, hidden, and so on) for the file created, an option to specify the mode that sets permissions on Unix platforms and is ignored in Windows, and an option to indicate whether a newline character is written to the file after the specified contents in the output attribute. See Chapter 60 in the Language Reference for more information. Before leaving the discussion of writing to files, you should also know ColdFusion’s append action (as in action=”append”). The attributes for this are the same as for the write action; the difference is that the data written to the named file by using append is added at the end of the file, if one already exists (otherwise, a file is created). This option can be particularly use- ful for creating log files or writing other sorts of output files. You have a better way to create log files than by using write or append. Release 5 of ColdFusion introduced a new CFLOG tag that is much more capable and straightforward to use, especially for writing to the standard administrative CF log files. Note Caution 38546228 ch32.F 1/30/03 12:16 PM Page 713 [...]... seriescolor=”##FF0000”> Creating charts from both explicit data points and databases Exploring a sampling of chart types Charting multiple data series ✦ ✦ ✦ ✦ 39546228 ch33.F 73 0 1/30/03 12:16 PM Page 73 0... particularly different in ColdFusion MX from their versions in ColdFusion 5, take your applications to a new dimension if they’re understood completely and used effectively They also can provide valuable solutions to common needs that your clients have ✦ ✦ ✦ 39546228 ch33.F 1/30/03 12:16 PM Page 72 9 33 C H A P T E R Charting Data with ColdFusion MX ✦ ✦ ✦ ✦ In This Chapter C harting in ColdFusion has historically... permit GIF and JPG formatted images, for example, you can specify the 71 7 38546228 ch32.F 71 8 1/30/03 12:16 PM Page 71 8 Part VI ✦ Extending Your ColdFusion MX Applications example tag from the preceding sections (with the option to make file names unique) as follows: The MIME type for... Verity Index collections ✦ The CFFILE tag is a true Swiss Army knife among ColdFusion tags, offering three broad areas of capability: reading and writing the contents of files, manipulating files, and uploading files from the client to the server 72 7 38546228 ch32.F 72 8 1/30/03 12:16 PM Page 72 8 Part VI ✦ Extending Your ColdFusion MX Applications ✦ The Verity Index feature (the tags CFCOLLECTION, CFINDEX,... 2-D and a 3-D line chart Figure 33-6: Line charts 73 3 39546228 ch33.F 73 4 1/30/03 12:16 PM Page 73 4 Part VI ✦ Extending Your ColdFusion MX Applications Curve A curve chart is very similar to a line chart, but instead of drawing a straight line between data points, CFCHART draws a curved line connecting all the points, as shown in Figure 33 -7 Figure 33 -7: Curve charts Step A step chart is also similar... circle represents all of the revenue made from 19 97- 2001, and each slice of the pie is proportional to how much each year contributed to the total five-year revenue stream Note that you can also “explode” pie slices by setting pieslicestyle=”sliced” in the CFCHART tag 73 7 39546228 ch33.F 73 8 1/30/03 12:16 PM Page 73 8 Part VI ✦ Extending Your ColdFusion MX Applications Creating a Chart from the Database... action=”upload” that can store the Photo field from this example to a directory on the server called c:\CFusionMX\wwwroot\members: 38546228 ch32.F 1/30/03 12:16 PM Page 71 7 Chapter 32 ✦ Adding Useful ColdFusion MX Features to Your Application Notice that this code uses a new filefield attribute, which holds the name... item=”1998” value=”288 475 5”> 39546228 ch33.F 1/30/03 12:16 PM Page 73 1 Chapter 33 ✦ Charting Data with ColdFusion MX Running Listing 33-2 produces the output shown in Figure 33-2 Figure 33-2: Adding a second series to the chart You can see from these examples...38546228 ch32.F 71 4 1/30/03 12:16 PM Page 71 4 Part VI ✦ Extending Your ColdFusion MX Applications Manipulating files on the server Maybe you’re not interested in reading or writing files You just need to manage and manipulate files on the ColdFusion server (or on a drive that it can access) CFFILE’s second major category of actions . 12:15 PM Page 70 4 Extending Your ColdFusion MX Applications ✦✦✦✦ In This Part Chapter 32 Adding Useful ColdFusion MX Features to Your Application Chapter 33 Charting Data with ColdFusion MX Chapter. the Development Environment ✦✦✦✦ PART VI VI 375 46228 PP06.F 1/30/03 12:15 PM Page 70 5 375 46228 PP06.F 1/30/03 12:15 PM Page 70 6 Adding Useful ColdFusion MX Features to Your Application I n this chapter, we introduce some features in ColdFusion. called c:CFusionMXwwwrootmembers: <cffile action=”upload” filefield=”photo” destination=”c:CFusionMXwwwrootmembers”> 38546228 ch32.F 1/30/03 12:16 PM Page 71 6 71 7 Chapter 32 ✦ Adding Useful ColdFusion