MailForm Page and #insertMailForm Macro

The MailForm page allow you to create any number of template-based HTML "Contact forms" in your site. When the form is submitted, the results are emailed to any address you've specified.

The #insertMailForm macro simply allows you to place the contact form somewhere else in your site (somewhere other than the contact form itself). In this case, the form still uses an existing mailform page to handle the form posts. So, you can't use the macro without having a "mailform page" somewhere on your site.

Security Considerations

"Mail form page," as they are generally known, have long been considered an "open security hole." In the old days (before Conversant) these pages would send the email to an address specified in the form. Spammers (members of the genus "bad people") would write scripts to send their commercial email messages to millions of people by submitting the form automatically, with different addresses each time.

This is not a problem in Conversant's mail form page. When you first create and configure the page, you must specify the addresses to which it is allowed to send email. Typically, this will be just a single address. It's also possible to support more than one email address in a single MailForm page, without any loss of security. See Working with Groups, below.

Creating a MailForm page

To create a MailForm page, go to "Files & Folders" section of your conversation's admin interface. If the plugin is active, "MailForm Page" will appear as an option in the popup for page types in the "Add new file" form. Give the page a name, select the "MailForm Page" type, and click "Add file".

Configuring Your MailForm Page

In the Files & Folders area, click on the MailForm page you have created, then click on the "Options" tab. This is where you configure the MailForm Page's properties. You must enter an email addresses (or a group id) before the page will function! Here you can set the email address the posts will be sent to, the address they will be sent from, and the subject line. You can also configure templates for the HTML form, the result page to be shown to the user, and the email message itself.

The "Form Template" can contain any standard HTML input tags, but should not contain the actual form tags, these will be added by the page.

The "Result Template" defines the message to be given to the user on a successful post. Any named input in the Form Template becomes a Conversant macro in the result template, so if you have an text input tag named "name" in the Form Template, you can include a <--#name--> macro in the result template to echo the input to the user.

The "Email Template" works just like the result template, macros exist for all named inputs in the Form Template -- but this template is used to build the plain text email message sent.

Using the #insertMailForm macro

The #insertMailForm macro allows you to insert the HTML form defined by a MailForm page anywhere in a conversation. The only attribute is required, "actionPath" which should point to an existing mailform page which the form will post to.

Syntax: <--#insertMailForm actionPath="path/to/mailform"-->

Working with Groups

You can use a single MailForm Page as a contact form for more than one person. The email will still be sent to just one person, but that person can be chosen from a popup menu or by some other means you specify.

You'll do this by leaving the "email" field blank in the page's properties, specifying the name of a group with the "Group ID" popup menu, and adding some way for the user to specify an email address in the HTML form (such as a popup menu that lists the people to whom email can be sent).

1. Go to the options tab in the page's properties (as described above, under Configuring Your MailForm Page)
2. Leave the "Email form to" field blank
3. Set the Group ID field to the name of a group in your zone. Note that this restricts the page sending email only to a person listed in this group!
4. Add a field named "emailto" to the Form Template. The simplest is to add a new row to the Form Template, like this:

       <tr>
           <td valign="top">To:</td>
           <td valign="top">
               <select name="emailto" />
                   <option value="[email protected]">Sales</option>
                   <option value="[email protected]">Tech Support<option>
                   <option value="[email protected]">The Boss</option>
                   </select>
               </td>
           </tr>