                        HTML FORM TEMPLATE
----------------------------------------------------------------------

by Darren Duncan <perl@DarrenDuncan.net>

CONTENTS

* Preface
* Keeping Up To Date
* Requirements
* Installation
* Support
* To Do
* Author

PREFACE

This distribution features the Perl 5 module named "HTML::FormTemplate".

All of my modules have complete POD inside of them, so please refer to that for a
description of the module itself.

This Read Me document concerns itself mainly with installation and support
issues, and also includes any "To Do" lists and the file manifest.

KEEPING UP TO DATE

My module set is constantly under development.  You should be able to find the
newest versions at my website, "http://www.DarrenDuncan.net", on the page called
"Perl Libraries I Made" (name subject to change).  They can also be found on CPAN
under the author name of "DUNCAND".  

I am inclined to update the copies on my web site more often, but those
intermediate versions are more likely to have been tested less, and the modules
may be updated day by day without increasing the version numbers.  However, the
copies on CPAN are guaranteed to have unique version numbers when the module has
changed.

REQUIREMENTS

All of my modules require Perl 5.004 or newer, even though only some of them need
it, in the interest of consistency.  That said, Perl 5.004 is already 3 years 
old, is available as a binary on practically every OS that supports Perl at all, 
and is a very solid release, so I see no reason to support anything older.

Modules in this distribution require modules in these following distributions:

Class-ParamParser-1.03.tar.gz
	- by Darren Duncan (DUNCAND)
	- Class::ParamParser 1.03 is required by:
		- HTML::FormTemplate (as a parent class; parses method arguments)

HTML-EasyTags-1.03.tar.gz
	- by Darren Duncan (DUNCAND)
	- HTML::EasyTags 1.03 is required by:
		- HTML::FormTemplate (makes form field HTML)

MultiValuedHash-1.06.tar.gz
	- by Darren Duncan (DUNCAND)
	- Data::MultiValuedHash 1.06 is required by:
		- HTML::FormTemplate (stores form field definitions)
	- CGI::MultiValuedHash 1.06 is required by:
		- HTML::FormTemplate (stores and parses/url-decodes user-input)

INSTALLATION

To install this module, cd to the directory that contains all of the extracted 
distribution files, including this ReadMe file, and type the following:

	perl Makefile.PL
	make
	make test
	make install

The last step probably won't work if you are not the administrator of your 
machine; in that case you either need to get your administrator to install this 
for you, or put it in a your own local directory instead.

If you are on a Mac system and/or you are otherwise having problems with the 
Makefile, you can still install this module the old fashioned way, by copying.

The file "FormTemplate.pm" goes inside the "HTML" folder which is in the "lib" 
folder that came with your Perl 5 distribution.  

Or alternately, put it anywhere you want, but you will need to have that 
location added to your include path by your main program using something like 
this:

	use lib '/users/me/www_files/lib';

Then you would want to run the included test program to make sure the module is 
installed correctly.  Call it with:

	perl test.pl

Any existing POD is embedded in the module itself.  The Makefile probably 
extracted it for you in the usual manner, or you can run a POD extractor on it 
yourself to the same effect.  You can also find an HTMLized copy of the POD on 
CPAN and other public source archives; I link to one copy of it on my web site.

SUPPORT

Currently I don't have any support arranged with other people, lists, newsgroups,
or otherwise.  Feel free to ask me if you can't figure things out on your own, or
another person whom you know has used this.  I may start a mailing list for 
support issues later, so that users of my modules can help each other with them.

TO DO

	* Correct remaining issues related to output html so that it validates 
	completely against W3C's XHTML spec.
	* Add a battery of tests to ensure that the module is working properly.
	* Allow echo reports to show the selection field labels for the user input 
	instead of the "values" that are actually passed behind the scenes.
	* Add field attribute read_only, allowing once-editable field data to share 
	screen space with still-editable field data.
	* Allow individual editing of internally stored field definitions, rather 
	than requiring that they are all defined at once.
	* Customize validation error messages so they give a better idea what about 
	the entry was inappropriate (eg: wrong number of selections).
	* Add support for customizing the appearance of forms more, such as having 
	literal text/html appearing between elements of @definitions.
	* Make a utility program that utilizes this module's abilities to let users 
	create form definitions for it with a web browser.
	* Add more field types and JavaScript support where appropriate.
	* Add support for "callback" or "closure" subroutines where appropriate.
	* I have few more ideas in this regard, but am open to suggestions.
	* Get my other modules done.

AUTHOR

Copyright (c) 1999-2001, Darren R. Duncan. All rights reserved. These modules are
free software; you can redistribute them and/or modify them under the same terms
as Perl itself.  However, I do request that their copyright information remains
attached to the files.  If you modify this module and redistribute a changed
version then please attach a note listing the modifications.

I am always interested in knowing how my work helps others, so if you put this
module to use in any of your own code then please send me the URL.  Also, if you
make modifications to the module because it doesn't work the way you need, please
send me a copy so that I can roll desirable changes into the main release.

Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.

Share and Enjoy!
