Customizing ASForm Error Messages


Introduction

You can integrate ASForm into your site so it looks like it belongs there by customizing your error messages. Although they are generated as they're needed by ASForm, you can define their appearance on your own without messing around with ASForm's internals -- which would violate the terms of use, anyway. We both know that you're not a dirtbag who would take another guy's 2600+ lines of code and mess around in it after he gave it to you for free, and this is one way to minimize the temptation that some other folks might feel if they thought it didn't do what they wanted done.

ASForm returns error messages as HTML, and generates everything it needs to make an HTML4.0 compliant (Transitional, or "Loose") document. The default document comes with just a white background, no text highlighting to call attention to the more important lines of the message, and the message itself in a table (no borders) set to a width of 65%. The text color, link color, etc. is simply not defined so it's left to the user's browser to pick those colors.

To allow you to provide a more-or-less consistent look to all of your site, ASForm will let you dictate the background image and/or color, text color, link color, etc. that get installed in the <body> tag, but not the font face. (Sorry...) Those things are described in the configuration document. Here, we will concern ourselves with writing HTML for the headers and/or footers of the error messages.

Getting ASForm happy with your HTML snippets

By now you may have noticed that ASForm likes to know that it's really supposed to be sending files into the world, and looks for certain tags to indicate that it should. These HTML snippets are no different. Each of them must contain an HTML comment that starts with asformdoc and may then include whatever you want within it, e.g.

<!-- asformdoc additional comments if desired -->

And yes, that space between the opening dashes (or hyphens) and asformdoc must be there, and it must be a single-line comment. If there is an intervening newline (carriage return, whatever you call it) in the comment, ASForm will just refuse to use this file, and will tell you so if you run it in debug mode.

Unless the snippets you use are also used elsewhere, don't even think of trying to sneak SSI (Server Side Include) directives into your HTML snippets for ASForm. Not only would it not stand a chance of actually working, ASForm parses these files and will strip out the SSI directives just in case you've got a wierd server that looks for them in CGI output. (Is there such a critter??)

How ASForm uses them

Here's the sequence of events as related to generating error messages:

  1. Parsing configuration file, keep an eye out for error head: and/or error foot: and the other parameters that define the appearance of the error message.
  2. If an error message must be generated, send the HTTP and HTML headers up to the opening <body
  3. If any or all of background, bgcolor, text color, link, alink, and/or vlink exist, populate the body tag appropriately, then close it with >
  4. If an error head: was found during parsing of the configuration file, test that it exists, is readable, is not empty, is a text file, and contains the tag (comment) <!-- asformdoc -->. If any test fails, blow it off.
  5. Strip out any SSI directives that might exist in the file.
  6. Send along the file indicated by error head:
  7. Send the error message in a table set to a width of 65%, using the highlight: color where appropriate.
  8. If there was an error foot:, test it like we just did for the error header file, and blow it off if it fails.
  9. Strip out any SSI directives that might exist in the file.
  10. Send the file indicated by error foot:
  11. Send </body> and </html>

If you want to see the tests happening, run ASForm in debug mode -- its output is generated as the tests are run. (Stripping SSI directives is not a part of the file testing, so it will not be indicated in the debug output.)

So, now that you know where in the document your HTML snippets will appear, you probably know what you can and can't do with them, and won't bother trying to put in your own <body> tags and such, right? Oh, yeah: If the error messages don't show up in some browsers, like Navigator, it's not ASForm doing it, it's your header/footer, and probably due to an attempt to incorrectly nest that table that the error message lives in. Trust me, I know these things.


Index
[online]
Introduction/
Features
Configuration Installation
 
Customizing
Error Messages
Writing
Message Templates
Writing Forms for
Use With ASForm
Running
ASForm Debug

 

© 1999 - Art Sackett