Welcome to the www.dtp-aus.com ennyForms script - version 2.07b MODULES.
IMPORTANT INFORMATION THAT MUST BE READ

The program "ennyfrm.cgi" was written (and ©) by Ron F Woolley, Melbourne Australia. Copyright 1998'99 2000. This program can be altered for private site use and commercial site use,
EXCEPT THAT:
  ALL COPYRIGHT NOTICES must remain in the code, visible on all output pages,
  AND ALL of the header notices MUST REMAIN intact visible as is,
  AND using the script(s) without first reading the README.HTM, is prohibited.

Australian copyright is recognised/supported in over 130 countries per Berne Convention
and other treaties ( including USA ) - copyright registration is not required!

The scripts and associated files remain the property of Ron F Woolley.
NO PROFIT what so ever is to be gained from users of these scripts for the use of these
scripts, except that a reasonable minimal charge for installation may be allowed if installing,
as a site developer, for a user on the users site that is not on / in the developers domain.
This program must NOT be used for multiple ennyForms users on one site/domain
and the program and resources must not be supplied as a remote service

Ron Woolley, the author, MUST be notified via the addresses/URLs below
if any monetary charge is applied for the installation of these scripts.

NOTE: If you use these files, you do so entirely at your own risk, and take on full responsibility for the consequences of using the described files. You must first agree that Ron Woolley / HostingNet, the only permtted supplier of this and/or accompanying files are exempt from any responsibility for all or any resulting problems, losses or costs caused by your using these or any associated files.

If you disagree with any of these requirements,
you must immediately destroy all files.

Although this program script is free to use, if you use it and find it useful, a donation to help continue this support and keep new scripts / upgrades coming would of course be appreciated.
      On line Visa / MasterCard payments are available for donations and low cost installations.

These files can only be obtained via the above web addresses, and
must not be passed on to others in any form by any means what so ever.
This does not contradict any other statements above - and ensure you have the latest.


ALL COPYRIGHT NOTICES MUST remain in the code and output pages, visible as is.
I at least do not include page links back to myself as many programmers do.

ennyForms MODULES
update** Version 2.07, April 2000 **update

These modules allow:
Saving of e-mail addresses to list files (E-Lists and ListMerge compatible)
Enable the ListMerge option of "user selected" Plain Text or HTML e-mails
UN-Subscribing from e-mail list files - new v2.06
Saving of data using one of two methods, to flat-file data base files
Use your own "Thank you" page when needed.
Add a reference "quote" number to the output
Return a copy of the visitors input to the visitor
Replace default texts with your own.
...and you can apply any of the above separately to each form, and:

You should have thoroughly read the readme.htm page, and both prepared and successfully used a form for basic mail-form tasks before enabling any of these extensions.

I have referred to these extensions as "modules" because they can be left off the server if not needed, or just plugged into any form when required by adding a few extra input tags.

v2.07b is a minor code change to the program and four .pl files - straight overprint upgrade from v2.07. The e-mail date line is now smtp compliant BUT reflects the correct international GMT date/time as your local time - good for business applications.

NOTE: ALL mail address files created for foms ("multi recipients" and "user selected recipient" address files) can now contain a name with each address which is added to the mail headers. Note the samples where a name is added AFTER the address divided by " : ".


"opts"
First I will list this tags options also mentioned in the readme.htm.
<input type="hidden" name="opts" value="EDdCQTnSsXxwmo1234">

