Relativity and Your Web Site

Caution: Paths may explode.

I bet, at some point, you’ve come across a broken link or maybe an image that just wasn’t loading properly into your web site. When it comes to linking files, or more specifically, file paths in your web site, everything is relative. But relative to what? The problems associated with relativity become especially apparent when working with dynamically created pages.

In your web applications, there are several kinds of paths you’ll be dealing with. Sorting out which path is for what is often confusing for beginning web developers so here’s the quick list of some of the terms and which path’s they’re referring to:

Start at the Document Root

(aka DocumentRoot, $_SERVER[‘DOCUMENT_ROOT’]), document.documentElement and Site Root)

The term document root is tricky. Which definition you need to follow depends on which part of the site you’re referring to: The server or the client?

The Server

On the server, the document root is the path starting at the server’s root /, to the folder where your web site documents are stored. For example, in a common Debian/Linux setup this is usually

/var/www

whereas on Mac OS X, this would be

/Library/WebServer/Documents 

So your default index page would be the index.html file in the document root of your site, or

/var/www/index.html

{.caution}If you’re running on a multi user or virtual host system the document root may include your home directory /home/username/public_html/ or a virtual host /var/www/example.com/. Check with your ISP or network administrator if you’re not sure.

In PHP, you can easily find out the document root of the current script using the $_SERVER['DOCUMENT_ROOT'] value, which is pre-populated from the web server configuration file. This isn’t necessarily referring to the folder containing the current script, as I mentioned above, it’s the document root of the entire site.

This is all fine and dandy for the web server, but the terminology gets even tricker when you’re referring to site root relativity for the web site in a browser.

The Browser

In the client’s web browser, document root can refer to two different things. First, if you’re dealing with JavaScript, the document root can refer to the JavaScript DOM element:

document.documentElement

which is usually the root <html> node in the document tree. You can use it to access the DOM and modify your structural document as necessary.

Second, when dealing with paths in your browser, the document root can also refer to the site root which, like the server root, is represented by the single / at the end of your domain name http://example.com/. The site root represents the same ‘location’ as the document root on the server. If I just lost you, think of it this way: Your web browser doesn’t know how your server is configured so when it asks the server for http://example.com/index.html, the server will send back the file /var/www/index.html, so http://example.com/ in the browser is the same set of files as /var/www/ on the server.

As a shortcut, when you’re working with HTML, CSS and browser documents within http://example.com, you can leave off the domain name and simply use an initial /as a short-form for http://example.com/ so

/hello.html

is the same as

http://example.com/hello.html

but only if you’re working within the http://example.com domain.

Find Your Relative Path

Now that you understand what the document root is, you can more easily understand path relativity. In the web browser, there are three kinds of paths: document-relative, site-relative and absolute.

Document-Relative

A document-relative path is the path from one file to another, using the initial file as the starting point rather than the document root. For example a document relative path may look like

images/background.gif

or possibly

../../images/background.gif

if you had a site structure that resembled

A.html
images/
	background.gif
folder/
	subfolder/
		B.html

A relative path from one document to another will change depending on the location of the document in the structure’s tree. If you want to link to background.gif from A.html, the document-relative path from the HTML file to the image would be images/background.gifwhereas if you want to link to background.gif from B.html, the same path would be ../../images/background.gif.

{.caution}The double period ../ reference refers to ‘my parent folder’ so the path ../../images/background.gif means go to my parent’s parent and then into images to get background.gif. Likewise, a single period ./ references ‘my folder’ so in the previous example, linking the image to A images/background.gif is the same as ./images/background.gif.

Paths relative to a document are often difficult to determine in a dynamically created site with a central engine, where you can’t be sure of the exact location of the document relative to others. If, for example, you’re using a MVC pattern to create all your pages on your site, there is going to be a single script in the root of your site responsible for creating all the HTML pages, but the page could be A.html or folder/subfolder/B.html so you’d need to calculate the relative path for each request. To avoid this, you could alternatively use a site-relative path.

Site-Relative

A site-relative path starts at the document root of the site, or as you remember the single /. If you look back, I actually left something out of the earlier hypothetical site structure. There is actually a site root missing at the top:

/
    A.html
    images/
        background.gif
    folder/
        subfolder/
            B.html

By starting from the site root, the link to background.gifwould be /images/background.giffor both A.html and B.html regardless of their position in the tree. By beginning the path with a single /, you’re telling the browser to basically ignore the current position of the document and start from the root http://example.com/.

Absolute (not relative)

If you want, you can also use the full domain name, http://example.com/images/background.gif which is referred to as an absolute path, but it’s unnecessary if you’re working within the same domain. By default your browser will know that / means http://example.com/. If however, you want to include a file from a different site, you need to specify the full absolute path http://jeffreysambells.com/images/example.gif which will tell the browser to look in a different site and document root.

Gotchas

One thing to remember with document-relative paths is that the relativeness of the path is dependent on the location of the document it’s in. For HTML, the path is relative to the HTML file. For external CSS files, although they’re included in the the HTML document, paths indicated in the CSS file such as in the url() of a background selector, are relative to the CSS document, not the HTML file that includes it. This means that A.html and B.html can share the same CSS file whose url()’s are defined relative to the CSS file. That way, regardless of where the CSS file is, the relative paths will always be correct.

Now go play

Hopefully this clears up any confusion you may have had regarding linking files and locating them in your site. Now you just have to be sure the files are actually located where you said they were so you’ll stop seeing broken images or missing stylesheets.