While you don't need a degree in web development to use Hazel, there are some basic concepts of HTML and how the web works with which you'll need to be familiar. Frantic dilemmas such as "Where are my images??" can be easily researched and solved if you know how a browser finds the images. As the image question is one of the most frequently asked, we'll begin with that.
Where are my images?
You have a broken image. Where is it? Let's assume you actually put it on your server. In that case, it's right where you put it! It isn't "missing," but your browser can't find it. The first investigative step is to find out where your browser is looking for it.
Each browser has a way of viewing an image. On Netscape, you right-click (or the Mac equivalent) on it and choose "View Image." Upon doing so, the URL (web address) of that image will show up in your browser's location window. That's where you're browser's looking for it, and it's obviously not there.
In most cases of broken images, the browser window shows a "Not found" (or some variant of that message.) Look at the URL. Does it look familiar? You need to know how to translate a URL to the path to which you upload documents and images to your server.
But first, some boners!
Before we go on to the theories behind why a browser might think an image is missing, here's a hitlist of common mistakes committed by those uploading images to their web server.
- Remember that filenames are case-sensitive on Unix systems. If you have a file named Example.HTML on your Unix web server, you won't be able to access it from the web as example.html. Case matters!
- Always upload images in "raw" or "binary" mode. Not "text" or "ASCII" or "MacBinary". It's a binary file and must be transmitted as is, without any translations.
- If your image URL resembles "file:///C:/My%20Documents/example.jpg", then you've done something wrong in your fancy-schmancy graphical editor. Edit the link so that it's a proper http:// or https:// URL.
Now that we've gotten those out of the way--onward to knowledge!
Document Roots and Relative Paths
Every web server has a "document root" where your web-accessible stuff is placed. It might be called "htdocs", "www", "public_html" or it could be named after your site (eg. "netsville.com/"). You need to know where that is.
Let's assume for this example that it's "htdocs" and the URL of our site is "http://www.netsville.com/". Those are the "document roots." Any file off you upload inside htdocs will be found via the web off of http://www.netsville.com/. If you upload an image into htdocs/example.jpg, then you'd view if from the web by going to http://www.netsville.com/example.jpg. That makes sense, right?
The part after the root (or "base") is the "relative" part of the path or URL. Assuming your web provider has a decent setup, that relative part should be the same for a server path ("htdocs/example.jpg") and for a web URL ("http://www.netsville.com/example.jpg").
Pop quiz! Assume the "htdocs" server path and "http://www.netsville.com/" web URL in our ongoing example. Let's go back to our broken image. Assume the URL your browser shows is "http://www.netsville.com/hazel-doc/example.jpg". Where is your web server looking when your browser requests that image?
Take your time. Think logically. It's not a trick question. Your web server sees a URL "http://www.netsville.com/" and knows to look for what it's going to serve in your server's document root. It's configured to look for that in your home directory under htdocs. Now it takes everything after the domain name (the "relative" part of the URL) and slaps it onto that htdocs directory.
What does it come up with? If you said htdocs/hazel-doc/example.jpg, you're right!
What about the other ones? It can't be htdocs/example.jpg, since there's no hazel-doc in there. While the second answer might be a better way to organize things (putting images into a subdirectory), that's not where the URL points. It doesn't have "images" anywhere. The last one is closer in that it's in hazel-doc, but again--we don't have an "images" subdirectory in our URL.
Get it? Make sense? I hope so!
Where Does My Browser Go?
Now that you know where your browser is looking for your images, you know where to put them so that the browser can find them!
However, it's not always a good idea to just upload images where the browser thinks they should be. After all, the browser is a dumb machine. You're a human, with higher logical, creative, and organizational skills. You know where you want the images, now how to get the browser to find them?
To answer that question, we need to go a little deeper into how a browser constructs a complete address for an image.
An Image Tag and Relative Links
You might be using Frontpage, Dreamweaver or some other "What You See Is What You Get" (WYSIWYG) editor to construct your pages. That's OK, but you should know what the browser reads. We'll start with the item in question--an image.
A browser reads text instructions called HTML, and "renders" it into a pretty page. The HTML tells it where to find elements of the page, and where to put them once it finds them. Let's take a look at the HTML for a basic image.
A single HTML element is composed of a less-than angle bracket, a tag name ("IMG" here), some attributes (eg. SRC="example.jpg"), and a closing greater-than angle bracket. The tag is the HTML element's name. It marks up a certain type of element for your page. The attributes further define that element. In our simple example, all we need is the address for the image.
Your browser sees the IMG tag, knows it needs an image, so looks at the SRC to find it. In our example, that SRC says "example.jpg". If that's all the browser knew, we'd be in big trouble. It'd be like someone telling you "21" and expecting you to find a house on a street somewhere in America.
Fortunately, the browser has a context for that address. It knows where the current page is, so assumes that image is in the same vacinity. If the page on which you defined the IMG tag was "http://www.netsville.com/test.html", then its best guess is that the image is at "http://www.netsville.com/example.jpg", in that same directory.
Pop Quiz Numero Two-o! If you load up the page "http://www.netsville.com/services/sheepshaving/prices.html" and there's an <IMG SRC="baa.jpg"> HTML element on that page, where is your browser going to look for it?
Let's see. Assuming the browser has no other hints (we'll discuss that later), it'll look for the image in the same directory as the HTML page. So, it'll have to be somewhere under services/sheepshaving. There's no mention of "images" anywhere in the IMG SRC, so those are ruled out. "prices.html/baa.jpg" is tempting, but prices.html is the file itself, not the directory. We want the directory that contains the HTML file, not the file itself.
What's your answer? #5? Correct! If you didn't answer http://www.netsville.com/services/sheepshaving/baa.jpg, go over the past section again. It's simple, really. Don't let the Man get you down. It's all nice and logical if you know how things work.
Fully Qualified Links
As we found out above, with an IMG SRC such as "baa.jpg" and no other hints (coming up), the browser looks in the "current" directory for the image. However, there are two other ways to specify an image source.
You could give a "fully qualified" URL. Start it with the protocal and spell out exactly where to find everything. Doing this is like giving someone the full state, city, and street address. An example would be <IMG SRC="http://www.netsville.com/services/sheepshaving/baa.jpg">.
Although a fully qualified URL is the most thorough way of specifying an address, it has its problems: (1) it's very long, and (2) it's high-maintenance.
The first drawback is obvious. That's a lot of typing for an image that you want in that same directory anyway.
The second may not ever be a problem for you, but it's good to keep in mind. If you ever decide to change your domain name, you'll have to change all your links to point to the new one! There are tools to automate the process, but it's a needless pain in the posterior.
A less obvious drawback of the fully qualified URL arises with secure e-commerce sites, where some pages might be served through the normal "nonsecure" server and others through the secure server. Both are (hopefully, if your ISP does things right) located on the same place on your web server, but the URL will be different depending on whether the page was served securely or nonsecurely.
Let's take the sheepshaving page above, but pretend we're running it through a secure server. Our secure URL is "https://secure.netsville.com/services/sheepshaving/prices.html". If you use a fully qualified URL such as "http://www.netsville.com/services/sheepshaving/baa.jpg" for the images, you're forcing the browser to grab the image from the nonsecure server.
Doing so will get you some nasty warning icons with broken keys since the images aren't on a secure link.
If you'd used a relative URL such as simply "baa.jpg", the browser would look on the secure server at "https://secure.netsville.com/services/sheepshaving/baa.jpg" (same directory as the HTML file). All is well.
Another way to specify an IMG SRC is to give an absolute link. This isn't as rigid and verbose as the fully qualified link. If the fully qualified link gives city, state and street address, the absolute assumes you're already in the right city, and thus just gives the street.
An absolute link looks like "/services/sheepshaving/baa.jpg". The important bit is that it begins with a slash. Instead of searching relative to the current directory, the browser looks for the image relative to the entire domain name.
An absolute link doesn't have all the drawbacks of the fully qualified link. In our earlier example, the absolute would work on your secure server since it doesn't specify a specific domain name. However, it does assume both your secure and nonsecure servers have the same file path structure. While that's a convenient setup, it isn't always the case.
Now that you know where a browser looks for an image, let's go on to how you can force it to look somewhere else.
With "static" HTML pages, there's little reason to use anything but good ol' relative links. Images are usually kept around their HTML files, and it's easier to maintain them that way. If someone gave you a list of addresses in your town, it'd be easier to scan just the streets and house numbers--not verbose listings including city, state, zip code, latitude and longitude!
And then there's Hazel.
When you're serving pages through Hazel, the address in your browser probably does not correspond to where the images on a page will be. Usually Hazel is placed in a dedicated "cgi-bin" or "scripts" directory. Images aren't even allowed to be put there.
When Hazel serves a page, she reads it right off your web server's hard drive, sprinkles her little HZML fairy dust on it, then pushes it off to the web browser. Your browser sees a URL such as "http://www.netsville.com/cgi-bin/hazel.cgi". There aren't any images in "http://www.netsville.com/cgi-bin/", so relative links without any other hints aren't going to work.
How would you solve this? Using the techniques we've presented so far, it sounds as if an absolute or fully qualified URL might be the way to go. However, we've pointed out their drawbacks. Is there another way, without the problems of those strict URL?
The BASE Tag
Fortunately, HTML provides a way to enlighten confused browsers. The BASE tag gives the browser a root URL for all of its relative links. If there's a BASE tag present, your browser uses it as the root of all its relative links--regardless of the current browser location.
Let's jump right in and show you the BASE included in Hazel's sample catalog and templates.
There we have the tag name "BASE", and an "HREF" attribute which defines that (fully qualified) base URL for the browser.
%HZU_DOC_BASE doesn't look like a URL, does it?
It isn't. Yet. When Hazel serves a page and does her magic HZML thing, she converts %HZU_DOC_BASE to the proper URL for that page. If you're on a nonsecure server, she replaces it with the value of the HTTP_DOC_ROOT field in your hazel.config file. If you're on your secure server, she uses the HTTPS_DOC_ROOT value. Thus, assuming you use links relative to those two URL, Hazel keeps everything straight!
Time for the final quiz of this section. Your browser is asking Hazel to serve a example.html page using the URL "http://www.netsville.com/cgi-bin/hazel.cgi?action=serve&item=example.html". You've got a <BASE HREF="%HZU_DOC_BASE"> at the top of your example.html page as we discussed above. Your hazel.config file defines HTTP_DOC_ROOT as "http://www.netsville.com/hazel-doc". There's an image tag on example.html: <IMG SRC="images/example.jpg">. Where will your browser look for that image?
The final exam! Which is the right answer? We've thrown a little spice into this question, but if you think it through you'll be fine. The most important thing to remember is that the BASE HREF takes precedence over all other browser hints. If the browser finds a BASE HREF on a page, it uses it to expand all relative links on that page.
If we'd left out the BASE HREF, #1 would be the answer, and you'd find yourself with a broken image.
If we'd used an absolute IMG SRC link such as "/images/example.jpg", then the last answer #7 would be correct. When a fully qualified or absolute URL is given, the browser searches based on the domain name and ignores any DOC BASE.
Answers #5 and #6 are definitely wrong. If you chose those, you need to go back and read some of the previous sections.
Answer #3 would have been right had we been serving through our secure server, but we're not.
Answer #2 is close, but no cigar. Our IMG SRC was "images/example.jpg", so the entire "images/example.jpg" needs to be added to the base. Put it all together and we get the right answer, #4: http://www.netsville.com/hazel-doc/images/example.jpg!
Get it right? If so, great! One less person to whom we'll have to explain the mystery of "lost" images. ;)
Wrong? Don't worry. Try re-reading the document. Not patient enough for that? Click the live support link below. We've a strong interest in making this as easy to understand as possible. The more educated you are, the better use you'll get out of Hazel.
HZML & HAM
CGI and You