The first step in understanding the CFHTIP tag is to take a quick look at its attributes. Technically speaking, the tag is quite simple with a manageable number of attributes, but this simplicity belies the range of roles that the tag can play.
The following list outlines the ttributes of the CFHTT tag:
URL Spcifies the URL of the file being accessed.
POIT Specifies the pori to be used in accessing the server.
METHOD Specifies the method to.access the server. Possible methods are GET and POST.
USEINME Specifies the usemame to use if the server requires authentication.
Password Specifies the password to use if the server requires authentication.
MAlE Specifies the name to assign to a query if the CFHTTP tag is being used to convert a delimited text file into a query.
COMING Specifies a comma-separated list of names to assign to columns when converting a text file to a query. These names override those specified in the f4″strow of the file.
PATH Specifies ~ directory in which a downloaded file should be stored.
FILE Specifies the filename to which downloaded data should be saved on the Cold- Fusion server..
DEUMTER Specifies the pattern of characters to use as a delimiter between fields in a text file being converted to a query.
TEXlQUALIFIER Specifies the character used to mark the start and end of a column when the celumn contains the delimiter character.
R£SOLVElItL Indicates that all URLs in the downloaded file should be converted from relative URLs to absolute URLs to avoid bad links.
PIOXYSEIVEI Specifies the proxy server to u’l1 when accessing the World Wide Web.
PIlOXYPOIT Specifies the port to use when a&~ing the World Wide Web through a proxy server.
U$EUGENT Specmes the user agent to provide to the server in order to mimic a specify browser.
THROMONERROR Specifies if the tag should throw an exception to be caught with the cmVand CFCATCH tags when an error occurs. Possible values are YES and NO. IEDDECT Specifies the action to take if the CFHTTP tag fails. If set to YES, CFHTTP follows any redirection provided by the server. If set to NOand THROWONERRORis YES, then an exception is thrown.
TDEOUT Specifies the time to wait in seconds for a response from a server before assuming the connection has failed
The Difference between GET and POST
Let’s start with a look at the METHOD attribute. This is the central key to how the CFHTTP tag operates. Using the METHOD attribute, one of two methods can be specified: GET or POST. The GET method is a one-way method. It is used to retrieve files (both text and binary files) from a server based on a specified URL. That’s all, really. Other than information encoded into the URL and the usemame and password provided for authentication if . needed, .no information is provided to the Web. server for processing or manipulation. By contrast, the. POST method is a two-way interaction in which the CFHTTP tag provides information of different types to the server to be processed by a CGI script, Cold- Fusion template. or other application. The application, in turn, can return data based on the processing it performed.
Using a.Basic GET Operation
At its most basic, you can use the GET method to retrieve a URL, store the content of the retrieved file in a variable, and then display or manipulate that variable as desired.” For instance, consider the Landegg Academy
You can retrieve this page by using the following CFHTTPtag:
When you do this, the resulting data is stored by default in the variable CFHTTP. File- Content. You can then use this variable in the rest of your template. For instance, to download the Landegg Academy home page and displaY.it, you would use the following ColdFusion code:
URL-‘ http://www. 1andegg. edu/’)
<CFOUTPUT>·tCFHTTP. Fi 1eContenU</CFOUTPUT>
This produces results like those
The first thing you probably noticed here is that none of the graphics appear correctly; they all appear to be broken links. This is because of the difference between relative and absolute URLs. Most Web pages encode the paths for images, links, and so on in terms of relative URLs. However, once the H1ML code fora Web “page is downloaded to the CFHTTP. Fi 1eContent variable and this code is then displayed using the CfOUTPUTtag the relative paths in the code point to locations on the ColdFusion server and not on the original Web server where the file carne from.
To solve this problem, you need to be able to tell the CFHTTP tag to convert all these relative links to absolute ones while it downloads the data. This is achieved with the RESOLVEURL attribute. By default, the value of RESOLVEURL is NO. But, set to YES, it causes all relative paths to be converted to absolute ones, resulting in the correct display of the HTML code.
Using RESOLVEURL in this way fixes all the types of URLs, links, and paths shown in the following list:
• Images using IMG SRC
• Links using A HREF
• Forms using FORM ACTION
• Applet references using APPLET CODE
• Script source files using SCRIPT SRC
• Embedded objects using EMBED SRC
• Embedded plug-ins using EMBED PLUGINSPACE
• Background graphics using BODY BACKGROUND
• Frames in a frameset using FRAME SRC
• Background sounds using BGSOUND SRC
• Objects using OB] ECT DATA, OB] ECT CLASSID, OB] ECT CODEBASE, or OB] ECT USEMAP
In this way, all graphics, applets, and embedded objects will display correctly; all links will function as they did in the original page; and frame-based sites can be accessed successfully.
Providing a Usemame and Password
Some sites password protect some or all of their pages by using basic authentication. Under basic authentication, the browser normally displays a password prompt in a dialog box like the one.
To use CFHTIP to access pages protected in this fashion, you can use the USERNAME and PASSWORD attributes. These attributes cause CFHTIP to respond to basic authentication and supply the specified login data to the server.
You have two choices in doing this. One approach is to hard-code a usemame or pass word into your template file where appropriate. For instance, the following code:
specifies the usemame and password to use if the Landegg Academy home page were password protected.
Alternately, you can provide a dynamic usemame and password that can come from; query result, can besubmitted by the user in a form, or can even be obtained from astored on the ColdFusion server. For instance, if you have a query result named USER with two fields, usernarne and password, then you could use the following CFHTTPtag to pass along the username and password fields to the server:
Saving to a File ,Using the GET Method
The PATHand FILE attributes provide a mechanism for saving the contents of a down- ‘loaded URL to a file on the ColdFusion server. For instance, to save the HTML file resulting from downloading the Landegg Academy Web page to a file at c: \html\ 1andegg. html, you could use the following CFHTTPtag:
When the CFHlTPtag is used in this way, the downloaded contents are not available is the CFHlTP. Fi 1eContent variable. Attempting to access this variable as in the following code segment will generate an error message like the one.
FILE=”l andegg. htJI1′,>