ColdFusion in Context: Included Point of View

Suppose you include a page. Suppose that page includes an image. Whose point of view counts? The perspective of the calling page, or the perspective of the included page? What effect does this have on you, and what can you do about it?

If you guess wrong, all of your relative references (links, images, form actions, redirects, and page includes) will be broken.

Assuming that a change in perspective wouldn't be noticed if all your pages were in a common directory, we'll instead look first at nested directories and then at sibling directories.

Nested Directories

Start by creating a home directory; call it homenot (because you don't want to follow this example). Within that directory, create a login directory; call it login. Within the homenot directory, place an image of your choice. Then create a rudimentary home page that uses your image (instead of earth.gif below): homenot/index.cfm. 

<h2>Welcome to my world</h2>
<a href="login/mystery.cfm">
<img src="earth.gif" border="0"></a>
Life is a mystery
<cfif isDefined("cookie.TICKET")>
  <cfif cookie.TICKET contains "_a">
    and love holds the key
  </cfif>
</cfif>

Within the login directory, create mystery.cfm (homenot/login/mystery.cfm) and give it this code. It wouldn't take much to extend this to use an encrypted cookie and a database lookup instead of the fake items used here, but this code just sets the stage for what comes next. 

<!--- Set defaults --->
<cfcookie name="TICKET" value="0" expires="-1">
<cfset Message="">
<cfif not isDefined("form.UserName")>
  <cfset Username="">
  <cfset Password="">
</cfif>

<!--- Act on login --->
<cfif isDefined("form.Try")>
  <cfif (form.Username contains "f")
  and (form.Password contains "f")>
    <!--- Issue pass --->
    <cfcookie name="TICKET" value="1_a">
  <cfelse>
    Incorrect login
  </cfif>
  - THIS EXAMPLE PRODUCES BROKEN LINKS
  <cfinclude template="../index.cfm">
  <cfabort>
</cfif>

<!--- Accept login --->
<p>
<form name="login" method="post">
<strong>Please log in . . . </strong><br>
[Good logins have an "f" in both the username and password.]<br>
Username <input type="text" name="Username"
size="25" maxlength="25"
value=<cfoutput>"#Username#"</cfoutput>><br>
Password <input type="password" name="Password"
value=<cfoutput>"#Password#"</cfoutput>>  <input
type="submit" name="Try" value="Go">
</form>

Now browse homenot (the default: index.cfm), click the image, enter a good login, and click "Go". Very briefly, what will happen? If login succeeds, the original page will be included, and the rest of the poetic statement will be displayed. Because the page is included instead of moved to by means of the cflocation tag, a cookie can be written when the login "succeeds". This is a good thing.

However, because the page was included from a parent directory, its references relative to the rest of the site are all wrong. The image is not present. If you check the missing image's properties - right click to get a menu - you'll see that it's looking for an image in the login directory. Right-click on the text, and you'll see that this page is effectively homenot/login/mystery.cfm, not the included page. If the included page had links leading to points within the home directory (or above it), all of them would be wrong as well. If you click on the placeholder for the image, you'll get a "not found" error.

The lesson thus far is that when you include a page, the point of view belongs to the calling page, and all the links and image locations of the included page are interpreted from the point of view of the calling page.

So, what's a designer to do? Consider sibling directories.

Sibling Directories

Copy the homenot directory to a sibling directory called home. Move the login directory from within homenot to become a sibling directory called site so that you have three directories at the same level now: homenot (which you won't use again), home, and site. Change the code in home/index.cfm to look like this; the only changes are to the link, the image location, and the cookie test (so the demonstrations won't interfere with each other). 

<h2>Welcome to my world</h2>
<a href="../site/mystery.cfm">
<img src="../home/earth.gif" border="0"></a>
Life is a mystery
<cfif isDefined("cookie.TICKET")>
  <cfif cookie.TICKET contains "_b">
    and love holds the key
  </cfif>
</cfif>

Now change the code in site/mystery.cfm to look like this; the only changes are the included page location, the cookie value (to keep the demonstrations separate), and removal of the "BROKEN" message: 

<!--- Set defaults --->
<cfcookie name="TICKET" value="0" expires="-1">
<cfset Message="">
<cfif not isDefined("form.UserName")>
  <cfset Username="">
  <cfset Password="">
</cfif>

<!--- Act on login --->
<cfif isDefined("form.Try")>
  <cfif (form.Username contains "f")
  and (form.Password contains "f")>
    <!--- Issue pass --->
    <cfcookie name="TICKET" value="1_b">
  <cfelse>
    Incorrect login
  </cfif>
  <cfinclude template="../home/index.cfm">
  <cfabort>
</cfif>

<!--- Accept login --->
<p>
<form name="login" method="post">
<strong>Please log in . . . </strong><br>
[Good logins have an "f" in both the username and password.]<br>
Username <input type="text" name="Username"
size="25" maxlength="25"
value=<cfoutput>"#Username#"</cfoutput>><br>
Password <input type="password" name="Password"
value=<cfoutput>"#Password#"</cfoutput>>  <input
type="submit" name="Try" value="Go">
</form>

Browse home (the default: index.cfm), click the image, enter a good login, and click "Go". What happens this time if login succeeds? Because the page was included from a sibling directory, its references relative to the rest of the site are correct. The image is present. If the included page had links leading to points within this directory or other sibling directories, all of them would be right as well.

Finish

You've just seen a simple technique at work: don't nest your directories. Set up multiple directories as siblings all on the same level relative to a common parent that contains almost nothing. Two years ago, I published this as a design approach. This example shows the power of the technique.

The only remaining issue is getting the browser out of the parent directory as soon as possible so this technique can be put into effect. One answer is to have the parent redirect the browser to a "main" directory before displaying anything useful. Here's an example to be placed above the directories you've created thus far. Call it index.cfm. 

<!--- Include your own code "here" before cflocation
to log the previous URL, count hits, etc. --->

<!--- Now go to the desired page --->

When you browse this top-level index.cfm, it will execute code you give it and then will bring you to home/index.cfm. If you want this page to show off ("splash") or want it to set a cookie, replace the cflocation tag with a link or simple form. =Marty=