The Cold Fusion Web Database Construction Kit
If you've used CGI programs through your Web browser, you probably have noticed that the output you receive tends to be slower than when you request a comparable static HTML page. This is a direct result of how Web servers interact with CGI programs. CGI is a very portable and easy-to-use specification with which you may extend the capabilities of your Web server, but it was never designed to be fast. For this reason, Cold Fusion defaults to using server API modules instead of CGI. This chapter introduces server API modules, teaches the differences between them and CGI, and explains why you should always use the server API modules when possible.
Cold Fusion is an example of a Common Gateway Interface application. The Common Gateway Interface is a mechanism to allow Web servers, which are designed to serve static documents, to receive dynamic output from programs and serve it as if it were static data. CGI applications provide most of the interaction found today on the Web. When you fill out a simple guestbook or use a complex Web application fused to a database, you are most likely invoking a CGI program to communicate between you, the Web server, and some other service--perhaps a database. All of this communication, however, imposes costs on the speed of execution.
Cold Fusion, a CGI program, is no different. After all, it has to do a lot of work to return a page! When a browser sends a request for a Cold Fusion template to a Web server, several things must happen. First, the Web server recognizes the information from the browser as a request for CGI output, as shown in step 1 in Figure 29.1. If the request was initiated from a form, the server has to write the form field information to some area in storage that is accessible to other programs on the machine. Usually, this is done by using STDOUT data streams. The WinCGI interface, which can be used by WebSite and other servers, writes the form data to INI-style files on disk, which are then opened and read by the CGI application. This communication is shown in step 2. In step 3, the CGI program requests data from the data source, which is returned in step 4. The CGI program formats the data as HTML output, returning this output to the server in step 5. The server receives this output, performs any further server-side processing necessary, and then sends it to the browser.
Figure 29.1 Path of a CGI request from browser to server and back again.
Some makers of Web servers, recognizing this problem, provided a solution. They exposed and documented application programming interfaces, or APIs, to various elements of their server applications, allowing programmers to write extensions to their servers. These extensions can provide all the functionality found in the CGI interface, and more. But the biggest advantage is that the extensions become, essentially, part of the server, minimizing the time it takes for the program to load and communicate with the server.
The price for this hot-rod interface is complexity. Writing server extensions requires extensive knowledge about advanced programming topics.
Using server extensions, however, is easy. All you have to do is install Cold Fusion and configure your templates for API use.
Another advantage that using the Cold Fusion server API modules provides is document-type mapping. Document-type mapping, as you have read in Chapter 25, "MIME Types," is a mechanism by which your Web server can host different types of output as if it were just another document. Cold Fusion, by using document-type mapping, allows you to place your templates within your regular document tree, just like you do with HTML, GIF, and JPG files. When the Web server is asked for a Cold Fusion template in its document tree, it automatically forwards the request to Cold Fusion, which is running as part of the server. This greatly simplifies your document-management tasks, as you don't have to keep separate templates and you don't have to figure how paths will be calculated every time you use a template. Also, you can consolidate document security by using the mechanism provided by your Web server; for example, you could password-protect a directory by using Basic Authentication, rather than have to build a login system within Cold Fusion.
Through the book, all the code examples have used the CGI interface, since that is the most broadly supported method of using Cold Fusion. To use the API version, you have to have a Web server for which Cold Fusion provides an API module, and you have to make sure that your existing Cold Fusion templates are modified as necessary to retain the desired path structure of references. If you want to use relative references, you have to map your Cold Fusion template directories to your Web server document directories by using Cold Fusion Administrator; otherwise, you don't need to do this when you use document-type mapping.
Only a few Web servers provide an API. Cold Fusion provides an API module for nearly all of those servers. Cold Fusion supports the following with server API modules:
Some servers implement APIs from other servers. WebSite, for instance, can use ISAPI extensions, but not ISAPI filters. Purveyor, from Process Software (http://www. process.com/), fully supports ISAPI. Future servers may also support these APIs. Currently, if you have one of these servers, Cold Fusion will not automatically configure your server to use the API module, even though your server supports the API because the document-type mapping configuration varies from one server to the next. You may be able to manually configure your server and Cold Fusion to use the API.
CAUTION: Allaire does not support the use of API modules with any servers other than the ones listed above at this time. If you try to use these modules on another server, you probably don't want to try on a production server until you've tested on a development server.
If you want to understand how the server API module interacts with your server, here is a behind-the-scenes look at what happens when you install Cold Fusion.
When you're using WebSite 1.1e, 1.1f, or Pro:
Figure 29.2 Registry Editor showing the ColdFusion.Template key and its subkeys.
NOTE: The Cold Fusion module for WSAPI is a load-on-demand generator. Therefore, it doesn't require an entry in the subkey of HKEY_LOCAL_MACHINE\SOFTWARE\Denny\WebServer\CurrentVersion\ CGI\DLL as it did under Cold Fusion 1.5. However, you can manually enter this key and use the Cold Fusion API module as a registered generator. This allows you to reference Cold Fusion templates in a manner similar to CGI references rather than use document-type mapping. To do this, select the above mentioned subkey. Then, add a key with a name like cfusion. The name that you use is completely up to you; you'll have to reference it in every URL that attempts to use the registered generator. The values for this key are:
ExtCgiDll D:\CFUSION\BIN\WSCF.DLL
ExtCgiEntry Process
Then, you can use the ~wsapi syntax to reference the URL. For example, rather than call the CGI version in this line:
http://www.a2z.com/cgi-shl/cfml.exe?template=/a2z/app.cfm
you could reference it by using the WSAPI module without using document-type mapping:
http://www.a2z.com/~wsapi/cfusion?template=/a2z/app.cfm
If you are using Internet Information Server:
Figure 29.3 Registry entry for Internet Information Server, showing the FilterDLL value with the Cold Fusion filter appended.
Under Netscape Enterprise Server:
CAUTION: Netscape Enterprise Server provides three different methods of serving more than one domain name. You can install another instance of the server software by using the Netscape Admin Server, which creates another http directory with its own separate configuration files and runs multiple services on Windows NT. Or, within an existing server, you can configure hardware virtual servers, which are bound to different IP addresses, and software virtual servers, which map multiple domain names to the same IP address by using information sent in document request headers by the later Netscape browsers. If you install Cold Fusion onto a machine running multiple instances of the server software, you have to confirm that all the instances for which you want to use the Cold Fusion API module are correctly updated. Likewise, if you have already installed Cold Fusion and want to create another instance of the server software, you have to update the configuration files by hand. Virtual servers share the same configuration files, so one installation will configure them all.
Figure 29.4 The Netscape obj.conf file shows the changes added by Cold Fusion.
So far, you've been using the CGI interface. You've referenced the CFML.EXE CGI gateway program in each of the examples and specified a Cold Fusion template as a parameter to the CGI program. The template was stored outside your document tree, in a template directory mapped to a physical directory in the Cold Fusion Administrator. This necessitated keeping track of two document trees: one for Cold Fusion and another for the rest of your HTML documents, images, and any other type of static content.
With document-type mapping, you can place your Cold Fusion templates directly within your document tree and reference them like you would any other document within the tree. For example, you may have had a Cold Fusion URL like this:
http://www.a2z.com/cgi cfml.exe?template=/a2z/index.cfm
When your Web server received a request for this URL, it would notice that the directory mapping /cgi-shl/ represented a CGI executable directory outside the document tree; then it would execute the CGI program, sending the template name to Cold Fusion.
With document-type mapping, the URL would instead be:
http://www.a2z.com/index.cfm
Now, your Web server will look in your root directory of your document tree and confirm that there is an index.cfm file. If there is, it will note the document type as a Cold Fusion template and then send it to Cold Fusion for execution. If the file path is relative, Cold Fusion checks its own internal document directory mapping, executes the template, and sends the results back to the client as if the document was an actual HTML file within the document directory.
You'll probably notice a couple of advantages right from this example! Not only can you simplify the management of your Web site documents by keeping them within the same tree, you also get an easier set of URLs to deal with. It's pretty easy to mistype that first URL above!
One of the great things about document-type mapping is that it's so simple to use! If you have a lot of Cold Fusion templates that use the CGI syntax or the Cold Fusion 1.5 API syntax, you will have to perform a lot of search and replace, but not too much else.
There are a few things that you'll have to do differently. Here's a short list.
Document-Type Mapping and the Cold Fusion Administrator. You've read previously
about the Cold Fusion Administrator's Mapping tab, which allows you to map template
directories outside your document tree for use with CGI. How does this work with
document-type mapping? There are several things you'll need to take into account,
depending on the complexity of your site and the existing Cold Fusion templates you're
already using.
When Cold Fusion is installed, two mappings are entered in the Cold Fusion Administrator Mapping tab: the "/" used to specify the Cold Fusion document root and the mapping within your document tree for the Cold Fusion HTML documentation. If you have added CGI mappings, they will be here too, of course. These mappings resolve all references to Cold Fusion templates, whether these references are in the URL that uses the Cold Fusion CGI or whether they are within CFINCLUDE tags.
As long as you place all your templates within your document tree and reference them just as you would any other document, you don't have to do anything else to use document-type mapping. Here is an illustration of this simplest case.
We'll use a single domain, a2z.com, and a single document tree, where www.a2z.com maps to c:\docs. Within the \docs directory, we'll place a single subdirectory, c:\docs\bookapp. Within the root directory is a template, index.cfm, and within the \bookapp directory is another template, bookapp.cfm.
For this example to work, you'd have to map the Cold Fusion document root, or "/", to c:\docs. That's it! You could then refer to the document in the root as:
http://www.a2z.com/index.cfm
and bookapp.cfm as:
http://www.a2z.com/bookapp/bookapp.cfm.
That was pretty easy, wasn't it? How about if you wanted to use CGI references to these documents? You'd then have to add a mapping for the c:\docs\bookapp directory to /bookapp/ in the Cold Fusion Administrator.
NOTE: Just because you have to place templates within your Web server's document tree to use document-type mapping doesn't mean that your documents have to be somewhere within some physical disk directory that is your document root; most Web servers support virtual mapping. This allows you to map virtual directories within your document root that correspond to some location outside your document root. Just make sure that you also map these directories within the Cold Fusion Administrator.
Absolute and Relative References. Within the CFINCLUDE tag, you can use either absolute or relative references. Absolute references refer to the template root defined in the Cold Fusion Administrator. Referring to the earlier example, this tag would refer to the index.cfm file in the c:\docs\ directory based on the information in the Administrator:
<CFINCLUDE TEMPLATE="/index.cfm">
Note that this tag could be placed in any template, regardless of its relative position to the included template in the document tree. Taking out the backslash
<CFINCLUDE TEMPLATE="index.cfm">
would work only if called from a template in the same directory.
Multihoming. Using document-type mapping with multihoming can be a little
more complex. Multihoming servers have no single-document root directory that corresponds
to a URL. Therefore, the document root mapping in Cold Fusion doesn't necessarily
match a real document directory.
Under WebSite, Cold Fusion automatically receives the correct directory, as long as the root mapping corresponds to the Web server's overall root directory. For example, if you were hosting a2z.com and xyz.com, you might have www.a2z.com mapped to c:\docs\a2z, and www.xyz.com mapped to c:\docs\xyz. In the Cold Fusion Administrator, you'd only need to map "/" to c:\docs. This mapping will also work under Microsoft Internet Information Server 2.0.
Miscellaneous Usage Notes. There are a couple of situations that you should
be aware of when using document-type mapping:
http://www.a2z.com/cgi/cfml.exe?template=/a2z/executethis.cfm&Param=1
What happens if you do that with a template you're calling by using document-type mapping?
http://www.a2z.com/executethis.cfm&Param=1
The previous statement won't work because the ampersand specifies an additional parameter, rather than a single parameter. In the first example, the first parameter is the template name, and the second is Param. So the proper syntax for the second example would be:
http://www.a2z.com/executethis.cfm?Param=1
This is a simple change for you to make in your Cold Fusion templates. However, you may have to use CGI syntax in some situations, even though you're using document-type mapping. At the time of this writing, for example, if you are building Java applets by using the Database Component Framework described in Chapter 31, the Query.addParam method expects you to be using the CGI syntax and appends parameters with an ampersand.
Why Wouldn't You Want to Use Document-Type Mapping? There are some concerns
that you may have if you use document-type mapping. The first, and probably most
serious, is that you may place some of your code at risk.
Consider the following hypothetical situation. On your server, some part of the Cold Fusion service or communication gateway crashes. Then, someone requests a template file available from within your document tree. What happens? The server, not being able to communicate with its "dead" Cold Fusion service, doesn't know what to do with the file. It then sends it, completely unparsed, to the browser, which also doesn't know what do with it. It prompts its user to save the unparsed Cold Fusion template as a text file. The user, if he or she does so, can view all the code that you've entered into the template.
Does this sound unlikely? Actually, it happens enough that this author has seen it more than once while browsing sites. The best example took place on the www. microsoft.com site, which allowed the author to download a file without registering it because the unparsed template listed the name of the desired file.
Another, less serious concern is the effect of Web robots on your site. Robots visit a site and index the contents of the pages. You might not want robots indexing all the dynamic content of Cold Fusion templates, though, since robot traffic takes up bandwidth and since you might not want some of the information available to be indexed. Normally, to prevent robots from visiting parts of your site that you want to keep closed, you would create a file in the root of your documents called robots.txt, which specifies which directories are off-limits. You generally would place your CGI directories on this list. With document-type mapping, you don't have a CGI directory for your templates. If specified as the default document in a directory, a Cold Fusion template can be indexed by a Web robot. On the other hand, you may find this to be beneficial; you can now place META tags within a Cold Fusion template, and these tags can be read and stored by robots.
Now that you understand server API modules and document-type mapping, you may want to retrofit your code to support these new Cold Fusion features.
The last chapters cover some loose ends about Cold Fusion, including Allaire Forums, a set of templates available from Allaire that allows you to use a Web page as a message board:
© Copyright, Macmillan Computer Publishing. All rights reserved.
){kind=link}
){kind=link}
){kind=link}
){kind=link}