The "EDdCQnSsXxw" properties shown in the value attribute perform the following tasks:
  "E"=show e-mail error warning and stop submission - subscribe option
  "D"=save input as database fields
  "d"=add quote marks to delimited data base fields
  "C"=send a return copy of visitor input back to the visitor
  "Q"=include a unique reference number in the output
  "T"=don't send "confirmation / thank-you" e-mail - see readme.htm page
  "n"=remove any null (empty) objects returned by the browser - see readme.htm page
  "S"=swap program URL to SSL secure server URL in preview - see readme.htm page
  "s"=also scramble visitors e-mail "scrambled" input in webmasters e-mail - see readme.htm page
  "X"=block Preview option and go straight to "success" page - see readme.htm page
  "x"=block all e-mail to the wemaster - see readme.htm page
  "w"=exclude inclusion of form results from webmasters e-mail - see readme.htm page
  "m"=use a mail texts replacement text file of your own creation - see "returning a copy" below
  
"0,1,2,3, or 4"=override $addr_only; saved 'Subscribe' option mail list type - subscribe option


SAVING FORM INPUT TO AN EMAIL LIST - "Subscribe"
NOTE the new (v2.06+) extra characters added to the 'Subscribe' object value.

The config file, "enyfrmset.pl", contains variables for the directory, format, delimiter, and file name extension of saved email lists - see readme.htm and below for details (previously some of these variables were contained in the mail module).

To enable an email list, add one or both of the following two "Subscribe" tags to your form.

Subscribing
1. This first method forces the saving to a list without visitor selection - not recommended unless they are told of it happening somewhere on the form page. (but note that if not used for mailing this hidden option can be used with the /E/ opts switch to stop repeat submissions to other forms!)
   <input type="hidden" name="07Subscribe" value="ennylst:1">
The value (ennylst is shown) is the name of the list file the address is saved to for this particular form. Make this anything you want to for simple file name identification.
NOTE: The "07" only represents field markers described in the readme.htm.

2. The second method allows a visitor to choose to subscribe to your email list via a "checkbox". This is obviously the preferred method.
   <input type="checkbox" checked name="07Subscribe" value="ennylst:1">
The value (ennylist is shown) is the name of the list file the address is saved to for this particular form. Make this anything you need to for simple file name identification.
NOTE: The E-Lists program is designed for dedicated subscriber mail list-only forms. ListMerge is a powerful mass mailer with "batch" mailing capability accepting the user selectable "Plain Text" or "HTML" mail formats from ennyForms Subscriber forms.

Refusing a Second Submission
If the form is submitted by a visitor who has already subscribed to that list, the address will be ignored and not added again. However, should you have a situation where multiple form submissions are to be refused, by adding one option to the "opts" hidden tag the form submission will not proceed, no mail will be sent, and an error page will warn the subscriber that repeat submissions are not allowed.
NOTE This could used in other forms just to stop repeated form submissions - tag above but hidden!

To display this error, add "E" to the opts hidden tag:
  <input type="hidden" name="opts" value="E">
NOTE: This can be in addition to other opts values already included.

UN-Subscribing - New v2.06
By adding a second radio button to a form the user can be offered the opportunity to UN-Subscribe form your lists when ever they so desire - it is a good idea to mention this as a brief note in the auto response mails to enhance perceived confidence in your site.

To do this make one slight change to a duplicate subscribe radio button ie:
   <input type="checkbox" name="07Subscribe" value="ennylst:0">
The value (ennylist is shown) is the name of the list file the address is saved to for this particular form.

The COMPATABILITY Variables AND the E_LISTS / LISTMERGE Programs
In the enyfrmset.pl config file there are variables that must be preset to control where the mail lists are saved to, the delimiter used between fields, the file name extension, the format of the list, plus a variable that specifies the "form common" object name of ALL ennyForms forms "first" or "full name" entry boxes.

• The latter ( $form_firstname ) is "Name" by default but can be changed (set this in config without the special "field markers" used for sorting etc). "Name" is versatile enough to use on forms requesting a first or full name and should not need changing. ennyForms then knows which object name to use with every form saving to mail lists.

$addr_only
• Another is the $addr_only config value, familiar to users of E-Lists and ListMerge programs:
1. A value of "3", will only save the e-mail address to a simple list file.
2. A value of "0" (null) will save the address, and name, and date.
3. A value of "1" will save the address, and name.
4. A value of "2" will save the name, and then the address.
5. A value of "4" will save the name, and then the address. - new v2.07

