Have you ever wondered about the difference between the many kinds of mappings available to you when doing ColdFusion development? There is indeed a big difference between:

• Web server mappings
• ColdFusion administrator mappings
• The "home directory" for your domain on your Web server
• CF Studio development mappings
• Network drive mappings

Some people, if they even know each of these exists, find all this mapping business to be very confusing -- and it's not just newcomers to ColdFusion. If you've never heard of one or more of these, or have never quite understood them, we'll show you what they are and why they're very useful.

A Quick Quiz

If you think you do understand all five types of mappings, consider the following quiz to test your awareness. The answers to each and an explanation are provided at the end of the quiz.

1. True or False? In order for my files to be browseable on my Web server, I must place them in my server's "webroot" (whose location depends on the server used, but may be something like c:\inetpub\wwwroot or d:\htdocs), or one of its subdirectories.
2. True or False? I can allow users to browse files found in any directory on my Web server using ColdFusion administrator mappings.
3. True or False? I can use Web server mappings to create an alias or virtual path called \myappimages directory, where the real directory path is c:\inetpub\wwwroot\myproj\myapp\images, so that I can point to an image in that directory more easily (especially from a template in some other directory) with <IMG SRC="\myappimages\photo.jpg">.
4. True or False? I can achieve the same result in "c" using CF administrator mappings.
5. True or False? I have some custom tags I'd like to share with others, but I'm not allowed to place them in the shared cfusion/customtags directory. They're buried deep in my directory structure on the server as c:\inetpub\wwwroot\myproj\myapp\mytags. I can use a CF administrator mapping to create an alias or virtual path called \mytags, so that templates in any of my directories, or indeed any directory on the server, can easily access those custom tags using <CFMODULE TEMPLATE="\mytags\customtag.cfm">.
6. True or False? In "e" above, creating a CF administrator mapping for \mytags is the only way I could enable any template to call my custom tags when I couldn't put them in the shared custom tags directory.
7. True or False? Using Studio development mappings, I can browse files within Studio without having to open an external browser.
8. True or False? Using Studio development mappings, I can easily launch an external browser installed on my workstation, such as Netscape, without having to type in the URL on the browser.
9. True or False? If you can connect to your Web server within your LAN using a network drive mapping (such as your "g:" drive), while you can edit a file there within Studio, you cannot use the "internal browse" feature on such a template.

The Answers

Let's check the answers. Did you base any answers on what you've heard, perhaps, or on just a guess? If you've actually worked with each of the three types of mappings, you probably got them all right. But many people haven't worked with them all and probably missed a few because they don't have a complete understanding of the distinctions. So what are the answers?

1. False: While you CAN and often do place files in the webroot or one of its subdirectories, you can indeed place files anywhere on the server's file system as long as the Web server software can access that directory, and you've set up a Web server mapping.
2. False: As the last question stated, while you can place files in any Web server directory using a Web server mapping, the ColdFusion mappings have no effect on the ability of users to browse files on your server. They're used only to affect the operations of CF tags such as CFINCLUDE and CFMODULE.
3. True: This is one of many uses of Web server mappings, to create an alias or virtual path name to simplify naming of a path in various tags. They also provide a single place to update if the "images" directory were to be moved, rather than having to change a relative path reference to \myproj\myapp\images.
4. False: This is a frequent misunderstanding. While it's indeed true you can use CF mappings to set up an alias or virtual path name, they do not affect how tags like <IMG SRC> or <A HREF> will work. The CF administrator mappings only affect how certain tags, like CFMODULE and CFINCLUDE, will operate when executed within the ColdFusion server.
5. True. This is indeed one of the main uses of the CF administrator mappings, to simplify paths on CFINCLUDE and CFMODULE tags.
6. False: This one may trick folks. The fact is, this use of CFMODULE to call the mytags directory did not really require creating a new mapping. By default, there's a CF administrator mapping for "/" which is set to the root of the Web server. Therefore, any template on the server could already access those custom tags using the longer form: <CFMODULE TEMPLATE="\myproj\myapp\mytags\customtag.cfm">. But creating a mapping would make it shorter, and would also provide a single place to update if the mytags directory were moved. Of course, you could also specify a relative path to locate the file, but again a Web server mapping has the benefit of protecting the code if the mytags directory were moved somewhere that would cause the relative path to fail.
7. True: This is indeed the main use of the Studio development mappings feature.
8. True: This will be a hidden gem for some. While some know of using the Studio development mappings for browsing internally within Studio, you can also benefit from the mapping if you want to browse files in an external browser. You just need to set up Options>Configure External Browsers, as well. Then use F11 or the "View External Browser List" to launch the current file in an external browser.
9. False: This may be a huge discovery to some users. You absolutely can set up Studio to allow you to use the internal browse feature on a mapped drive. This is discussed in the Allaire documentation in Chapter 9 of the book "Using ColdFusion Studio".

