Reusing Code and Writing Functions
- To include files with <cfinclude>.
- To to use Application.cfm and OnRequestEnd.cfm.
- To to write user-defined functions.
Writing reusable code results in time and money savings, more consistent and bug free code, and the ability to hide complex code from less seasoned developers. We'll cover several basic code reuse techniques in this lesson.
Including Files
Including files in ColdFusion is made simple with the <cfinclude> tag, which takes a single attribute: template. The template attribute points to the file to include. ColdFusion first looks for the included file relative to the current directory. If it cannot find it, it then looks in directories mapped in ColdFusion Administrator.
<cfinclude template="path_to_file">
Note that a ColdFusion tag cannot be opened in a calling file and then closed in an included file or vice versa. The ColdFusion code in the included file must be syntactically valid on its own.
A Note on Security
If included files are under the web root, they can be accessed just as any other file can. If they have an extension such as .inc then the browser may display them as plain text. With other extensions, the browser may attempt to download the file. If the included file is a ColdFusion file and a user navigates to it, the server will try to process the file and may return errors. As a precaution, you may want to place your included files in a directory above or outside of the web root. This will prevent users from accessing the files directly.
Code Sample: ReusingCode/Demos/index.cfm
<html> <head> <title>Runners Home™</title> <link href="Styles/Main.css" rel="stylesheet"> </head> <body> <cfinclude template="Includes/NavBar.cfm"> <div id="greeting"> <cfoutput>The time is #TimeFormat(Now(),"h:mm tt")# on #DateFormat(Now(), "mmmm d, yyyy")#.</cfoutput> </div> <table align="center" cellpadding="10" cellspacing="0" width="100%" height="100%" id="hometable">---- Code Omitted ----</table> <cfinclude template="Includes/Footer.cfm"> </body> </html>
The above code is relatively straightforward. It contains to included files: Includes/NavBar.cfm and Includes/Footer.cfm.
Application.cfm and OnRequestEnd.cfm
Whenever a ColdFusion page is called, the ColdFusion Application Server checks the current directory for a file called Application.cfm. If Application.cfm is not found in the current directory, ColdFusion looks for the file in the parent directory and continues to look up the tree until it gets to the root directory of the file system. As soon as the file is found, ColdFusion stops looking up the tree and prepends the found Application.cfm to the called page.
Application.cfm is often used for the following tasks:
- Control state management variables and set the application name with <cfapplication>.
- Set default global variables such as data source names and file paths.
- Set custom error handling using <cferror>.
Application.cfm should not used for including code to be output to the browser, such as a common header.
When and only when an Application.cfm file is found, ColdFusion will also look for a file called OnRequestEnd.cfm in the same directory. If it finds OnRequestEnd.cfm it will append it to the called file. OnRequestEnd.cfm is sometimes used for outputting debugging information or logging information about the page.
User-defined Functions
User-defined functions are used to make common tasks easier and to make code more modular and easier to read.
Defining and Calling Functions
Functions are defined with the <cffunction> tag as follows. Like built-in functions, user-defined functions can receive arguments. Arguments are defined using the <cfargument> tag. If no default is defined with the default attribute, then the argument is required.
<cffunction name="function_name" returntype="type"> <cfargument name="arg" type="type" default="default"> </cffunction>
Here is an example user-defined function for adding numbers.
Code Sample: ReusingCode/Demos/UDF.cfm
<html> <head> <title>User-defined Function</title> </head> <body> <cfset total = addNums(1)> <cfoutput>#total#</cfoutput> </body> </html> <cffunction name="addNums" returntype="numeric"> <cfargument name="num1" type="numeric"> <cfargument name="num2" type="numeric" default="0"> <cfargument name="num3" type="numeric" default="0"> <cfset sum=num1 + num2 + num3> <cfreturn sum> </cffunction>
Notice that user functions are called in the same way as built-in functions.
Reusing Code and Writing Functions Conclusion
Using includes and functions are two common ways of writing reusable code. Very often developers will save common functions in an include file (e.g, functions.inc), so they don’t have to copy and paste functions into scripts to make use of them.