Vform II HowTo

Virtual Form CGI
Written by Victor T. DeCristoforo
Copyright Area 51 Consulting Inc.
Last Update: May 24, 2000

Overview

Here are some of the highlights and options that VFORM can perform.

FORM POST FUNCTIONALITY
- This CGI will allow a HTML form with up to 128 fields.
- The maximum allow data input is currently limited to 10000 bytes.
  - A larger size can be implemented upon request.
- User configurable response page with and without a form template
- User configurable e-mail response pages using form templates
- Database file creation using CSV (Comma Separated Values) format.
- Import data files directly into Microsoft Excel or Access.
FORM GET FUNCTIONALITY
- Can Query data files exported from Microsoft Excel or Access
  - Field Name to Query on
    - Query Field Name to Match with the Query (Specific Value, or All Fields)
  - Field Names to Include with the Query
  - Sort Numerically, Alphabetically, Forward or Reverse.
- HTML file to merge results with
  - Options to keep or remove form tags

Examples

Several examples have been included to show various ways how this CGI can be used.
These samples show the HTML code along with what the results look like.
The examples used here are only using FORM INPUT statements.
The CGI supports all other FORM tags also like CHECKBOX, RADIO, SELECT, and TEXTAREA.

Example 1
- A generic form that just emails its results using its default output. Here we will also have
  the CGI generate its generic user response page prior to sending email.
Example 2
- A form that does not require a response page, but uses a formatted email response.
Example 3
- This example will use both a formatted user response and email response. This new example will create a ongoing database.
  The database file created will be called vf_ex3data.csv. It will store all the fields from the form page.

Example 4
- This example will use the GET method functionality of vform to read data back from the CSV file created from Example 3.

Form Tag Usage

The following information will describe what input fields the CGI requires an what are optional.
A brief explanation of what each input field does and what options it takes is also outlined.

**The following field names ARE REQUIRED by this CGI**
FIELD NAME	DESCRIPTION
VF_ReturnURL	- This is the page the CGI will return to upon completion of the form. Example: <Input type="hidden" name="VF_ReturnURL" value="http://mydomain.com/mypage.html" >
VF_MailTo	- This will be the email address the form data is mailed to. The email address must be a fully qualified host and domain name. Multiple receipts can be specified by separating the names with a comma. Example: vicd@mail.ar51.net <Input type="hidden" name="VF_MailTo" value="webmaster@mail.thisdomain.com" > If the value="NONE" is used then there will be no email reply
Submit	- This must be used to submit form data to the CGI. Example: <Input type="submit" name="Submit" value="Continue" >
Accept	- Required when a verify user response is needed. Example: <Input type="submit" name="Accept" value="Continue" >

**The following field names ARE OPTIONAL by this CGI**
FIELD NAME	DESCRIPTION
VF_FormTitle	- This will be the title that is displayed upon displaying the data that the user entered, prior to accepting the form data. Example: <Input type="hidden" name="VF_FormTitle" value="Your Response Message" >
VF_Subject	- This will be the subject that is used with the email. Example: <Input type="hidden" name="VF_Subject" value="Web Form Data " >
VF_REQUIRED	-This hidden fields value parameter may hold the field names required by the HTML form. Example: <Input type="hidden" name="VF_Required" value="field1,field2" >
VF_FormTemplate	-This optional field allows the webmaster to create a custom output form template that will be used to email the form results. -This template file must contain the form names that are used in the actual form. -Optional parameters that can be use are REMOVE_TAGS, and NODUP. This option will direct the CGI to replace the FORM tag with the data acquired verses just assigning the "value=" attribute. -Option NODUP is used in conjunction with the REMOVE_TAGS option. Example: <Input type="hidden" Name="VF_FormTemplate" value="/mergefiles/file1.htm, OPTION1, OPTION2" >
VF_DBFIELDS	-This option allows the webmaster to create a real-time database file. The file that is created will format its output data using CSV (Comma Separated Values). -The value= field will have to contain the filename to create along with the field names to save data for. Example: <Input type="hidden" Name="VF_DBFIELDS" value="filename.ext,field1, field2, etc" >
VF_ReplyEmail	-This optional field will allow the CGI to use the field name provided by the value= attribute as the user field to use as the sender of the form data. Example: <Input type="hidden" Name="VF_ReplyEmail" value="USER_EMAIL_FIELD" >
VF_VERIFY	-This optional field will allow allow for a verification page to be displayed or not. -By default if this option is not used there will be no verification page. If the value= is set to "1" or "TRUE" then the CGI will use its default output verification page. -If the value= attribute is set to a full path to a valid file name that is readable, then the form data entered will be merged with this as a verification page. -Optional parameters that can be use are REMOVE_TAGS. This option will direct the CGI to replace the FORM tag with the data acquired verses just assigning the "value=" attribute. Example: <Input type="hidden" Name="VF_VERIFY" value ="Boolean 0/1 or TRUE/FALSE" or value="VerifyFile.html, OPTION1, OPTION2" >
VF_NoFileHeader	When using the VF_DBFIELDS or VF_DBFILE options, this parameter implies NOT to create or use a field header record. Example: <Input type="hidden" name="VF_NoFileHeader" value="1"> DEFAULT is to use field names
VF_FieldSeparator	With this hidden field option the field separator to use for creating or reading from a data file can be specified. The value is given as a encoded hex value. Example: To use the TAB character as the field separator <Input type="hidden" name="VF_FieldSeparator" value="%08"> DEFAULT="," (CSV Comma Separated Value format)
VF_Debug	This allows for VFORMII to output a extra debug log file the the log file directory. The values field can be from 0 - 9. Where 9 is the highest debug level to use. With the level set to 3 or above can cause the debug file to get quite large.

