Online Tutorials

Please note this area is always being updated. If you have a question that is not answered here, please contact us or submit a support request, and if it's something that will benefit other users we will post it here.

How to use the Standard Mail Form Handler

Introduction

The standard mail form handler (SMF) lets you setup forms on your website to collect information from your visitors and then have it sent to you by e-mail. For example, a form on a contact us page to collect enquiries. The SMF requires knowledge of HTML to use.

Quick Use Guide

Step 1

Create a form that POSTS to http://www.perthweb.com.au/smf/smf.php

<form method="post" action="http://www.perthweb.com.au/smf/smf.php">
</form>

 

Top of Page.

Step 2

If you want javascript validation (recommended), link http://www.perthweb.com.au/smf/smf.js in header of your page and add the attribute value onSubmit="javascript: pwValidate(this);" to your form. Javascript validation means that the form information will be checked before it gets sent to the SMF handler (i.e. before the user submits the form).

<head>
<script src="http://www.perthweb.com.au/smf/smf.js" type="text/javascript"></script>
...
</head>

<body>
...
<form method="post" action="http://www.perthweb.com.au/smf/smf.php" onSubmit="javascript: return pwValidate(this);" >
</form>
...
</body>

Top of Page.

Step 3

Add fields to your form using the data elements name syntax (see below). Fields need to follow the correct syntax to ensure they are validated correctly.

<head> <script src="http://www.perthweb.com.au/smf/smf.js" type="text/javascript"></script> ... </head>

<body>
...
<form method="post" action="http://www.perthweb.com.au/smf/smf.php" onSubmit="javascript: return pwValidate(this);">

<div>
<label for="pwmsFirst_Name">First Name</label> *<br />
<input type="text" name="pwmsFirst_Name" id="pwmsFirst_Name" value="" />
</div>

<div>
  <label for="pwmsLast_Name">Last Name</label> *<br />
<input type="text" name="pwmsLast_Name" id="pwmsLast_Name" value="" />
</div>

<div>
<label for="pwmeEmail_Address">E-mail Address</label> *<br />
<input type="text" name="pwmeEmail_Address" id="pwmsEmail_Address" value="" />
</div>

<div>
<label for="pwmsMessage">Message</label> *<br />
<textarea name="pwmsMessage" id="pwmsMessage"></textarea>
</div>

<div>
<input type="submit" name="submit" id="submit" value="Submit"> <input type="reset" name="reset" id="reset" value="Reset">
</div>

</form>

</body>

 

Step 4

Configure the SMF using hidden fields and the reserved element names (see below).

<head><script src="http://www.perthweb.com.au/smf/smf.js" type="text/javascript"></script>... </head>

<body>

...

<form method="post" action="http://www.perthweb.com.au/smf/smf.php" onSubmit="javascript: return pwValidate(this);">

<div>

<label for="pwmsFirst_Name">First Name</label> *<br />
<input type="text" name="pwmsFirst_Name" id="pwmsFirst_Name" value="" />
</div>

<div>
<label for="pwmsLast_Name">Last Name</label> *<br />
<input type="text" name="pwmsLast_Name" id="pwmsLast_Name" value="" />
</div>

<div>
<label for="pwmeEmail_Address">E-mail Address</label> *<br />
<input type="text" name="pwmeEmail_Address" id="pwmsEmail_Address" value="" />
</div>

<div>
<label for="pwmsMessage">Message</label> *<br />
<textarea name="pwmsMessage" id="pwmsMessage"></textarea>
</div>

<input type="hidden" name=" pwSender0" value="pwmeEmail_Address" />
<input type="hidden" name=" pwSubject0" value="Enquiry Posted by pwmsFirst_Name pwmsLast_Name to the SMF Simple Contact Form Example" />
<input type="hidden" name="pwHeaderText0" value="Dear Recipient,\n\nThis is the information that what was submitted:\n\n" />
<input type="hidden" name="pwFooterText0" value="\nMessage End." />
<input type="hidden" name="pwRecipients" value="address@mail.com.au" />

<div><input type="submit" name="submit" id="submit" value="Submit"> <input type="reset" name="reset" id="reset" value="Reset"> </div>
</form>

</body>

Notice the use of element names in the values. These are tokens (see below). The use of "\n" equates to a new line.

Step 5

Create a success and failure page for the SMF to pass through to, then continue to configure the smf (see below).

<head> <script src="http://www.perthweb.com.au/smf/smf.js" type="text/javascript"></script> ... </head>

<body>
...
<form method="post" action="http://www.perthweb.com.au/smf/smf.php" onSubmit="javascript: return pwValidate(this);">

<div>
<label for="pwmsFirst_Name">First Name</label> *<br />
<input type="text" name="pwmsFirst_Name" id="pwmsFirst_Name" value="" />
</div>

<div>
<label for="pwmsLast_Name">Last Name</label> *<br />
<input type="text" name="pwmsLast_Name" id="pwmsLast_Name" value="" />
</div>

