Welcome to spin_feedback for mod_spin from Rexursive(R)
=======================================================

This mod_spin application will store requested fields of an enquiry form into
SQL database and e-mail desired fields to the supplied address.

Configuration
=============

The example configuration file, spin_feedback.xml, show which application
configuration parameters can be set. Here is what they mean:

feedback_host:   name or IP address of the SMTP mail server
feedback_mailto: who gets feedback

feedback_store:  which parameters should be stored into the database
feedback_email:  which parameters should be e-mailed
feedback_names:  what names should be given to the e-mailed parameters

feedback_validate_empty: which paramaters should not be empty
feedback_validate_email: which parameters should be valid e-mail addresses
feedback_validate_lists: which parameters belong to one of the lists

feedback_files: which parameters are attached files
feedback_cc:    should we send a carbon copy to the person filling in feedback

feedback_list_<name_of_list>: the list specified, <name_of_list> must match
                              one of specified in feedback_validate_lists

feedback_db_connect:      connect string for the database
feedback_db_feedback:     name of the feedback table
feedback_db_feedbackitem: name of the feedbackitem table

Template API
============

This application will check parameters for validity in 3 different ways: if
the parameters are empty, if they are valid e-mail addresses and if they match
items from some list. Only the specified parameters will be checked. If the
parameters doesn't validate, a reference "<name_of_the_field>_error" will be
placed into the context. Template can then check for its existence to display
the appropriate error. On validation error, no parameters will be stored or
e-mailed.

If validation finished successfuly, the requested parameters will be stored.
If there were errors, a reference "store_ERROR" will exist in the context.
After storing (even if there were errors), an e-mail will be sent out with the
requested parameters and any uploaded files. If there were errors, an
"email_ERROR" reference will be placed in the context. After that, an
"finished" reference will be placed in the context. Template can check for the
existence or all these references and display appropriate messages.

Parsing
=======

The configuration file contains three types of items that will be parsed:
parameters, names and lists. Parameters can be separated by commas, spaces,
tabs, newline or carriage return characters. Names and list only by commas,
tabs, newline and carriage return characters. That is to say, parameters
cannot contain spaces, other items can.

Database
========

There are three sample database creation scripts for PostgreSQL, SQLite3 and
MySQL. However, the C code won't work with MySQL without change, because MySQL
doesn't implement CAST() to TIMESTAMP.

What gets stored
================

All parameters named in feedback_store will be put into the database. However,
if the parameter is an attachment (i.e. uploaded file), only its name will be
stored, not its content. The content will be e-mailed to the designated e-mail
address.