Many years ago, the first time that I tried to extend a child application.cfc to the root application component using the extends argument in the cfc and received the following message: "Could not find the ColdFusion component or interface xxx'. This caused enourmous frustration until I finally discovered how to extend application components using mapping.

Table of Contents

Extending a Child Application Component Using a Proxy

The problem when extending a child Application.cfc to its parent Application.cfc using the extends argument is that both the root and the subfolder components have the same name, i.e., Application.cfc, and ColdFusion can't properly identify what component to extend. Finally, after some serious investigation, Sean Corfield documented a solution to create a proxy.cfc that resides in the same root directory as the root Application.cfc, and the Application.cfc in the subfolder extends an empty Proxy.cfc that extends the root application cfc like so:

root directory: Application.cfc
This root Application.cfc does not extend anything

Also in the root directory: Proxy.cfc
Proxy.cfc has the following code; it's essentially empty. The only thing that the Proxy.cfc does is to extend the Application.cfc that is in the same directory:

<cfcomponent extends="Application">
<!--- This is an empty cfc that is used to extend the Application.cfc in the admin folder to the base Application.cfc in the root directory. --->
</cfcomponent>

The child Application.cfc, responsible for securing the contents of the admin folder, extends the Proxy.cfc to gain the methods and properties of the Application.cfc in the root directory:

<cfcomponent displayname="Admin" extends="Proxy.cfc">
<!-- Lots of code --->
</cfcomponent>

This approach was a godsend, and it was heavily blogged. Ben Nadel has made several helpful posts, which I will share at the bottom of this article.

This works well unless you're using virtual directories on a hosted domain or a server. In this case, we are in the same original boat we started from. Now we are back into the "Could not find the ColdFusion component or interface xxx' hell!

However, there is a solution to this tricky problem; we must also use mapping.

Extend a Child Application Component Using ColdFusion Mapping

It is a common misnomer that you can't use mapping to extend components. I don't know where this misconception originated, but it is untrue.

Occasionally, we must use mapping to solve annoying problems. This particular site was hosted by hostek.com. They were a fine company to deal with prior to being sold, but the original server had some idiosyncrasies due to the directory structure. Here, when I used the Proxy.cfc method to extend the logic from the base Application.cfc to the Application.cfc in the admin folder, I received the dreaded 'could not find the ... component' error.

I was dismayed when I first saw it, thinking "not this again...", so I turned to ColdFusion CFC mapping. Mapping tells ColdFusion where to find the file and what the file relationships are.

Review

Let's review CFC structure that was just discussed. For example, imagine the following directory structure:
root directory: i.e. www.gregoryalexander.com/
subdirectory: www.gregoryalexander.com/admin/

As we discussed, we have an Application.cfc and the Proxy.cfc in the root directory. Our child application component, Application.cfc is in the 'admin' subdirectory. The Proxy.cfc extends the Application.cfc, also in the root directory, and the Application.cfc in the subdirectory (admin) extends the Proxy.cfc in the root directory. 

Now we also need to add the following mapping to the root application.cfc.

Mapping Logic

This mapping logic should be near the top of the root Application.cfc and not be within any of the Application.cfc event handlers (onApplicationStart, onApplicationRequest, etc). This mapping code does not need to be anywhere else other than the root Application.cfc:

<!-- Define application-specific mappings. These will be used to point to this application.cfc when we extend it in the admin/Administrator.cfc template using the Proxy.cfc that resides in the same folder as this Application.cfc. --->
<cfset this.mappings="structNew()" />
<!-- Mapping for the ROOT Application.cfc --->
<cfset this.mappings["rootCfc"]=getDirectoryFromPath(getCurrentTemplatePath()) />
<!-- Mapping for the admin SUBDIRECTORY Application.cfc. Note the admin prefix is attached at the end of this line. This points to the admin folder. --->
<cfset this.mappings["adminCfc"]= getDirectoryFromPath( getCurrentTemplatePath() & "/admin" )) />

I used rootCfc to identify the Application.cfc in the root directory, whereas adminCfc applies to the directory of the Application.cfc (in the admin directory). These variables can be named anything. Note that the "/admin" string at the end of the adminCfc mapping points to the 'admin' folder, which is a subdirectory. Now that we have the mappings in the root Application.cfc, we need to apply them to the extends statement in Application.cfc located in the subdirectory. In the /admin/Application.cfc template like so:

<cfcomponent displayname="xxx" sessionmanagement="xx" clientmanagement="xx" extends="rootCfc.Proxy">
<!-- Logic --->
</cfcomponent>

Of course, rootCfc tells the Application.cfc in the subdirectory to look for the Proxy.cfc template in the root directory. Like other 'extend' statements, you don't need to specify '.cfc' at the end of Proxy. You don't need to use this 'extend' mapping in either the root Proxy.cfc or Application.cfc templates. They can already find each other as they are both in the same root directory.

<cfcomponent extends="Application">
<!--- The Proxy.cfc extends the parent application.cfc --->
</cfcomponent>

Summary

For the sake of absolute clarity, the parent Application.cfc contains the mapping logic has the mappings for both the root and subdirectory.
This mapping logic should be near the top of the root Application.cfc, and must not be within any of the Application.cfc event handlers (onApplicationStart, onApplicationRequest, etc).

<cfset this.mappings="structNew()" />
<cfset this.mappings["rootCfc"]="getDirectoryFromPath(getCurrentTemplatePath())" />
<cfset this.mappings["adminCfc"]="getDirectoryFromPath( getCurrentTemplatePath() & "admin" )="" />

The Proxy.cfm also resides in the root directory, simply extends the Application and has no mapping logic:

<cfcomponent extends="Application">
<!--- The Proxy.cfc extends the parent application.cfc --->
</cfcomponent>

The child Application.cfc, in the admin folder, extends uses the mapping the variable used for the folder, with a dot and the name of the Proxy.cfc template without the .cfc extension.

<cfcomponent displayname="Admin" sessionmanagement="yes" clientmanagement="yes" extends="rootCfc.Proxy">
<!--- Lots of code. This uses mappings to extend the Proxy.cfc  --->
</cfcomponent>

 Further Reading:

Note: this article was orginally published on Janruary 30th 2021 and updated on March 9 2025. Unfortunately the original article was unintentinally mangled when I migrated to a new webserver.