The main piece of support for mapping URLs to specific components is built
using a regular Iowa content file and code file.  These are found here as
Main.html and Main.iwa.  In a nutshell, they work by looking up the URL
being requested in a hash.  The value of the hash is the name of the component
to use to handle the request.  The hash is described with a simple mapfile
using the following format:

URL: COMPONENT

i.e.

/: Index
/index.html: Index
/guestbook: Guestbook
/guestbook/: Guestbook
/guestbook/index.html: Guestbook


It is a simple, stupid, fast way of doing it that, in practice, has proven
to work quite well.

The tutorial at http://enigo.com/projects/iowa

will have a chapter on setting up and using the URL mapping capabilities
soon.  In a nutshell, the _best_ way to do it right now is to use the mod_ruby
handler, as the translation handler portion can reject requests for items
that can't be handled by the Iowa application, making it really easy to do
an entire site under Iowa.  However you do it, use the Main.iwa and the
Main.html included here at the Main for your application.  Also copy the
ErrorIndex.html and ErrorIndex.iwa files to your application directory and
edit as you see fit.  This is the error page that will be displayed if the
Iowa application is asked for a page that it does not have a mapping for.

Add the following lines to the Application subclass of your startup script:

attr_accessor :mapfile
@mapfile = 'mapfile.cnf'

Create a 'mapfile.cnf' according to the format shown above.

Start your application.

Now, assuming you are using the mod_ruby handler, you need to add the
following to your apache config:

    RubySetEnv MAP_FILE "/path/to/a/seperate/mapfile/apache_mapfile.cnf"

This mapfile is a simple list of paths, one per line, that the handler should
pass on to the Iowa application.  So, given the sample config above, it would
probably look like this:


/
/index.html
/guestbook
/guestbook/
/guestbook/index.html


Restart your web server.  Mapping should be running.  Both the handler and the
code in Main.iwa will detect changes to the mapfiles and reload automatically,
so once it is setup, you can make changes on the fly without restarting.
