Mastering ColdFusion MX Arman Danesh; Raymond Camden; Selene Bainum; Guy Rish

Transcription

1 SYBEX Sample Chapter Mastering ColdFusion MX Arman Danesh; Raymond Camden; Selene Bainum; Guy Rish Chapter 9: Including Outside Code Copyright 2002 SYBEX Inc., 1151 Marina Village Parkway, Alameda, CA World rights reserved. No part of this publication may be stored in a retrieval system, transmitted, or reproduced in any way, including but not limited to photocopy, photograph, magnetic or other record, without the prior agreement and written permission of the publisher. ISBN: SYBEX and the SYBEX logo are either registered trademarks or trademarks of SYBEX Inc. in the USA and other countries. TRADEMARKS: Sybex has attempted throughout this book to distinguish proprietary trademarks from descriptive terms by following the capitalization style used by the manufacturer. Copyrights and trademarks of all products and services listed or described herein are property of their respective owners and companies. All rules and laws pertaining to said copyrights and trademarks are inferred. This document may contain images, text, trademarks, logos, and/or other material owned by third parties. All rights reserved. Such material may not be copied, distributed, transmitted, or stored without the express, prior, written consent of the owner. The author and publisher have made their best efforts to prepare this book, and the content is based upon final release software whenever possible. Portions of the manuscript may be based upon pre-release versions supplied by software manufacturers. The author and the publisher make no representation or warranties of any kind with regard to the completeness or accuracy of the contents herein and accept no liability of any kind including but not limited to performance, merchantability, fitness for any particular purpose, or any losses or damages of any kind caused or alleged to be caused directly or indirectly from this book. Sybex Inc Marina Village Parkway Alameda, CA U.S.A. Phone:

2 Chapter 9 Including Outside Code You ve probably noticed by now that ColdFusion templates can grow to be much longer and more complex than the average HTML file. In addition, just as with HTML, there will inevitably be sections of ColdFusion code that you will want to reuse repeatedly throughout an application or a website. For these reasons, you need to be able to include ColdFusion code from other files in another template. In this chapter, you will look at how to do this with the cfinclude and cfmodule tags. In considering the combining of code from different templates, it is also necessary to look at variable scope issues; that is, where does a variable exist in one or both of the templates involved? Featured in this chapter: Using cfinclude to include code within the current template Understanding variable scope Using cfinclude to Include Code within the Current Template Anyone who has done advanced work with HTML has probably encountered server-parsed HTML. With server-parsed HTML files (generally ending in the extension.shtml), it is possible to use a variety of special tags that are processed on the server side before sending the results to the browser. Most flavors of server-parsed HTML offer one or more tags for including the contents of another HTML file in the current file. This is generally used for commonly recurring elements of pages within a site. For instance, if a site always has the same title or menu bar across the top of each page, this code could be placed in a single file and then included in every page on the site. The great advantage of this comes in the area of site maintenance: You can modify this global element for all pages by making changes to a single file. No longer is it necessary to edit all pages or perform global search-and-replace functions to make the necessary alterations to the site. ColdFusion offers a similar capability. The simplest way to achieve this result is by using the cfinclude tag. Although it is possible to devise ways of using your web server s server-parsed HTML

3 86 Chapter 9 INCLUDING OUTSIDE CODE to include a ColdFusion template into an HTML file, it is generally best to stick to ColdFusion for the complete solution. This ensures that the correct parsing and processing of both files occurs. The cfinclude Tag The cfinclude tag is quite simple in that it has only one required parameter: template. This parameter indicates the logical path of another ColdFusion template to include in the current template. The mechanics are simple: The code of the specified template is added to the current template at the point where the cfinclude tag is located and is processed as if it were part of the current page. Let s look at how this works. Consider the code in Listing 9.1. It provides a title banner and menu for a simple site. ColdFusion is used to highlight the correct menu item based on information set in the variable chosen in the template containing the cfinclude tag. Listing 9.1: A Standard Page Header (head.cfm) <!--- Name: /spiderbytes/c09/head.cfm Description: An Example Standard Page Header ---> <h1>using CFINCLUDE</h1> <cfif chosen is 1> <strong>the Syntax</strong> <a href= syntax.cfm >The Syntax</a> <cfif chosen is 2> <strong>examples</strong> <a href= examples.cfm >Examples</a> <cfif chosen is 3> <strong>alternatives</strong> <a href= alternatives.cfm >Alternatives</a> </cfif> Of course, an immediate problem appears to exist with this template: None of the cfif tags will work because the chosen variable does not exist. But this is fine because the template is designed to be included in the other templates in the site. For instance, Listing 9.2 is the home page of the site that includes the menu and title header template. Listing 9.2: Including a template (cfinclude.cfm) <!--- Name: /spiderbytes/c09/cfinclude.cfm Description: An Example of Including a Template --->

