Reuse

Imagine building a Web site with thousands of pages and a copy of the header on each page. Sometime during the life of a successful Web site, changes will be wanted or needed. The developers must go in and change the header code on every page. Obviously this is not a position in which you want to find yourself.

Code reuse has many benefits, one of the most important of which occurs when you need to change code that is viewed on many pages. Other obvious benefits include using code that is already written, tested, and debugged.

Reuse and Including Files

One way to implement reuse in ColdFusion is to use the <cfinclude> tag. In essence, this tag takes code from one page, called the included page, and puts it into the page that contains the <cfinclude> tag, called the calling page. Therefore, the code for a header could be stored in a central location and included in every page where it is needed. The <cfinclude> tag has only one attribute, template, which is the path to the page to include.

The path can be specified either as a relative path or as a ColdFusion mapping. If the first character after the quotation mark in the template attribute is a forward slash (/), the path uses a ColdFusion mapping.

The included page assumes the directory of the calling page. This means that you must be very careful using relative paths in the included code because they are often used at many different directory levels in the Web site. You can find solutions to this issue in the next two sections of this chapter.

Variables are not protected in the calling or included pages. This means that a variable in the calling page can be directly displayed and manipulated in the included page. Conversely, any variables from the included code can later be displayed and manipulated in the calling page after the <cfinclude>. Later in this chapter, you will see that this capability can work to your advantage.

ColdFusion Mappings

ColdFusion mappings are directory aliases created in ColdFusion Administrator. A virtual directory name can be associated with an actual physical directory path. For example, a ColdFusion mapping called udfs can be mapped to the physical directory c:\cfusionmx7\wwwroot\udfs\. You then could write a <cfinclude> tag as follows:

 <cfinclude template="/udfs/string.cfm"> 

The use of a ColdFusion mapping offers some advantages. No matter where in the directory structure of your Web site the header is called, the path specified in the template attribute of the <cfinclude> can be the same. You don't need to worry about a relative path to the header. If the Web page is moved in the directory structure, you don't need to change the path to the header.

If a mapping isn't used and a major overhaul of the site changes the actual directory where the templates are stored, you would have to edit every <cfinclude>. If a mapping is used, you would need to make only one change in ColdFusion Administrator.

Web Server Mappings

ColdFusion mappings are only seen by ColdFusion and may only be used within ColdFusion code. This means that they cannot be used outside of ColdFusion, for example, in an <img src> tag. As images are served by the Web server (and not by ColdFusion), a ColdFusion mapping would not be of any use, The solution is to use Web server mappings. Just as ColdFusion mappings allow a virtual name for a physical directory that can be used in ColdFusion tags, so can Web server mappings be used with HTML tags where needed.

Consider a Web server mapping, or virtual directory as it is called in some Web server software, named images. Say it is mapped to the physical directory of c:\cfusionmx7\wwwroot\imgs\. You then can use this mapping in the header code where needed to be sure the images are correctly found and no broken links appear. For example, you could use the following:

 <img src="/books/2/445/1/html/2//images/car.gif"> 

If this tag is used in the header, it does not matter where it is includedthe link will function correctly.

Variable Scoping and <cfinclude>

Remember that variables are not protected either in calling or included pages, meaning that a variable from one page can be displayed or manipulated by the other. At first, this capability may seem like a negative factor, but sometimes it is just what you need.

Some search engines use the HTML title as part of the search report. If you include the header as suggested earlier, every title will be the same. Remember that variables set in the calling page can be used in the included page. So you could build something like this for the header:

 <html> <head>  <title>  <cfoutput>#VARIABLES.TheTitle#</cfoutput>  </title> </head> 

Then, when you're building the home page, you could use this code:

 <cfset TheTitle="PassThatTest.com Home Page"> <cfinclude template="/templates_mapping/header.cfm"> 

That way, every page would simply set the title before using the <cfinclude> tag.

If many parts of the header are changeable, as in a navigation system, a query could be performed before the <cfinclude> and the information from the database used in the header.

CAUTION

When you include a page, the <cfoutput> block does not carry into the included page. This means that if the <cfinclude> is inside a <cfoutput> block, any ColdFusion variables to be displayed on the included page must be surrounded with another <cfoutput> block.