Overriding the config "$addr_only" value
The config default option ($addr_only) can be overridden simply by adding one of the above numbers to the forms hidden "opts" value:
  <input type="hidden" name="opts" value="0"> - or "1" or "2" or "3" or "4"
NOTE: This can be in addition to other opts values already included.

Like E-Lists, these options can be chosen for common or alternate list formats which can then be used on your local PC or via WEB based programs to send personalised "merged" mass mail-outs. Whatever your needs one of the above formats should do the job.
• ListMerge also knows which fields it can "merge", AND detect the following HTML mail option!

Plain Text or HTML formatted mail-outs - a ListMerge option
new v2.07 By adding the following to your form the user can select whether to receive normal Plain Text e-mails via your mail-outs OR receive HTML formatted e-mails.

The object name is a reserved word!
  HTML <input type="checkbox" name="15Mail-Format" value="html">
      OR perhaps a radio button "group":
  Text <input type="radio" checked name="32Mail-Format" value="normal">
  HTML <input type="radio" name="32Mail-Format" value="html">

List Options Delimiter
• Another is the $sep variable which tells the program what delimiter to use to divide:
1. the list fields saved as a result of the $addr_only variable
2. addresses placed in the multi recipient and user selected multi recipient files.
Basically all mail files used by ennyForms that contain multiple fields MUST be separated or will be separated by this value.

Lists File Name Extension
• Another is the $elst_exten mail list file name extension. The default is ".elf" which should not conflict with other cgi programs. However should you already have programs saving to lists then this can be changed to suit. ennyForms makes up the file name for particular forms from the "frmName" hidden tag and creates them automatically.

Lists Directory
• Last is the variable that points to the desired directory containing your e-mail lists and where new ones are to be created.

Except for the common form "Name" input box name, all the above have been refined for full compatibility with E-Lists and ListMerge - which contain the same set-up methods in their config files. While it is easy (greatly so!) to just hard code much of this, these options enable versatility and compatibility between a suite of powerful programs. There were one or two ennyForms compatibility "bugs" which have been finally ironed out with v2.06.

So if you only want to save e-mail addresses to lists, then the email list module is simple to enable just by including the subscribe/un-subscribe buttons - files are created automatically.


SAVING FORM INPUT TO A DATA BASE FILE

The config file, "enyfrmset.pl", contains a variable for the directory of saved data base files - see readme.htm. To enable data base saving, add the following option to the "opts" hidden tag.
  <input type="hidden" name="opts" value="D">

You already have a hidden tag in your forms that contains the forms name (frmName - a reserved word). The database module uses the first eight characters of this form name to create a data base file name - it is automatic.

Option ONE
This first option of the data base module will save to a file, all input tags that include the field marker "_r" (or "required" input entries) - you can even include hidden, radio button, or drop-menu tags etc that already have a default option selected. Remember that form objects not having a value cannot be recognised by a server - only those with a value get sent from the browser

Option TWO - the best and most useful
To allow more than just 'required' entries to be saved, even empty objects, you can add one hidden tag to a form plus prepare a very simple template file that tells the module what to record as a field.
This additional hidden tag must contain the file name of the template created for that form, ie:
  <input type="hidden" name="db" value="form1.tpt">

Your default "ennydb" directory contains one such template file sample. As long as the spelling AND case is identical, this module will read the sent values, and place a null value in the field names it cannot match. Make sure you chmod template files to 766 (or 777 per the readme.htm)

Delimited and "" Quote-Enclosed Data Base Fields
For data base files to be of any use, every record must have the same number of fields. Both options for this module can be set up correctly to ensure this happens. The fields are separated by the vertical line pipe character by default, ( | ), and this must be remembered when downloading and importing the db files. Some times it is preferred to also identify the field values enclosed in quotes ( ""|""|"" ) - record filed strings. If you require this, then simply add one more identifier to the "opts" hidden tag, ie:
  <input type="hidden" name="opts" value="d">