So, how did you do? If you got them all right, congratulations. You're very skilled in the distinctions among the kinds of mappings. If you missed any, perhaps the explanations of the answers will give you enough direction to be able to use them more effectively.

If you would like a little more background on the significance of relative and absolute paths, as well as what a webroot-relative path is and why it's important to understand the difference, please see the associated article posted on the author's Web site at http://www.systemanage.com/cff/pathbasics.cfm. It also discusses the possibly different location of a webroot in an environment where several domains are hosted on the same server.

In this article, we want to focus more on the difference between the first two kinds of mappings discussed at the outset, Web server mappings, and ColdFusion administrator mappings.

We'll have to leave a more complete discussion of Studio mappings and drive mappings for a second part to this article.

Benefits of Mappings

As the quiz suggested, Web server and CF mappings can be easily confused with each other. Both mappings do offer some common benefits. They can:

• Allow several directories on a shared server to be accessed without long webroot-relative paths
• Allow you to locate and browse files in any directory, perhaps even outside the webroot
• Help make references to certain directories on your Web server easier to remember or shorter to code, especially when you have a deep subdirectory structure, when using webroot-relative paths
• Reduce maintenance chores when changing the location of files currently pointed to by relative or webroot-relative paths

Again, if you're fuzzy on what a webroot-relative path is, see the other "basics" article for more background. In that article, we are introduced to a fictitious Web server directory structure that will be helpful in this article.

Let's assume we have a directory called c:\inetpub\wwwroot\myproj\myapp\, which holds the HTML and CF templates for a given application. Let's also assume that under that directory there is also an "images" directory used to hold image for the application.

Here's another representation:

C:\

  Wwwroot\

    Myproj\

	   Myapp\

	     Images\

    Otherproj\

	   Otherapp\

As such, a template running in the myapp directory can refer to images in the "images" directory using a relative path, such as <IMG SRC="images/photo.jpg">. And a page in the Otherapp directory could also refer to that photo using either a relative path, with <IMG SRC="..\..\Mproj\Myapp\Images\photo.jpg"> or a webroot relative one (just a little shorter), with <IMG SRC="\Mproj\Myapp\Images\photo.jpg">. The differences between these two are explained in the other article.

But a Web server mapping can make accessing files in this sort of structure much simpler. And a CF admininstrator mapping may also be called for, though not for the simple example shown here of referring to a photo in an <IMG SRC> tag.

Web Server Mappings Versus CF Administrator Mappings

On the simplest level, the difference between these two kinds of mappings is that Web server mappings are configured in your Web server, whereas CF administrator mappings are configured in the CF administrator. But there's far more to the distinction than just that.

Many people assume they're the same and that they perform the same role with just a difference in how you create them, just as a CFQUERY tag can point to an ODBC datasource regardless of whether it was created in the CF administrator or the Windows Control Panel (for Windows 95/98/NT users) or Administrative Tools (for Windows 2000 users).

