Cfincludes are probably one of the most used ColdFusion tags around.

The function of the cfinclude tag is to grab a file that is saved somewhere else in your server’s directory structure and ‘include’ its contents in the place of the cfinclude tag.

So, for instance, if you have this file:

You may have noticed that I put the include file in a specific directory structure. This is something that I have learned helps to keep the code organized. ColdFusion doesn’t require this level of organization, but it is helpful to yourself and other ColdFusion programmers to organize your code.

ColdFusion usually loads on your server with the ‘/’ mapping already there. This is so that you can use the ‘/’ in your cfinclude as a mapping to your webroot, and anything after that ‘/’ in the template parameter will be treated as the directory location.
I like to add a specific mapping to my ColdFusion administrator that for my ‘includes’ location. This makes it possible to move the location of the includes folder for future website changes.

A cool feature of this is also that the mapping location of the includes folder doesn’t actually have to been inside the webroot.

Let’s say for instance that you have two seperate websites that use some of the same code.

Your web root locations might be:

c:/inetpub/website1

c:/inetpub/websiteTwo

then you can have a mapping to:

<cfset this.mappings['/includes'] = ‘c:/sharedResources/includes’ />

Now you would be able to use the same includes in both websites. If code changes are needed, then you would only need to change 1 location.

The question has come up many a time regarding ‘when’ to use it, ‘why’ to use it, and of course ‘what’ is it.

I will start with the ‘when’. You should use cfqueryparam for any query to the database that uses a variable that ‘can’ be altered by the user. This means a url variable, a form variable, a cookie variable, etc. I, personally, just make it a practice to use cfqueryparam for variable in the database. (since a constant cannot be spoofed) It may be tedious, but this little tag has saved many a website in the past from being the victim of attacks.

Why to use it? Well, lets say that you have a very simple query that pulls up the data from a database to view an article on your site. You pass that article information via the url as an id.
eg. [yoursite]/viewArticle.cfm?id=12345

When the ‘evil-bad’ user tries to hack this site, they could change the url to have the id=12345;select * users;. If your code is setup to just loop over the results they ‘could’ see all of your user data in your users table. Now you may be thinking to yourself, ‘well I don’t use a users table’, or ‘I validate my queries when they come back better than that’ or something similar. My hacking example here is very rudimentary and I am sure you can image the havoc that can be caused by changing my ‘hackquery’ to something more vicious. Cfqueryparam would have stopped that hack attempt in its tracks.

How would it stop that? I am glad you asked. I will try to describe this using non-technical terms to try to help anyone who is reading this, newbie or experience.

Imagine yourself at a drive-thru teller at your bank. The older style where they have an actual person in a window as well as a suction tube that send your checks, cash etc into the teller to process.

You, in your car, are the coldfusion application code. The teller is the database. The tube is the datasource that you had to set up in the coldfusion administrator in order to ‘talk’ to the database.

Cfqueryparam is like using those plastic canister. You place all of your checks and your passbook and identification into the canister, you close the canister and then you place that canister into the tube and it zips off to the teller. The teller then opens the canister, processes your request and then sends your receipts back to you. If you had, instead, just put your items in the tube without the canister, the tube would have sent the items haphazardly to the teller.

With cfqueryparam, you are telling the database that the information in the value is a ‘closed’ environment and should only be checked against the values in the table, and NOT executed against the database as a whole.

I hope this helps a little to understand the when and why of cfqueryparam. I did not include any ’samples’ specifically because there are plenty of resources on the internet that describe the syntax of the tag.

Cfqueryparam should be a single part of your overall website security schema. It is the ‘last chance’ before something goes to the database. Please research full security methods to keep unwanted persons and sessions from attaching themselves to your site.

With this as my muse, I decided to try to get the process handled without using session variables, or anything that might require the existence of cookies on the browser. Please keep in mind that my solution here does not provide protection against XSRF attacks. That will probably be covered in a future post, but solutions can also be easily researched on other blogs.

The only way that I could determine to do this form submission validation, without sending a cookie to the user was to either create a server variable and send the key to the form, or to directly hash the validation code in the form as a hidden field.

For instance:

This is a very simple form that will create an image, a text field, a hidden field with the hashed value of the image, and a submit button. Obviously this is only part of a form that you would want. Since captcha is used in much more than just login forms these days, I have slimmed this form to just the captcha portions, you would fill in the form with other fields as you need them.

Please note, I have used an image captcha here for example purposes only. You can use any type of captcha you like and the same principals will apply.

After this form is submitted you will then need to process your data.

As you can see this is a fairly simple method of passing the data. I would rather have preferred to keep the captcha on the session instead of revealing it to the form, but this method can be useful.

Now, we all know that there are a lot of ways to attack this code by submitting the form with various values in the two fields. Captcha should never be your only form of defense against unwanted users or attacks. I suggest you read up on: XSRF protection, ‘get’ injections, ‘post’ injections, and at the very minimum, have ample use of <cfqueryparam> tags.

