2. Overview
3. Installation
4. The Form
- recipient
- bcc
- valid_attach_types
- non_valid_extensions
- valid_attach_extensions
- required_fields
- require_attach -- Version 2.0 and above.
- banned
- subject
- send_blank_fields
- redirect
- auto_responder
- Environment report
- Header/footer files
- Safe Mode
Copyright 2004 Richard Harkrider (c) All rights reserved. http://www.hiqformmail.com. This application will only function at PHP Version 4.1 or higher. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT
WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
THE USE OR OTHER DEALINGS IN THE SOFTWARE. OVERVIEW INSTALLATION |
|
The action of your form needs to point
towards HiQFM.php. |
| Optional Form Fields The optional fields below require specific processing by the HiQ Formmail script and should be used as stated. In addition to these you are free to define fields in your forms as needed. Information from any other form fields will be included in the email. |
Field: subject
Description: Email subject.
Usage:
The subject field can be used to override the config file subject entry that you wish to appear in the e-mail.
To Top<input type=hidden name="subject" value="subject">
Field: email
Description: This form field will allow the user to specify their return e-mail address.
Usage:
If you want to be able to return e-mail to your user, I strongly suggest that you include this form field and allow them to fill it in. This will be put into the From: field of the message you receive. While the script checks the syntax there is no way to verify that the email is valid. Typos are common.
To Top<input type=text name="email">
Field: redirect
Description:If you wish to override the redirect value entered in the config file, you can use this hidden variable as below.
Usage:
To choose the URL they will end up at
To Top<input type=hidden name="redirect" value="http://your.host.com/to/file.html">
Field: attachment[]
Description:This allows the attachment of one or more files to the email.
| --NOTE-- If sending attachments when Safe Mode is activated there are additional requirements. CLICK HERE for specifics. |
Multiple attachments are supported and because of this it is ALWAYS necessary to include the []. The script will not work without this.
Multiple file attachment example:<input type="file" name="attachment[]">
Would allow up to 4 files to be attached to the email.<input type="file" name="attachment[]">
<input type="file" name="attachment[]">
<input type="file" name="attachment[]">
<input type="file" name="attachment[]">
In most instances, it is advisable to also use the following when sending attachments MAX_FILE_SIZE - (case sensitive) hidden field must precede the file input field and it's value is the maximum file size accepted. The value is in bytes.
--NOTE-- If having trouble trying to email large attachments (usually in excess of 2MB) and having problems it is usually a server issue. On many installations the Apache server limits file uploads to 2MB.<input type="hidden" name="MAX_FILE_SIZE" value="1000000">
To Top
Field: configfilename
Description: If using a configuration file with a name other than the default or are using multiple configuration files this information is passed to the script by a hidden form field. File name only WITHOUT THE EXTENSION.
Usage:
When the form is submitted, the information from the specified file will be used to configure the script. That file MUST be located in the same directory as HiQFM.php.
--NOTE-- The configuration file(s) MUST always have .conf as the extension.
If you have a configuration file named myconfigfile.conf
The form would have configfilename set to myconfigfile as in:
To Top<input type=hidden name="configfilename" value="myconfigfile">
Advanced Features
The advanced optional entries can be used to greatly enhance the operation of HiQFormmail.A couple things are important to understand here.
1. A 'scalar' field name can only pass 1 entry to the script. If the field name appears more than once in the form only the last entry will appear in the resulting email.
Example:
When the form is submitted, the email will contain *only* arlene.<input type=hidden name="Scalar_Field" value="fred">
<input type=hidden name="Scalar_Field" value="arlene">
2. An 'array' field name can be used to pass multiple values to the script. If the field name appears multiple times in the form them multiple values are passed to the script.
Example:
When the form is submitted, the email will contain *both* arlene and fred<input type=hidden name="Array_Field[]" value="fred">
<input type=hidden name="Array_Field[]" value="arlene">
It is very important to understand that the [] at the end of the name makes a world of difference and can be quite powerful as will be shown below. The big initial advantage is allow multiple select boxes and multiple/single select lists.
To Top
Field: MultipleValueFormat
Description: This option allows defining the way 'array' field form entries are displayed in the email.
Usage:The default is 1 per line as in:
Field Name: value 1
Field Name: value 2
By choosing the column option as in:
the same form input would be:<input type="hidden" name=MultipleValueFormat value="column">
Field Name: value 1 & value 2
--NOTE-- the default seperator is & With the above the value(s) are displayed seperated by a & as in:
Field Name: value 1 & value 2
This can accept entry of a second value following a comma. This will be the string used to separate the values.
With the above the value(s) are displayed seperated by the string and as in:<input type="hidden" name=MultipleValueFormat value="column,and">
Field Name: value 1 and value 2
To Top
Field: SelectRecipient[]
Description: Use to select 1 or more users from the list of recipients defined in the config file.
| --NOTES-- 1. User is defined as that part of the email address which precedes the @ in an email address. MOST IMPORTANT TO REMEMBER THIS. 2. If an input error occurs (like a typo) such that the requested user is not found then the no mail will be sent. 3. When a requested user is not found an error is issued and execution stops with no mail sent. 4. The SelectRecipient[] name is case sensitive and MUST be entered exactly as you see it here. |
SelectRecipient[ ]
This field provides a lot of flexability for choosing recipients since it can be used with single & multiple selection check boxes, hidden input and the value can be a single or multiple users seperated by comma(s). Its value is used to email the form to a matching entry (or entries) in the recipients list as defined in the config file. In addition, this field is useful when you have more than one form on a web site, but each form is sent to a different recipient - no need to use multiple config files where each has its own unique recipient defined.
For example, the HiQFM config file would have these recipients defined:
[recipient] betty@mydomain.com
[recipient] fred@mydomain.com
[recipient] allen@mydomain.com
[recipient] arlene@mydomain.com
[recipient] harold@mydomain.com
[recipient] support@mydomain.com
The form would have SelectRecipient[] set to a particular "user", in this case "support":
<input type="hidden" name="SelectRecipient[]" value="support">
When the form is submitted, the email would be sent *only* to support@mydomain.com.
To send to multiple recipients, simply separate the users with a comma:When the form is submitted, the email would be sent to both fred@mydomain.com and harold@mydomain.com<input type="hidden" name="SelectRecipient[]" value="fred,harold">
In Addition the following are also valid when giving form subitters the ability to select recipients.
<input type="checkbox" name="SelectRecipient[]" value="user03"> user03
<input type="checkbox" name="SelectRecipient[]" value="user04"> user04
<input type="checkbox" name="SelectRecipient[]" value="user10,user11,user12"> Sale
<select name="SelectRecipient[]" size="3" multiple="multiple"> <option>user05</option>
<option>user06</option>
<option>user07</option>
<option>user08</option> </select>
All the above are valid uses and can be used separately or even together.<select name="SelectRecipient[]" size="3">
<option>user05</option>
<option>user09</option>
<option>user08</option>
<option>user07</option> </select>
To Top
Field: SelectRecipient_Special
Description: This option is provided for that very 'special' case where the email recipient(s) are determined based on some specific information from the form other than the user name(s). This is often done using JavaScript or some other method . When unable to deal with setting the user list to an array for passing off to HiQFM.php use this.
The value can consist of 1 or more users seperated by comma(s).
| --NOTES-- 1. User is defined as that part of the email address which precedes the @ in an email address. MOST IMPORTANT TO REMEMBER THIS. 2. If an input error occurs (like a typo) such that the requested user is not found then the no mail will be sent. 3. When a requested user is not found an error is issued and execution stops with no mail sent. 4. The SelectRecipient_Special name is case sensitive and MUST be entered exactly as you see it here. |
Usage:
SelectRecipient_Special
This field is typically a hidden field in the form. Its value is used to email the form to a matching entry (or entries) in the recipients list defined in the config file. In addition, this field is useful when you have more than one form on a web site, but each form is sent to a different recipient - no need to use multiple config files where each has its own unique recipient defined.
For example, the HiQFM config file would have these recipients defined:
[recipient] betty@mydomain.com
[recipient] john@mydomain.com
[recipient] quasimoto@mydomain.com
The form would have SelectRecipient_Special set to a particular "user", in this case "john":
<input type="hidden" name="SelectRecipient_Special" value="john">
When the form is submitted, the email would be sent *only* to john@mydomain.com.
To send to multiple recipients, simply separate the users with a comma:When the form is submitted, the email would be sent to both john@mydomain.com and quasimoto@mydomain.com<input type="hidden" name="SelectRecipient_Special" value="john,quasimoto">
How to dynamically set SelectRecipient_Special
Now, to take things a step further, let's say you have a form that has to be directed to a different recipient based on something the user selects on the form. In this case, you wouldn't be able to hard-code the "user" values. Remember, for our puroses, the term user defines the part of the email address before the @domain, for example: MORE>>>>.To Top
HiQ Formmail configuration file definition.
HiQ Formmail takes a different approach to processing form generated email. Instead of configuring the script by way of hidden form fields as most form handlers do the HiQ Formmail script is configured from information contained in 1 or more files. I feel that while a bit more of a job to configure there is a higher level of security and flexibility.
Configuration of directives take the form of
[directive] value (multiple values are entered 1 per line)
Lines beginning with a # are comments.
To Top
recipient / bcc:
# Multiple values are entered 1 per line.
[recipient] user@somedomain.com
[bcc] none
To Top
valid_attach_types:
# --NOTE -- To allow any file type set value to 'all' as in...
# [valid_attach_types] all
[valid_attach_types] image
[valid_attach_types] text
To Top
non_valid_extensions:
# List of file extensions which are not allowed entered 1 per line or multiple values seperated by comma(s).
# Default list is bat,com,exe,scr,vbs,vbe,js,reg,pcd,inf,plf and pcd
# Add additional here
[non_valid_extensions] none
To Top
valid_attach_extensions:
# List of file extensions which are allowed entered 1 per line or multiple values seperated by comma(s).
# --NOTE -- Used to only allow attachment of files with specified extensions.
# Non valed extensions will take precidence over these values.
[valid_attach_extensions] none
To Top
required_fields:
#list of required form fields entered 1 per line.
[required_fields] none
To Top
require_attach --- Version 2.0 and above.
# To require attachment(s) set to yes.
[require_attach] no
To Top
banned:
# Banned emails, email addresses of people who are blocked from using the script.
# Ex. *@somedomain.com,user@domain.com,etc@domains.com
[banned] none
To Top
subject:
# Items below only accept single values.
[subject] Form Submission processed by HiQ Formmail.
To Top
send_blank_fields:
# By default blank fields not sent - to change set to yes.
[send_blank_fields] no
To Top
redirect:
# Html file to redirect the user to after form is processed.
[redirect] none
To Top
auto_responder:
# File to be emailed to the form submitter.
[auto_responder] none
To Top
Environment report:
# Environment report is used to include information about the form user.
# To activate an item change to a yes.
[HTTP_HOST] no
[HTTP_REFERER] no
[REMOTE ADDR] no
[BROWSER] no
To Top
Header/footer files:
# Header/footer files -- wrap output to blend with site design.
[er_header_file] er_header_def.htm
[er_footer_file] er_footer_def.htm
[header_file] header_def.htm
[footer_file] footer_def.htm
To Top
Safe Mode:
# Items below apply only to Safe Mode operation.
# The directory defined here MUST be in (or under) the same directory as HiQFM.php
# and have world write permissions (CHMOD 777).
[safemode_temp_dir] TEMP_FILES
# For Safe Mode set this to a non-zero value.
[safe_mode] no
To Top