When you design a ColdFusion application, you must structure its contents into directories and files, also known as mapping the directory structure. This activity is an important step in designing a ColdFusion application. Before you start building the application, you must establish a root directory for the application. You can store application pages in subdirectories of the root directory.

The following sections describe how ColdFusion uses application-specific pages and how you can organize your application pages in a directory structure.

How ColdFusion finds and process application definition pages

ColdFusion uses the following rules to locate and process the Application.cfc, Application.cfm, and OnRequestEnd.cfm pages that define application-specific elements. The way ColdFusion locates these files helps determine how you structure an application.

Each time ColdFusion processes a page request it does the following:

1. When ColdFusion starts processing the request, it does the following:
   • It searches the page's directory for a file named Application.cfc. If one exists, it creates a new instance of the CFC, processes the initial events, and stops searching. (ColdFusion creates a new instance of the CFC and processes its initialization code for each request.)
   • If the requested page's directory does not have an Application.cfc file, it checks the directory for an Application.cfm file. If one exists, ColdFusion logically includes the Application.cfm page at the beginning of the requested page and stops searching further.
   • If the requested page's directory does not have an Application.cfc or Application.cfm file, ColdFusion searches up the directory tree and checks each directory first for an Application.cfc file and then, if one is not found, for an Application.cfm page, until it reaches the root directory (such as C:\). When it finds an Application.cfc or Application.cfm file, it processes the page and stops searching.
2. ColdFusion processes the requested page's contents.
3. When the request ends, ColdFusion does the following:
   • If you have an Application.cfc, ColdFusion processes the CFC's onRequestEnd method and releases the CFC instance.
   • If you do not have an Application.cfc, but do have an Application.cfm page, ColdFusion looks for an OnRequestEnd.cfm in the same directory as the Application.cfm page ColdFusion uses for the current page. ColdFusion does not search beyond that directory, so it does not run an OnRequestEnd.cfm page that resides in another directory. Also, the OnRequestEnd.cfm page does not run if there is an error or an exception on the application page, or if the application page executes the cfabort or cfexit tag.

The following rules determine how ColdFusion processes application pages and settings:

• ColdFusion processes only one Application.cfc or Application.cfm page for each request. If a ColdFusion page has a cfinclude tag pointing to an additional ColdFusion page, ColdFusion does not search for an Application.cfc or Application.cfm page when it includes the additional page.
• If a ColdFusion page has a cfapplication tag, it first processes any Application.cfc or Application.cfm, and then processes the cfapplication tag. The tag can override the settings from the application files, including the application name and the behaviors set by the cfapplication tag attributes.
• You can have multiple Application.cfc files, Application.cfm files, and cfapplication tags that use the same application name. In this case, all pages that have the same name share the same application settings and Application scope and can set and get all the variables in this scope. ColdFusion uses the parameter settings of the cfapplication tag or the most recently processed file, if the settings, such as the session time-out, differ among the files.

Defining the directory structure

Defining an application directory structure with an application-specific root directory has the following advantages:

Development: The application is easier to develop and maintain, because the application page files are well-organized.

Portability: You can easily move the application to another server or another part of a server without changing any code in the application page files.

Application-level settings: Application pages that are under the same directory can share application-level settings and functions.

Security: Application pages that are under the same directory can share web server security settings.

When you put your application in an application-specific directory hierarchy, you can use a single application definition (Application.cfc or Application.cfm) page in the application root directory, or put different application definition pages that govern individual sections of the application in different directories.

You can divide your logical web application into multiple ColdFusion applications by using multiple application definition pages with different application names. Alternatively, you can use multiple application definition pages that specify the same application name, but have different code, for different subsections of your application.

The directory trees in the following image show two approaches to implementing an application framework:

• In the example on the left, a company named Web Wonders, Inc. uses a single Application.cfc file installed in the application root directory to process all application page requests.
• In the example on the right, Bandwidth Associates uses the settings in individual Application.cfc files to create individual ColdFusion applications at the departmental level. Only the Products application pages are processed using the settings in the root Application.cfc file. The Consulting, Marketing, and Sales directories each have their own Application.cfc file.