Imagine this. Everytime you open a page on your website, the Application page is run.

On the Application.cfm page, each line is run in sequence every time.
If you load many APPLICATION variables or SESSION variables or other ‘environment’ variables, then you are recreating them, every time you open a page on the server. This is a lot of work for the CF server and can cause slowages on even the smallest websites.

On the Application.cfm page, only the code that is necessary is run.
Examples:
These 3 sections are common sections in an Application.cfc page.

1. onApplicationStart
2. onSesssionStart
3. onRequestStart

The ‘application start’ is the first time an application (the website) is run on the server, or after it has timed out. Therefore the code in the onApplicationStart section will only run at the time the website runs for the first time on the server, or after a timeout. (or reboot of the server)

The ‘session start’ is the first time a unique web browser visits an application (the website), or after the session cookies have been erased. Therefore the code in the onSessionStart section will only run at the time a web browser starts its progress through your site.

The ‘request start’ is every time a page is called on the web server. Therefore the code in the onRequestStart will always run when a new page is requested (or a page is ‘refreshed’)

There are many possible sections on the ‘Application.cfc’ page, but the above are the most common. Hopefully you can see how a cfc can severly reduce the stress on a coldfusion server.

Let’s say that you have large language files that you load into the system in order to easily change from one language to another. In the past you might have called these variables lang.welcome = ‘Welcome’. Well, you could place these language files in the application.cfc – onApplicationStart section, and only load them when the application starts. This would reduce the overhead of lines of code that was needed to start each page.

You could make that into a structure:
Application.lang[‘en’].welcome = ‘Welcome’;
Then in the onRequestStart you can change the ‘session.lang’ variable based on the most recent choice of the user, and call each variable in this manner.
Application.lang[session.lang].welcome.

This would make it so that you would only load the multitude of line of code that describe the language variables into the application scope once, but be able to call the values on each page load.

With an Application.cfm page, you would have to load each language file every single time you loaded the page.

The benefits don’t stop there. There are a few additional ‘sections’ of an Application.cfc page that can benefit ColdFusion developers.

onError is used to capture page errors and deal with them in any fashion that the developer sees fit. This is a huge advance over the limitations of the <cferror> tag.

The onMissingTemplate section can be used to capture requests for ‘.cfm’ pages that don’t exist (or no longer exist) on your site. I have used this in the past to show a brief ‘page not found’ error to the user, then display a search result of possible matches to what the user ‘might’ have been looking for. Certainly a whole lot better than the static ‘dead end’ page that apache or IIS want to show the user.

I encourage you to have some fun testing and experimenting with the different sections of the Application.cfc page, only a few of the sections are listed here.

First off, the form page.
Try this simple form:

When a user fills out the form in their local browser and clicks on the submit button, the file will be sent automatically from the user’s computer to your server. In the ‘form’ tag above, the ‘method=post’ tells the form to send all information in as a ‘post’ form (not as part of the url string). The ‘action’ parameter tells the form which page to load after the form is submitted. The ‘enctype=multipart/form-data’ tells the form that there is a file attached to the form that needs to be sent to the server (without this, the file will not be received by the server at all).

So, here are the steps so far:

1. The user opens your ‘uploadfile.html’ page in their browser. (You could have called this page anything ‘upload.cfm’, ‘uf.html’, etc)
2. The user clicks on the ‘browse button’ in the form and chooses which file on their local computer to send to your server.
3. The user clicks on the ’submit’ button.
4. The file is sent with the form to your server
5. Your web server recognizes the ‘multipart/form-data’ enctype and accepts the file, saving it in a temporary (temp) directory on the web server.
6. Your web server retrieves the ‘action’ page (getfile.cfm, could have been called anything as long as it is a CF page) and processes it.

Next, in order to actually use the file, you will need to save it into a ‘permanent’ directory on your webserver.
Try this simple CF page:

The misleading part? The action says ‘upload’. Most people (myself included) read that to mean ‘upload from the users computer’. Which can lead the programmer to believe that the file stays on the user’s computer until this command is run. Which can also lead the programmer to believe that they have some minutia control over the user’s computer. What the ‘upload’ really means is ‘copy from temp directory’ or ‘upload to a permanent directory’.

So we pick up our server activity steps from where we left off above. (web server retrieves the ‘action’ page)

1. Since the action page is a .cfm page the web server sends the page to the ColdFusion engine.
2. The ColdFusion engine sees the cffile upload command and;
   • Copies the file from the temp directory to the specified destination directory
   • If the copy was successful (no ‘permission’ errors), then the temp directory file is deleted
3. ColdFusion creates a structure variable called ‘cffile’ to contain all of the information returned by the cffile action
4. After ColdFusion engine is done with the file, it is sent back to the webserver to be sent as a ’static’ html page to the user’s browser.

This is how you upload a file from the user’s browser to a directory on your web server. It is important to mention that this is an example of the most simple of cases. There are other actions that you should take when uploading a file. For instance, you should determine if you want the filename to be unique. You should limit the file types to those types you are allowing to be uploaded. You probably don’t want anyone to upload a .cgi, .pl, .exe, etc that may ‘compromise’ your web server.