4 USING CFINCLUDE TO INCLUDE CODE WITHIN THE CURRENT TEMPLATE 87 <cfset chosen=0> <cfinclude template= head.cfm > <hr> This site is designed to provide reference information about the CFINCLUDE tag. Choose an option from the menu above. The end result is that the code from the head.cfm template is included in the home page template; both are processed as one large template that looks like the following: <cfset chosen=0> <h1>using CFINCLUDE</h1> <cfif chosen is 1> <strong>the Syntax</strong> <a href= syntax.cfm >The Syntax</a> <cfif chosen is 2> <strong>examples</strong> <a href= examples.cfm >Examples</a> <cfif chosen is 3> <strong>alternatives</strong> <a href= alternatives.cfm >Alternatives</a> </cfif> <hr> This site is designed to provide reference information about the CFINCLUDE tag. Choose an option from the menu above. The results look like those in Figure 9.1. Figure 9.1 cfinclude can be used to include titles and menus.

5 88 Chapter 9 INCLUDING OUTSIDE CODE It should be noted that the code that generates the simple menu in your head.cfm template (the series of cfif tags) is designed to highlight the current selection with a strong font if chosen is set to 1, 2, or 3 (indicating which selection has been chosen) or to highlight no selection if the value of the variable is set to anything else. In the home page example you just looked at, chosen is set to 0, and the result is that all three of the menu choices are active links. By way of comparison, consider Listing 9.3, in which chosen is set to 3. Listing 9.3: Included Template with chosen=3 (cfinclude.cfm) <!--- Name: /spiderbytes/c09/cfinclude2.cfm Description: An Example of Including a Template with chosen=3 ---> <cfset chosen=3> <cfinclude template= head.cfm > <hr> This site is designed to provide reference information about the CFINCLUDE tag. Choose an option from the menu above. This produces results like those in Figure 9.2. Notice how the third option in the menu is highlighted with a bold font and is not a link. Figure 9.2 One menu option is bold and inactive. Note The template attribute takes a logical path as a value. That is, the template to include should be specified as a relative path from the current template instead of as a complete URL. For instance, to include a template in the same directory as the current template, simply specify the file by name. To include a template in the parent directory of the one containing the current template, use the form../template.cfm.

6 UNDERSTANDING VARIABLE SCOPE 89 An Example of Using the cfinclude Tag The SpiderBytes application we use throughout this book provides a practical example of the use of the cfinclude tag. At the top of the Application.cfm file, you see two cfinclude tags: <cfif not isdefined( application.initialized ) or isdefined( url.reinit )> <cfinclude template= includes/global_vars.cfm > </cfif> <cfinclude template= includes/udf.cfm > First, a brief discussion is needed about the Application.cfm which is introduced in depth in Chapter 19, Implementing the ColdFusion Web Application Framework. Essentially, Application.cfm is included at the start of every template that s in the same directory as the Application.cfm file and in all subdirectories of that directory. This happens automatically without a cfinclude tag, and this automatic process is handled by ColdFusion without programmer intervention. Essentially, you use it for universal code that must operate before each template in your application. Let s consider the two cfinclude tags found in the SpiderBytes Application.cfm file. The first tag is in a cfif block. This file is included the first time the application is run (the isdefined( application.initialized ) condition) or when conditions exist that the state of the application must be reinitialized to its starting point (the isdefined( url.reinit ) condition). The second tag includes the udf.cfm file, which contains a set of user-defined functions (UDFs) for use throughout the application. UDFs are discussed in Chapter 31, Creating User-Defined Functions. By placing this cfinclude tag in Application.cfm, you ensure that the UDFs are available in all templates in the application without explicitly using the cfinclude tag in every template. Understanding Variable Scope The concept of scope is fairly simple. Scope simply refers to the context in which a variable exists or doesn t. In its most simple state, a variable s scope starts when it is first declared (for instance, when a value is assigned to it using cfset) in a template and lasts to the end of the template. This is best understood by example. In the following example, the cfoutput tag can be used to display the value of the variable sample only because the variable sample came into existence earlier in the template using the cfset tag: <cfset sample= Some Text > <cfoutput>#sample#</cfoutput> However, if the order of these lines is reversed, then cfoutput is trying to access the variable sample outside the scope of the variable (that is, before it has been created): <cfoutput>#sample#</cfoutput> <cfset sample= Some Text > In this case, an error similar to the one in Figure 9.3 will be produced. More subtleties exist when multiple templates are involved. When you used cfinclude, the code of the included template became part of the calling template. This means it is part of the same scope. The code of the calling template can directly refer to variables contained in the code of the template being included and the other way around.

7 90 Chapter 9 INCLUDING OUTSIDE CODE This is why, for instance, when cfinclude was used, the template was able to directly reference the variable chosen, which was used to generate the header and menu. Figure 9.3 Accessing a variable outside its scope produces an error. Where Do We Go from Here? In this chapter, you learned about the useful cfinclude tag for combining more than one template by including one template in another. In the next chapter, you will move on to an extremely important aspect of ColdFusion: creating databases and tables. Databases are what give ColdFusion its power. With databases, ColdFusion applications can manipulate and process large amounts of information quickly and easily for the user and at the request of users. This allows the creation of sophisticated, interactive, dynamic websites.