Names in Italic and colored are future options:

**The following Table shows the form GET names**
FIELD NAME	DESCRIPTION
VF_DBFILE	This is the DATA FILE to make the queries from. Current file format supported is CSV (Comma Separated Values) EXAMPLE FILE FORMAT Example syntax <input name="VF_DBFILE" value="VF_ex3data.csv">
VF_MERGEFILE	This is a optional (usually used) html file template. This file would contain the form INPUT tags of where to insert data. INPUT tags then contain the field name used in the DATA FILE. Options available are: REMOVE_TAGS NODUP Example syntax <input name="VF_MERGEFILE" value="VF_merge.htm,REMOVE_TAGS,NODUP">
VF_QNAME	This option is used to specify the Field name to query on. <input name="VF_QNAME" value="NAME">
VF_QVALUE	This form input name is used to specify a specific value to query on, or wild card query. <Input name="VF_QVALUE" value="*">
VF_INAME	This form input is used to specify other fields that should be included, once a query is found. <Input name="VF_INAME" value="SEX,COMPANY,PHONE"> or as individual options <input name="VF_INAME" value="SEX"> <input name="VF_INAME" value="COMPANY"> <input name="VF_INAME" value="PHONE"
VF_FieldSeparator	With this hidden field option the field separator to use for creating or reading from a data file can be specified. The value is given as a encoded hex value. Example: To use the pipe character as the field separator <Input type="hidden" name="VF_FieldSeparator" value="\|"> DEFAULT="," (CSV Comma Separated Value format)
VF_QWILD	This option works with the VF_QVALUE. It will allow for a partial or specific match. The default uses partial matches. Example: For specific searching of the VF_QVALUE <Input type="hidden" name="VF_QWILD" value="0"> For partial searching which is the default method <Input type="hidden" name="VF_QWILD" value="1"> All searches are non case sensitive.

Optional command line parameters that can be used when calling the CGI are:

PARAMETER	DESCRIPTION
D#	- The 'D' enables extra logging information into a .debug file - The '#' represents a number from 1 - 9. This will define the log level. Where 1 is minimal logging where 9 would be max logging.
V	Prints out the version of this CGI

Example to display the version of the CGI: /cgi-bin/vformfm.cgi?V

Data File Format

name,sex,company,title,phone,email,DATE
Victor,Male,Area 51 Consulting,VP Software,330-374-0351,guru@ar51.net,Aug 11 16:24:53
John,Male,Area 51,CEO,,johnr@ar51.net,Aug 13 12:06:59

Configuration File

Vform relies on a configuration file that resides in the CGI directory. The following configuration options are available and defined as follows.

Configuration Option	Description
RootDir=	The root directory is the base directory defined by the web server. This will be the directory of where files to merge with will start. DEFAULT is the value returned from the Web Servers environment variable DOCUMENT_ROOT.
DataDir=	The data directory is a directory that needs to be read/write by the CGI for usually user nobody. (chmod 777 or 770 with group set to user nobody) This will be the directory that the log and debug files will be written to, along with any data files that need to be created. This does not necessary need to be a readable directory if there is no intent to share the data to the web user. DEFAULT is to use the CGI's directory ./formdata. (cgi-bin/formdata) The formdata directory will need to be created. This directory will need to have read/write permissions for user nobody or (the owner of the webuser).
LogFileDir=	The directory and file name to use for the log file. DEFAULT is is to use the CGI's directory ./formdata. With the file name of "vformfm.log".
UserHomeDir=	Home directory of where users files are located. This is for when the Web server is running with user home directories. Example: /home
UserBaseDir=	This is the base directory that the Web server uses in side a users home directory. Example: public_html

History

DATE	DESCRIPTION
12/16/1999	Prefixed field names with "VF_". The fields affected are as follows: MailTo, ReturnURL, Subject, FormTitle, DF -> VF_DBFILE, MF -> VF_MERGEFILE, Q -> VF_QNAME, I -> VF_INAME, QV -> VF_QVALUE
03/01/2000	Added VF_FieldSeparator to GET and POST functionality. Corrected documentation VF_INAMES changed to VF_INAME.
03/03/2000	Restructured this document into seperate files. Corrected formating issues when dealing with special characters. Corrected white space parsing when reading or writing to a data file.
05/24/2000	Added new TAGS VF_Debug, and VF_QWILD. Fixed some internal buffer issues when dealing with large CSV files. Added a BACK button on the page that displays "Required Fields Missing" for when USER Required fields do not pass.