The lower case "d" combined with the upper case "D" will enclose each field with quotes.

Changing the delimiting character v2.04+
Near the top of the code in the "ennydb.pl" file there are three lines for a "$delim" varaible. Two lines have the hash (#) character at the start. If you want to use a Tab or Comma delimiter, then remove the appropriate hash character AND then place one at the start of the default value line.

Adding environment fields to the records - using the db template option.
You can add environment variables to the data base records by including the following in the template file described above. Date and Time are split for DB program use etc.
  DTME = date
  TTME = time
  ENVREF = users IP# or Remote Host - depends on your server.
See the sample template file for reference.

Including the Reference Number
If the "opts" [ Q ] and [ D ] option values are used to generate quote or reference numbers plus a db file, AND you want to include the number in the saved data base, inlcude the "qte" name in the template file. Refer to samples "form1.tpt" and "form2.tpt" for reference.

HANDY HINT
To easily create a data base template file with all spelling and case exactly as your form object names, run your form with the preview option. Drag the cursor over the preview list, copy the highlighted text, and place in an empty "WordPad" document (or similar) window. Then it is a simple matter of deleting the rubbish and very quickly you will have a list of exact spelling etc - remove items not needed and add any of the above extras.

The problem with Mail-Form type programs is that the one script has to work with an unlimited number of form variations. Also, It has already been mentioned that the server may not know an input object exists on a form unless its value is more than null (nothing).


ADDING A REFERENCE Quote NUMBER

This is the easiest of the "module" options to add to ennyForms output. All it takes is to add one option to the "opts" hidden tag, and reference numbers will be added to that forms output and e-mail. Just add the upper case "Q" to the tag as follows:
  <input type="hidden" name="opts" value="Q">

A new number will be generated each time the preview page is activated, and the same count file is used by all forms. However, the reference number will contain the first character of the form name for identification, and will have the month and day values appended on to it also. I am sure there are plenty of people who can make use of this simple module without using dedicated programs.

Note the info above regarding the inclusion of this number in saved data base records.


RETURNING AN INPUT COPY

This module is also easy to enable, and there is one variable in the "ennycopy.pl" module file that needs to be changed, or deactivated. First, to enable the returning to the visitor, a copy of all their input to your form(s), just add upper case "C" to the "opts" hidden tag, ie.
  <input type="hidden" name="opts" value="C">

With this enabled, the module will send the users input, not your hidden tags, back to the visitor. The script will also recognise this and disable the simple default auto-response mail message (if left activated - see readme.htm).

New v2.04 Read the readme.htm page for info on hiding OR scrambling selected input data when sending a full "C"opy of the form back to the visitor... good for on-line order forms etc.

Personalising - a form specific file AND the new /m/ opts switch
NOTE: This will work for both the /C/ returned copy (this section) AND the default response.
You can add your own texts above this returned mail which can also personalise by imbedding the users name (if supplied by the form). This is done by reference to the "$form_firstname" variable in the config file. If an object of that name is found then a special field marker () is replaced with the users Name input.

Note this text file can be switched off or on for various forms using the same "frmName" value by placing the /m/ switch in the forms hidden "opts" value.

To use the text the file has to exist in the new "ennymore" sub directory, have the extension of ".emt", and have the file name created as described in the supplied "testfeed.emt" sample.

Using this feature only the default footer section of the mails will be used (plus the full input copy as explained in this section). Your text file has to contain the rest of what you want to say!!.


ALL COPYRIGHT NOTICES MUST remain in the code and output pages, visible as is.


Enjoy - & please let me know how you get on with this script, how/what server type it installed to, how well the modules operated etc. Notify me if bugs are found and a fix will be forwarded to you.
      Ron