|
NOTE: In One on One Internet's
ongoing efforts to prevent spamming from our
servers, account owners must use our server-wide
version of formmail.pl located at /cgi-sys.formmail.pl.
Local copies of formmail.pl found in any accounts
cgi-bin will be deleted.
In order for formmail.pl to work,
it is required that you have a .FormMail.conf file
in your home directory. This file aids in the prevention
of SPAM through your domain, thus preserving your
bandwidth for legitimate users of your site. In
addition, it enables you to enhance your forms
and provide shortcuts that not only simplify your
forms, but also enable you to hide your e-mail
address from spiders and e-mail harvesters.
To use Formmail, you need to create
a form on one of your web pages.
The form action line should be:
<FORM ACTION = "/cgi-sys/formmail.pl" METHOD
= "POST">
formmail.pl will do all the programming
work for you. You alter the behavior of Formmail
by using hidden fields in your form.
There is only one form field that you must have in your form for FormMail
to work correctly. This is the recipient field.
NOTE: As mentioned above, this is
an example of where the .FormMail.conf file comes
into play. Any recipient that you have specified
in your form must also be listed in your configuration
file. Please refer to the example configuration
file at the end of this page for detailed instructions.
Before you are able to use formmail,
you will need to create your configuration file.
This can be done in one of two ways. The first
method is using the File Manager in your control
panel, and the second is if you have ssh access
to your domain. Either way will work equally well
for this application. If you have any trouble with
creating your conf file, please contact support
for assistance.
Method One: File Manager
- You will find the configuration
file text at the bottom of this page. Simply select
the text with your mouse, right click your mouse
and choose 'copy'.
- Once the text is copied, go to your Control Panel main menu, and click
on the File Manager icon.
- When the File Manager screen loads, type '.FormMail.conf' (without
the quotes) in the text area to the left of 'Create/Edit file', and click
'Create/Edit file' with your mouse.
- When the page loads, right click your mouse and select paste. (If the
file is not empty, you already have a configuration file, and can skip
this step.)
- After you paste the text, change the 'Size' to 90 so that it will be
easier for you to read and edit.
- Scroll through the text of the configuration file, being sure to update
the values to suite your needs.
At the very least, you will need
to enter your domain name (without the 'www.')
in between the 'allow_mail_to' lines, and put your
e-mail address in between the 'postmaster' lines.
Once your changes have been made,
click the 'Save' button.
At this point, you can send e-mail
via forms in your html files to any e-mail address
set up on your domain. If you would like to send
e-mail to other addresses other than ones set up
on your domain, simply add the e-mail addresses
in between the 'allow_mail_to' lines of your configuration
file. (There is more detailed information explaining
this in the actual configuration file. Please read
over it and if you have any questions, please contact
support for assistance.)
NOTE: although you will not be able
to see your configuration file in the File Manager,
it is there. Because it begins with a 'dot' (.),
it is considered hidden. You can always access
it simply by typing the name in the text area manually.
Method Two: Command Line via SSH
This method may be considered a
more advanced method because of the 'vi' editor.
Its commands may be confusing to some individuals.
If you have any problems with this method, please
try the above method, or contact support for assistance.
First you will need to SSH to your
domain. Then, from the command prompt, type the
following:
cd /home/user (hit enter key) (Replace "user" with your domain's
username)
vi .FormMail.conf (the first dot "." indicates that this will
be a hidden file and not visible from the File Manager).
Now, within the vi editor,
IF the file comes up with a blank screen,
- use the i key "i" to activate insert mode
- switch to the browser window (this screen)
- select-n-copy the Example .FormMail.conf at the end of this page.
- when copied, switch back to the shell screen and paste the copied text
- when the lines are pasted in, type Escape "Esc" and then
colon 1 ":1" to goto the top of file (hit enter key)
Once at the top of the file, proceed to read the descriptions and get
yourself familiar with what their purpose is. When you come to 'postmaster'
and 'allow_mail_to', you will have to enter the values in between the
two lines marking the boudaries of those values. The rest is optional,
but very handy.
When you need to change the file,
please refer to these 'vi' commands:
Type "i" (to get into
insert mode)
Type "o" (to get into insert mode on the next line below your
cursor)
Type "u" (to undo your last change. note: cannot be in insert
mode)
Type "Esc" (to exit out of insert mode)
Type ":w" (to save the file)
Type ":wq" (to save and exit vi)
To save your entries and exit the vi editor, type the following:
(hit the <ESC> key)
:wq (hit enter key)
The email addresses in the ".FormMail.conf" allow_mail_to section
should match the email addresses in the "value" field (e.g):
<input type=hidden name="recipient" value="username@hotmail.com,anothername@yahoo.com">
The form action line should be:
<FORM ACTION = "http://domainname.ext/cgi-sys/formmail.pl" METHOD
= "POST">
NOTE: The above is also true if you would like to use your own secure
apache certificate for your forms. The only change is the FORM ACTION
line. The http:// gets replaced with https://. For example.
The form action line for a domain specific cert should be:
<FORM ACTION = "https://domainname.ext/cgi-sys/formmail.pl" METHOD
= "POST">
NOTE: The above is also true if you would like to use a server wide secure
apache certificate for your forms. The only change is the FORM ACTION
line. The root domain name is required between the servername and
the cgi-sys directory. For example.
The form action line for server wide cert should be:
<FORM ACTION = "https://host.servername.ext/domainname/cgi-sys/formmail.pl" METHOD
= "POST">
Field:
recipient
Description:
This form field
allows you to specify to whom you wish for your
form results to be mailed. Most likely you will
want to configure this option as a hidden form
field with a value equal to that of your e-mail
address.
NOTE: The recipient email address
must be at your domain, not @yahoo.com, @hotmail.com,
etc.
Syntax:
<input type=hidden name="recipient" value="joe@yourdomain.com">
Field:
subject
Description:
The subject
field will allow you to specify the subject that
you wish to appear in the e-mail that is sent
to you after this form has been filled out. If
you do not have this option turned on, then the
script will default to a message subject: WWW
Form Submission
Syntax:
If you wish to choose what the subject
is:
<input type=hidden name="subject" value="Your Subject">
To allow the user to choose a subject:
<input type=text name="subject">
Field:
email
Description:
This form field will allow
the user to specify their return e-mail address.
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.
Syntax:
<input type=text name="email">
Field:
realname
Description:
The realname form field
will allow the user to input their real name.
This field is useful for identification purposes
and will also be put into the From: line of
your message header
Syntax:
<input type=text name="realname">
Field:
sort
Description:
This field allows you to
choose the order in which you wish for your
variables to appear in the e-mail that FormMail
generates. You can choose to have the field
sorted alphabetically or specify a set order
in which you want the fields to appear in your
mail message. By leaving this field out, the
order will simply default to the order in which
the browsers sends the information to the script
(which isn't always the exact same order they
appeared in the form.) When sorting by a set
order of fields, you should include the phrase
'order:' as the first part of your value for
the sort field, and then follow that with the
field names you want to be listed in the e-mail
message, separated by commas.
Syntax:
To sort alphabetically: <input
type=hidden name="sort" value="alphabetic">
To sort by a set field order: <input
type=hidden name="sort" value="order:name1,name2,etc...">
Field:
redirect
Description:
If you
wish to redirect the user to a different URL,
rather than having them see the default response
to the fill-out form, you can use this hidden
variable to send them to a pre-made HTML page.
Syntax:
To choose the URL the user will
end up at:
<input type=hidden name="redirect" value="http://yourdomain/file.html">
To allow the user to specify a URL
he wishes to travel to once the form is filled
out:
<input type=text name="redirect">
Field:
required
Description:
You can now require for
certain fields in your form to be filled in
before the user can successfully submit the
form. Simply place all field names that you
want to be mandatory into this field. If the
required fields are not filled in, the user
will be notified of what they need to fill
in, and a link back to the form they just submitted
will be provided.
Syntax:
If you want to require that
the user fill in the email and phone fields in
your form, so that you can reach them once you
have received the mail, use a syntax like: <input
type=hidden name="required" value="email,phone">
Field:
env_report
Description:
Allows you to have Environment
variables included in the e-mail message you
receive after a user has filled out your form.
Useful if you wish to know what browser they
were using, what domain they were coming from
or any other attributes associated with environment
variables. The following is a short list of
valid environment variables that might be useful:
REMOTE_HOST - Sends the hostname
making a request.
REMOTE_ADDR - Sends the IP address of the remote host making the request.
HTTP_USER_AGENT - The browser the client is using to send the request.
General format: software/version library/version
Syntax:
If you wanted to find the
remote host and browser sending the request,
you would put the following into your form:
<input type=hidden name="env_report" value="REMOTE_HOST,HTTP_USER_AGENT">
Field:
title
Description:
This form field allows
you to specify the title and header that will
appear on the resulting page if you do not
specify a redirect URL.
Syntax:
If you wanted a title of 'Feedback
Form Results':
<input type=hidden name="title" value="Feedback Form Results">
Field:
return_link_url
Description:
This field allows you to
specify a URL that will appear as return_link_title,
on the following report page. This field will
not be used if you have the redirect field
set, but it is useful if you allow the user
to receive the report on the following page,
but want to offer them a way to get back to
your main page.
Syntax:
<input type=hidden name="return_link_url" value="http://yourdomain.com/main.html">
Field:
return_link_title
Description:
This is the title that
will be used to link the user back to the page
you specify with return_link_url. The two fields
will be shown on the resulting form page as: <ul> <li><a
href="return_link_url">return_link_title</a> </ul>
Syntax:
<input type=hidden
name="return_link_title" value="Back
to Main Page">
Field:
background
Description:
This form field allow you
to specify a background image that will appear
if you do not have the redirect field set.
This image will appear as the background to
the form results page.
Syntax:
<input type=hidden name="background" value="http://yourdomain.com/image.gif">
Field:
bgcolor
Description:
This form field allow you
to specify a bgcolor for the form results page
in much the way you specify a background image.
This field should not be set if the redirect
field is.
Syntax:
For a background color of
White:
<input type=hidden name="bgcolor" value="#FFFFFF">
Field:
text_color
Description:
This field works in the
same way as bgcolor, except that it will change
the color of your text.
Syntax:
For a text color of Black: <input
type=hidden name="text_color" value="#000000">
Field:
link_color
Description:
Changes the color of links
on the resulting page. Works in the same way
as text_color. Should not be defined if redirect
is.
Syntax:
For a link color of Red:
<input type=hidden name="link_color" value="#FF0000">
Field:
vlink_color
Description:
Changes the color of visited
links on the resulting page. Works exactly
the same as link_color. Should not be set if
redirect is. Syntax:
For a visited link color of
Blue:
<input type=hidden name="vlink_color" value="#0000FF">
Field:
alink_color
Description:
Changes the color of active
links on the resulting page. Works exactly
the same as link_color. Should not be set if
redirect is.
Syntax:
For a visited link color of Blue:
<input type=hidden name="alink_color" value="#0000FF">
Any other form fields that appear
in your script will be mailed back to you and displayed
on the resulting page if you do not have the redirect
field set.
|