Something I would like to address, that has come up a few times, is this:
A certain browser (ie) made by the same company that makes a certain popular operating system (windows) sends the user’s directory information for the file along with that file to the webserver. You can view it by displaying the ‘cffile.CLIENTDIRECTORY’ variable, after performing the cffile tag. It is important not to rely on this information. Unless you can guarantee that all browsers in your system will be IE (or at least IE7) then this information will not be available for all browsers. The reason is due to the ’sandbox’ rules. These rules are there to protect the user from web sites that might want to do too much and possibly jeopardize the user’s system. ‘IE’ has always broken those rules where it sees fit, but other browsers such as Netscape (now dying off), Firefox, Safari, etc respect the sandbox and don’t send that information.

1. Block tags or break tags.

   This is probably the most familiar method to anyone entering ColdFusion. I have shown both of these examples using the HTML paragraph tags, but you can substitute for any line-breaking code. (<br />, <div></div>. etc)

   
   

   Regular record set:

   
   <cfoutput query=”[yourqueryname]”>

   <p>#[columnname]#</p>

   </cfoutput>
   

   
   

   Grouped record set:

   <cfoutput query=”[yourqueryname]”>

   #[sectionname]#<br>

   <cfoutput>

   <p>#[columnname]#</p>

   </cfoutput>

   </cfoutput>
   

2. Tables - Horizontal.

   After working with HTML for a while you will recognize this code as a simple list/report layout.

   
   

   Regular record set:

   <table>

   <cfoutput query=”[yourqueryname]”>

   <tr>

   <td>#[columnname]#</td>

   </tr>

   </cfoutput>

   </table>
   

   
   

   Grouped record set:

   <table>

   <cfoutput query=”[yourqueryname]”>

   <tr>

   <th>#[sectionname]#</th>

   </tr>

   <cfoutput>

   <tr>

   <td>#[columnname]#</td>

   </tr>

   </cfoutput>

   </cfoutput>

   </table>
   

3. Tables - Vertical.

   This is similar to the system above with the addition of a ‘counter’. What you do is decide how many vertical results you want to display before ‘breaking’ to the next line of results. I have used 4 results, but choose what you need. I have moved the ‘<tr>’ to the outside of the cfoutputs and have added a to determine if the code should insert a table row termination and start tag. I had previously left out the code that I am adding using this editing color. I had left it out intentionally to keep the ‘concept’ of the process simple and clear for the new developer. It has been brought to my attention that it can end in badly formed HTML (this was the least of my concerns).

   
   

   Regular record set:

   <table>

   <tr>

   <cfoutput query=”[yourqueryname]”>

   <td>#[columnname]#</td>

   <cfif currentrow mod 4 eq 0 and currentrow neq recordcount></tr><tr></cfif>

   </cfoutput>

   </tr>

   </table>
   

   
   In the grouped example, I have added an additional cfif to check to see if the loop ‘did not’ end on a multiple of 4 AND it is not the very first record in the query. I have also added a variable that carries the row count of every breaking <tr> in the data displays so that it can be checked against the currentrow in the ‘group’ and not print two recurring breaking <tr> groups together.
   
   
   

   Grouped record set:

   <table>

   <tr>

   <cfoutput query=”[yourqueryname]”>

   <cfif currentrow mod 4 neq 0 and currentrow neq 1 and currentrow neq lastbreakrow ></tr><tr></cfif>

   <th colspan=”4”>#[sectionname]#</th>

   </tr>

   <tr>

   <cfoutput>

   <td>#[columnname]#</td>

   <cfif currentrow mod 4 eq 0> </tr><tr></cfif>

   </cfoutput>

   </cfoutput>

   </tr>

   </table>
   

4. Tables – Horizontal AND Vertical (Newspaper).

   This is similar to the system above however instead of running the records left to right, we will run them top to bottom for ½ the records and then start at the top again for the 2nd half. (you can also do this for thirds, fourths, fifths, etc).

   
   

   Regular record set:

   <table>

   <tr>

   <td>

   <cfoutput query=”[yourqueryname]”>

   #[columnname]#

   <cfif currentrow eq round(recordcount / 2)></td></tr><tr><td><cfelse><br /></cfif>

   </cfoutput>

   </td>

   </tr>

   </table>

   
   

   Grouped record set:

   <table>

   <tr>

   <td>

   <cfoutput query=”[yourqueryname]”>

   <p>#sectionname]#</p>

   <cfoutput>

   <p>#[columnname]#</p>
   
   <cfif currentrow eq round(recordcount / 2)></td></tr><tr><td></cfif>

   </cfoutput>

   </tr>

   </cfoutput>

   </table>
   

This is certainly not the only methods available, nor will they be the best formatted versions for your needs, but they should hopefully help you get pointed in the right direction to have your data displayed the way you wanted it.