But Web server and CF administrator mappings are really quite different from each other.

Web Server Mappings

Web server mappings affect how the Web server will find a file when requested from a browser. That's the key point: they affect requests made of the Web server by Web browsers. For instance, the Web server may receive a request from the browser by a user typing in a URL, or by their causing execution of a page's HTML (such as <A HREF>, <IMG SRC>, <FORM ACTION>, etc.) or JavaScript (such as location.href, window.open, etc.) telling the browser to request a given file from the Web server.

In these cases, the Web server will respond by locating the file specified in the URL using the path provided to point to the named file. A Web server mapping can serve as a virtual directory name or "alias", pointing to a real physical path on the server. This is transparent to the browser (and even the coder building the HTML to be sent to the browser).

A Web server mapping might be set up to make it so that any reference to our photo above will be much shorter. When the Web server receives the request for a file, it looks at the words following the "\" immediately after the domain name in the URL (or following the leading "\" if no domain name is used, as in the case of a relative path). Let's look at an example.

As was mentioned in the quiz, we could use Web server mappings to create an alias called \myappimages directory to point to the real directory path c:\inetpub\wwwroot\myproj\myapp\images. Now I can point to an image in that directory more easily (especially from a template in some other directory) with, <IMG SRC="\myappimages\photo.jpg">. That's much more succinct than <IMG SRC="\Mproj\Myapp\Images\photo.jpg">!

And code in any directory on the Web server can share that mapping and find files in this example that way, so they're no longer forced to use either a relative or webroot-relative path. If the location of the Images directory were to change, the Web server mapping could be changed and all code referring to it via the mapping would continue to work well.

But perhaps a more important point is that a mapping need not point only to subdirectories within the current webroot directory structure (in which case a mapping just saves a little typing). Instead, a Web server mapping can be created to point to any directory anywhere on the Web server.

If the server had a D: drive, and there was a directory there called "projectx", as in d:\projectx, then a Web server mapping could be set up to point to it as "projectx", so that the URL www.mydomain.com/projectx would now point to files in that d:\projectx directory. That's powerful. It means that you need not place all Web applications in the same default webroot directory structure.

The mechanism to create Web server mappings will depend on the Web server you are using. In Internet Information Server version 5, on a Windows 2000 machine, for instance, this is done via Start>Settings>Control Panel>Administrative Tools>Internet Services Manager. From there, as seen in Figure 1, you choose your "computer" or server name. In a simple setup with just one domain, you'd then select the Web server (typically "Default Web Site"). Right click on that, and choose "new>Virtual Directory" which will launch a wizard to lead you through creating a new directory.

Figure 1: Creating a Web Server Mapping in IIS 5

If you're using a Web server other than IIS on Windows 2000, refer to your Web server and operating system documentation on how to modify such Web server properties. It may involve editing a property file, or there may be a similar interface to this. Look for help on creating an "alias" or "virtual directory" or simply "mapping". The terms vary among Web servers, but the concept is supported on nearly all of them.

We mentioned that such Web server mappings are used by tags like <A HREF> and <IMG SRC>, which make requests of a Web server to present a file to the browser. We should clarify, too, that it's not just browsers making requests of Web servers that can benefit from such Web server mappings. Several CF tags also use URLs within their attributes and therefore can take advantage of any Web server mappings on the server to which they're pointing, such as CFLOCATION, CFHTTP, CFINDEX, and CFSCHEDULE. But like the HTML tags, these do not benefit from CF administrator mappings. And similarly, tags like CFINCLUDE and CFMODULE cannot benefit from these web server mappings. Let's see why.

CF Administrator Mappings

So what's the difference between Web server mappings and CF administrator mappings? They're really quite different. CF administrator mappings are needed solely to bring the benefits of mappings to CF tags such as CFINCLUDE and CFMODULE which don't involve communication with the Web server to find their named files. These tags execute entirely within the CF server, so they can't benefit from any Web server mappings. If you want to bring the benefits of mapping any given directory to these tags, you need to set that up in the CF administrator mappings.

