Practical Uses of HTTP in ColdFusion

Now, let's talk about cfhttpparam. This allows you to specify a parameter to send to the URL in the url attribute of the cfhttp tag. This tag lets you simulate HTML form submissions by adding parameters—GET and POST variables, cookies, and more—to your HTTP request. Let's see this in action.

In this example, we'll set a form variable, a cookie, a URL (query string) variable, and a file upload using our HTTP parameter tag. We'll also send a file for the target to upload. If you try this code out on your own server, you'll want to replace "www.example.com" with the path to your server.

<cfif not isDefined("Form.aFormField")>  
 <!--- this file (receive.cfm) requests itself --->  
 <cfhttp url="http://127.0.0.1/receive.cfm" method="post" timeout="10">  
    <cfhttpparam name="aFormField" type="FormField" value="I'm in a form.">  
    <cfhttpparam name="aCookie" type="Cookie" value="I'm a Cookie">  
    <cfhttpparam name="aUrlField" type="URL" value="I'm a URL variable">  
    <cfhttpparam name="aFile" type="File" file="C:\temp\test.txt">  
 </cfhttp>  
 
 <cfoutput>  
    Here is what the server said:<br />  
    #cfhttp.filecontent#<br />  
    #cfhttp.mimetype#<br />  
 </cfoutput>  
 
 <!--- end of the request --->  
<cfelse>  
 <!--- receives the variables --->  
 <cfoutput>  
    <cfif isDefined("Form.aFormField")>  
       Form Field: #form.aFormField#<br />  
    </cfif>  
    <cfif isDefined("Cookie.aCookie")>  
       Cookie Variable: #Cookie.aCookie#<br />  
    </cfif>  
    <cfif isDefined("URL.aUrlField")>  
       URL Variable: #URL.aUrlField#<br />  
    </cfif>  
    <cfif isDefined("Form.aFile")>  
       <cffile action="upload" filefield="aFile" destination="C:\temp\new_test.txt" nameconflict="makeunique">  
    </cfif>  
 </cfoutput>  
 <!--- end of the receipt --->  
</cfif>

What output is generated when you run this? Well, first the script requests itself using cfhttpparam to send some request parameters. When it is requested with those parameters, the script lists the parameters that it was sent. This output gets put into the cfhttp.FileContent variable back in the script that performed the request. It is then displayed along with the cfhttp.MimeType.

As you can see, cfhttp and cfhttpparam provide you a great deal of flexibility over your applications, and they can help you manipulate your ColdFusion scripts to behave like real people surfing a Website. I'm sure that you can probably think of a thousand different uses for these tags.

I should warn you, though, that you'll want to do plenty of error handling when using these tags. If the server you're calling is down, you'll need to allow your script to continue seamlessly (or at least fail gracefully). Any information for which you rely on that server will not be available. Also, use good judgment when using these tags. Making many HTTP calls will certainly cause problems on your site and could slow your server down considerably if you're not judicious.

Be aware that you must specify the absolute URL. If you try to specify just the relative filename, it will not resolve, and you'll get a connection failure.

cfheader and cfcontent Tags

The next thing we should discuss is the use of the cfheader tag. This can be used to manually set HTTP response headers along with the contents of a page. HTTP headers are sent with every request. They describe the type of data that's being sent back, along with various other attributes of the request. Let's say that you recently found the SitePoint article on No-Refresh links, and you wanted to attempt to implement that in a ColdFusion application (having first given attention to any usability issues that might arise, of course, as described in that article).

Once you decide how you want to implement this, you can do so very easily in ColdFusion:

<cfheader statuscode="204" statustext="No Content">

This sets the "no content" status code, which lets the browser know that there's no need to refresh, as there is no content. You could choose to set the status code to 404 (page not found) if you wanted, or even 500 (internal server error). Any valid HTTP response code can be specified in there (I don't know why you'd want to intentionally return a 404, though).

You might also use this tag if you were setting up search engine/user friendly URLs. You could set up a 404 error handler that would decide if there was a valid page to display for the user's request. If there was, you would set the status code to 200 (successful) and display the content. If it really was a page not found, you'd simply leave it as is, letting it return a 404, and tell the user that you couldn't find the page. We'll see yet another use of the cfheader tag in a moment.

Note that you must set up the 404 handler as a URL handler, not a File handler. The File handler will dump out your ColdFusion code in the browser as if it were a text file.

To illustrate this tag a little better, I put together this little bit of code. Here's the call.cfm file:

<a href="receive.cfm">Call</a>

It's just one simple link to call the receiving page. In the receive.cfm page, I have code that looks like this:

<cfheader statuscode="204" statustext="No Content">  
<cffile action="write" file="C:\Temp\test.txt" output="file written successfully">

Now, run the call.cfm page and click the link. You'll notice the status bar loads but the page remains on the call.cfm page. Open your Windows Explorer and go to C:\Temp and you'll see that the text.txt file was written with the string in the "output" attribute. So, it worked! Just be sure that you set the header before you output anything at all (if you're returning no content, there should really be no content output to the browser in the receive.cfm file, though).

Keep in mind that you'll need to alert the user that some action has taken place and has been successfully completed -- this could be done using JavaScript or DHTML. However you do it, don't confuse your visitors.

Now, let's delve into the cfcontent tag a bit before we move on to our project. This tag allows you to specify the MIME type that is returned by the file. If you output anything before the cfcontent tag, it will be ignored, just as with cfheader. You'll actually have to use cfcontent in conjunction with cfheader to make sure it works properly. What we're going to do with this tag is return an image in response to a request for a .cfm file. It's very simple to do:

<cfheader name="Content-Disposition" value="inline; filename=help.gif">  
<cfcontent type="image/gif" deletefile="no" file="C:\Inetpub\wwwroot\help.gif">

When you run this file, you'll see that it simply returns an image. Now create a new HTML document and insert this image tag in it:

<img src="returnimage.cfm" />

This assumes you have named your file with the cfcontent tag in it returnimage.cfm. Go to that file and you'll see that it's displayed right there on the page. You can return practically any file type you want. Simply specify the content disposition in the cfheader tag as shown above, and the content type (and, optionally, the name of the file to be sent from the server, and whether to delete the file) in the cfcontent tag, and you're done. For another example of how to use cfcontent and cfheader, check out Macromedia's Live Docs on the topic.