distinction of web server mappings and cf mappings:

Web Server Path Basics for Web Developers

And the Mysteries of Relative and Webroot-relative paths

June 2001


Many CF users pay scant attention to how the web server on which they work functions. Perhaps you’re in a hosted environment, or working on a corporate server, and someone else runs the web server.


You may just be told to put your files into directory “x”. Maybe that’s an FTP directory on your server (if you’re on a hosted site), or a mapped drive on your LAN (if your web server is on a box down the hall).


In either case, on the server itself, this location will end up being some directory under the “root” of the web server, such as c:\inetpub\wwwroot, or d:\htdocs, depending on your web server. This location is often referred to as the web server’s “webroot”.


But you may not care. You just know to put files in the “x” directory, and then to point your (or your visitor’s) browser at http://www.yourdomain.com or http://www.somedomain.com/yourdir, to execute those templates.


That’s fine, until your needs grow beyond that simple structure, such as if you have several subdirectories with templates pointing to each other, or multiple domains located on the same server. (By the way, if you’re not familiar with the term “domain”, it’s the phrase www.mydomain.com in the first example above.)


In any of these cases, it really helps to understand the different ways to specify paths among multiple directories on the server, including relative and webroot relative paths, as well as the notion of knowing your domain’s “home directory”.


In this article, we’ll explain these things. This forms the basis also of understanding the difference between web server mappings and ColdFusion Administrator mappings, as are discussed in the Allaire DevCenter article at http://www.allaire.com/handlers/index.cfm?id=21225&method=full.

About Relative and Webroot-relative Paths

Before explaining the benefits of and differences between web server and CF administrator mappings, it may help to clarify a distinction about “relative”, “absolute” and “webroot-relative” paths.


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:







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”>. This is called a relative path, because it specifies the location of the directory relative to current running template.


But what if the page referring to that photo existed in an entirely different directory on the web server, such as c:\inetpub\wwwroot\otherproj\otherapp. In that case, such a template could still use a relative path, but it would require understanding a rather subtle point of directory nomenclature to be able to point up the directory hierarchy.

It’s a holdover from the days of DOS and Unix command lines, using “../” to refer to one’s parent directory: that is, the one above where a file using it is currently located.


So to refer to the aforementioned photo.jpg file from within the otherproj/otherapp directory, we would have to use a rather lengthy path, as in <IMG SRC=”../../myproj/myapp/photo.jpg”.


That’s quite a mouthful! And in fact, it’s not always really necessary. We’ll learn about “webroot relative paths” soon.

Absolute Paths

You may also hear the term “absolute path”. This can have different meanings to different people. Technically, in this case, the absolute path for that images directory would be: c:\inetpub\wwwroot\myproj\myapp\. It’s the actual physical path to the file on computer hosting the web server. The thing is, when you’re referring to directories in web browsers and in URLs (such as are used in <A HREF> and <IMG SRC> tags), you can never use this absolute path.


The reason is that a browser is prevented from using absolute paths on the web server. They can only see directories relative to the location defined as the “web root” or “webroot”. So instead, an absolute path in a URL would be one specifying the domain name and the path/file name, as in http://www.yourdomain.com/somepath/somefile.htm.


In this case, some will also refer to the absolute path as being that which can be specified when templates on the same server are referring to that path/file name, as in <A HREF=”/somepath/somefile.htm”.


More often, that sort of path will be referred to as a “webroot relative path”, because it’s specifying a path/file name relative to the root directory of the web server. It’s very useful to keep the webroot relative path in mind, since then any template in any directory on the web server could point to any other directory.


Another subtlety is the actual physical location of this “webroot”.

Where is the “webroot”?

Where is this “webroot”, or the web server’s root directory? Well, its exact location will depend on how your web server is configured. It can mean different things on different servers, or even for different domains on the same server, when several domains are hosted on a single web server. More on that in a moment.


In any case, it’s the location pointed to if you specify just your domain name in a URL, as in http://www.mydomain.com. But where is it, exactly, on the web server?


Well, some web servers may refer to this as the “home” directory. In our example above, it would be c:\inetpub\wwwroot. On a unix server, it may be \htdocs. So if a file named test.html is located in the c:\inetpub\wwwroot directory, it would be callable by the URL http://www.mydomain.com/test.html (using the fictitious domain name above). Note that the “/” in the URL really means “look in the webroot directory”, wherever that is for this domain.


And if we wanted to refer to the deeply nested directory above, we would use http://www.mydomain.com/myproj/myapp/, which means “start looking in the myproj directory just below the webroot” and furthermore, look in the myapp directory below that.  This might be used in an <A HREF> tag for a template located in the “otherproj” directory to link to a template in the “myproj” directory.


Note that it’s certainly possible that web server security rules will prevent the template in “otherproj” from seeing the files in “myproj”. That may bring up the matter of multiple domains hosted on a shared server.


When there are multiple domains hosted on the same server (often called “multi-homing”), then it’s inappropriate to have them all point at the same “webroot” directory. In that case, each domain can be defined to look for files in its own “webroot” Further, that directory can be anywhere on the web server. It need not be placed within the c:\inetpub\wwwroot directory structure, continuing our example.

Where is the Home Directory?

In the example above where we had an “otherproj” directory, in addition to the “myproj” one, it’s very likely that either of these projects may be setup to each have their own domain name on a shared server, so that, for instance, http://www.otherdomain.com/ points directly to this c:\inetpub\wwwroot\otherproj directory.


Why’s this important to our discussion? Well, it would make transparent to visitors to “www.otherdomain.com” the fact that its files are in a subdirectory called “otherproj”. As far as they know (and any HTML being coded), the webroot for such pages IS the otherproj directory.



That coverage of relative vs webroot relative (and absolute) paths should help clear up confusion if you’re relatively new to the subject. You may not have to deal with multiple domains on your server, but at least now the concept of a home directory also is more familiar.


You can apply this knowledge in the HTML and JavaScript you create, as well as in some ColdFusion tags that use relative and webroot relative paths. If you’re interested in learning more about “mappings” and the distinction between web server and CF Admin mappings, be sure to check out the DevCenter article mentioned at the outset.


PS You may also notice that when referring to paths used in URLs or HTML tags, I’ve been using the forward slash “/” whereas when referring to the file system path I use the backslash “\”. The back slash is how the Windows operating system separates directories in paths, while in URL’s—even on windows servers—use the forward slash. That’s because the first web servers were on Unix servers, which also used the forward slash for separating directories in paths. Not something you have to know, but again it’s one of those things that are often “presumed knowledge” that you may have always wondered about.


If you have any questions about this article, please feel free to contact me at carehart@systemanage.com.

| Home | ColdFusion | Articles | Presentations
| User Groups | Other Resources | Press Releases | Company

© 1998-2023, Charles Arehart, SysteManage
Our Practice Makes You Perfect