<div>
<label for="pwmeEmail_Address">E-mail Address</label> *<br />
<input type="text" name="pwmeEmail_Address" id="pwmsEmail_Address" value="" />
</div>

<div>
<label for="pwmsMessage">Message</label> *<br />
<textarea name="pwmsMessage" id="pwmsMessage"></textarea>
</div>

<input type="hidden" name="pwSender0" value="pwmeEmail_Address" />
<input type="hidden" name="pwSubject0" value="Enquiry Posted by pwmsFirst_Name pwmsLast_Name to the SMF Simple Contact Form Example" />
<input type="hidden" name="pwHeaderText0" value="Dear Recipient,\n\nThis is the information that what was submitted:\n\n" />
<input type="hidden" name="pwFooterText0" value="\nMessage End." />
<input type="hidden" name="pwRecipients" value="address@mail.com.au" />
<input type="hidden" name="pwSuccessPage" value="http:// FULL /url/to/success.html" />
<input type="hidden" name="pwFailurePage" value="http:// FULL /url/to/failure.html" />
<input type="hidden" name="pwQSPassthrough" value="1" /> <div> <input type="submit" name="submit" id="submit" value="Submit">
<input type="reset" name="reset" id="reset" value="Reset">
</div>

</form>
...
</body>

If you know a little PHP you can offer more sophisticated failure messages (if the user enters invalid information). To do this, make sure the pwQSPassthrough field is set to value "1". Then name your success and failure pages with the .php extension (instead of .html) and include the following code in your page: <?php echo $_GET['msg']; ?>. That code will then get replaced with a detailed report of invalid information for the user to correct.

Make sure you include a back link in your failure page so the user can go back and correct any information they filled out incorrectly the first time.

Step 6

That's it, all done! View the source of the commented Complex Form example in your browser for a complete example with commented HTML.

Appendices

Data Elements Name Syntax

char 1 char 2 char 3 char 4 meaning
p w     Indicated the SMF will handle this field.
    m   Mandatory field, the form element must contain a value.
    o   Optional field, the form element may be blank.
      s String (alphanumerics and punctuation).
      a Alphabet (a-z) characters ONLY.
      n Numerics ONLY.
      e E-mail address. (in the format name@address.com)
      w Website URL.
      d Date (in the format dd/mm/yyyy).

The rest of the data element's name is used to describe the content.

Examples

A person's first name that MUST be filled in and is a STRING (which might contain punctuation for names such as O'Brien). A suitable field name for this would be: pwmsFirst_Name - PerthWeb Mandatory field String : First_Name

Note the underscore (_). It will get replaced by a space in the mail output.

Another example, a telephone number (just say numbers only for this case's sake even though a string is probably more suitable to handle any symbols for international codes and extensions). We'll say it's optional too, so the visitor doesn't HAVE to give us this info: pwonTelephone_Number - PerthWeb Optional field Number : Telephone_Number.

The form names are the most important aspect of using the SMF. If they're setup correctly it'll handle validation and type-of-data checking for you (as well as any potential security attacks your form could be used for).

Special Element Names

There are reserved form element names that can be used to configure the SMF. These should all be hidden <input>s.

element name meaning
pwSender(0..n) an e-mail sender
pwSubject(0..n) an e-mail subject
pwHeaderText(0..n) an e-mail header (prefixes the form data i.e. main mail msg body)
pwFooterText(0..n) an e-mail footer (suffixes the form data i.e. main mail msg body)
pwRecipients CSV list of recipients (Note: NO spaces)
pwSuccessPage relative (from the smf.php) page to go to on success
pwFailurePage relative (from the smf.php) page to go to on failure
pwQSPassthrough whether to pass through an <ul> of errors to the failure page in the querystring (can be fetched from the failure page as $_GET['msg'])

Where the notation '(0..n)' is used means you can specifiy more than one of them using a number suffix to denote the recipient it applies to. So the indexes 0..n must match the order of the CSV recipents specified in pwRecipients. If anything goes wrong it defaults to 0 everytime.

Tokens

All form element/field names can be used as tokens in their values. This can be really useful when sending to multiple recipients (say the admin and a confirmation to the user). It's a tricky concept but let's take a look at an example,

Example

<input type="text" name=" pwmeEmail_Address " value="" />
<input type="hidden" name="pwSender0" value=" pwmeEmail_Address " />

So here, the visitor would fill out their email address in the mandatory form element/field, and the mail that gets sent (say to the admin of the site) would appear to be sent FROM that same e-mail address (because pwmeEmail_Address is included in the value of pwSender0). This means the admin can then simply hit the reply to button to the mail.

Special Built-In Tokens

token name replaces with
pwInsertDate Inserts the current date in the format d/m/y. Use it in the value of an element/field.
pwInsertTime Inserts the current time in the format hh:mm (24 hour clock). Use it in the value of an element/field.

Complete Examples