CFINCLUDE

The CFINCLUDE tag will likely be your first encounter with code reuse when developing ColdFusion applications. The CFINClUDE tag enables you to embed existing ColdFusion templates into your current template by referencing the template names. Consider the following example:

 <!---This is the code for the template PageOne.cfm--->  <HTML>       <HEAD>            <TITLE>Page One</TITLE>       </HEAD>  <BODY>  <H1>This is Page One!</H1>  </BODY>  </HTML>  <!---End of PageOne.cfm--->  <!---This is the code for the template PageTwo.cfm--->  <HTML>          <HEAD>                   <TITLE>PAGE TWO</TITLE>          </HEAD>  <BODY>  <H1>This is Page Two!</H1>  </BODY>  </HTML>  <!---End of PageTwo.cfm--->

As you can see from the preceding code sample, we have two independent CFM templates. When you run the first of these pages in a web browser, you'll get output similar to that shown in Figure 5.1.

Figure 5.1. Output of `PageOne.cfm`.

graphics/05fig01.gif

Similarly, running the second of these two templates results in output similar to Figure 5.2.

Figure 5.2. Output of `PageTwo.cfm`.

graphics/05fig02.gif

Suppose now that the code in PageTwo.cfm had to be included within the PageOne.cfm template exactly as it is currently written. To do this, you could simply write the code like this:

 <!---This is the code for the template PageOne.cfm--->  <HTML>       <HEAD>            <TITLE>PAGE ONE</TITLE>       </HEAD>  <BODY>  <H1>This is Page One!</H1>  <CFINCLUDE TEMPLATE="PageTwo.cfm">  </BODY>  </HTML>  <!---End of PageOne.cfm--->

After modifying the code for PageOne.cfm in this way, you're presented with the output shown in Figure 5.3.

Figure 5.3. Output of modified `PageOne.cfm`.

graphics/05fig03.gif

As you can see, CFINCLUDE enables you to embed the entire content of an existing CFML template at any point in another CFML template.

You can imagine the uses for this type of functionality. Assume that you have created a header table that needs to go at the top of the page on every page within your web application. By simply creating an include to hold this table, each page that needs to display this table can "include" it. This enables you to keep the central code in one place. Thus, if the header table ever needs modification, a modification to the source file also updates all the templates that are "including" this information.

Each CFINCLUDE example to this point has "included" templates that reside in the same directory as the template into which they are included. We'll refer to these as the calling template and the included template. Because the included templates have been in the same directory, we've been able to reference them just by naming them. We have not had to worry at all about traversing the directory structure of our application or web site.

Note, however, that you might not always want to lump all the templates into one directory. Toward that end, developers often use ColdFusion mappings to create an alias for a directory where all their included templates can be stored and easily accessed from anywhere in the application. Let's look at an example of using ColdFusion mappings with the CFINCLUDE tag:

 <!--- This is the code for the template PageOne.cfm --->  <HTML>       <HEAD>            <TITLE>PAGE ONE</TITLE>       </HEAD>  <BODY>  <H1>This is Page One!</H1>  <CFINCLUDE TEMPLATE="/AllIncludes/PageTwo.cfm">  </BODY>  </HTML>  <!--- End of PageOne.cfm --->

The difference might not be readily apparent. By beginning your included template reference with a forward slash (/), ColdFusion knows to look for a ColdFusion mapping that corresponds to the alias that you provide following the forward slash. Using ColdFusion mappings, you can store included templates outside the webroot directory structure.

Note

In this book, you'll see many examples in which included templates are referred to by using a ColdFusion mapping. Keep your eyes open.

ColdFusion mappings are created in the ColdFusion Administrator and apply only to pages that are processed by ColdFusion Server with CFINCLUDE or CFMODULE tags. To create a ColdFusion mapping, follow these simple steps:

In the ColdFusion Administrator, click Mappings under the Server Settings heading (see Figure 5.4).

Figure 5.4. ColdFusion Mappings page in ColdFusion Administrator.
Under Add/Edit ColdFusion Mappings, enter the name of the mapping. Make sure that the name is preceded by the forward slash (/).
Browse to or type the full path to the directory where the includes will be stored.
Click the Add button.

Your new mapping appears in the Active ColdFusion Mappings area at the bottom of the screen. You can now reference any template located within that mapped directory in your CFINCLUDE calls.

CFINCLUDE

CFINCLUDE

Figure 5.1. Output of PageOne.cfm.

Figure 5.2. Output of PageTwo.cfm.

Figure 5.3. Output of modified PageOne.cfm.

Figure 5.4. ColdFusion Mappings page in ColdFusion Administrator.

Figure 5.1. Output of `PageOne.cfm`.

Figure 5.2. Output of `PageTwo.cfm`.

Figure 5.3. Output of modified `PageOne.cfm`.