They work otherwise similarly to Web server mappings. If you define one then when a webroot relative path is provided in a CFINCLUDE, for example, the word that follows the leading "/"can be a virtual path as created in the administrator.

You may see examples in books or classes showing a CF administrator mapping set up to point to a "templates" directory that holds some commonly used navigational toolbars that are CFINCLUDEd by templates in directories all over a given Web server directory structure. In that case, the CF administrator mapping simplifies the path specified on such CFINCLUDEs, and also protects the CFINCLUDE from failing if the "templates" directory is moved (as long as the CF administrator mapping is updated to reflect the move).

Let's see more detail on how to set one up and then use it. We create CF administrator mappings in the administrator page reached via the left navigational toolbar options Server>Mappings. From there, you can create a virtual mapping or path, as shown in figure 2.

Notice that by default, there is already a mapping for the root itself, "/". That's very handy. It means that you can always use the equivalent of a webroot relative path in a CFINCLUDE or CFMODULE.

Let's consider that we wanted to create a new mapping for the c:\inetpub\wwwroot\myproj\ directory in our ongoing example. Perhaps there are some templates that would be useful to CFINCLUDE there which could be shared by templates in many other directories. We could create an alias for that directory called "myprojtemplates". (While we could call it just "myproj", that could be confusing both to CF and your developers.)

We would then simply enter "/myprojtemplates" in the "Logical Path" and then enter the full path (c:\inetpub\wwwroot\myproj\myapp\) in the "Directory Path". Note that the case of the "logical path" is not sensitive, though the case of the "directory path" may be sensitive on Unix platforms. Also note the leading "/". CF forces you to put that there. Again, a mapping will be used if the beginning of a path provided in, for example, the CFINCLUDE TEMPLATE attribute, starts with "/".

Now, we could use that CF administrator mapping with an example such as <CFINCLUDE TEMPLATE="/myprojtemplates/sometemplate.cfm">, and the administrator would locate the file in the correct physical location.

Just remember: you may not always need to set up a CF administrator mapping. If you can leverage the existing "/" mapping that points to your web server root, there may be no need to create yet another mapping.

CF Administrator Mappings and Shared Custom Tags

Where else might CF administrator mappings come in handy? Well, consider the challenge of using custom tags in an environment where you're not allowed to place them in the default shared custom tag server directory. If you work in a hosted environment (where you pay a fee to place your Web site on a third party's servers) or in a tightly controlled environment where someone else decides what may and may not be placed in the shared custom tag directory, you may be at a loss on how to share custom tags among several directories if you can't place them in the default shared custom tag directory (such as c:\cfusion\customtags).

We're about out of space to explain things in depth, but you can take advantage of the CFMODULE tag and its TEMPLATE attribute to point to any Web server directory using either a relative or webroot relative path. You could also create a new mapping to make it even easier for code in multiple directories to share a given custom tag directory. Again, this is all done with CF administrator mappings, rather than Web server mappings.

You can learn more about this notion of calling custom tags in different locations, including the purpose and use of CFMODULE's NAME attribute, in a two-part article called "Calling All Custom Tags" in the March and April 2000 editions of ColdFusion Developer Journal.

I hope this discussion of Web server versus CF administrator mappings has been helpful. It's not a trivial subject, though many people and resources often presume that it's a concept understood by all. In my experience, it's not well-understood at all. Good luck applying this new information to solve your own coding challenges.

Studio Mappings and Drive Mappings

We've run out of space to discuss the remaining two mappings, so we'll have to pick those up in a Part 2 of this article. Studio mappings really are quite different entirely and are worthy of their own article. We'll also show you how to configure Studio to browse files (internally and externally) based on those mappings as well as explain how drive mappings can be used with those browse mechanisms.