Form-to-Mail Documentation

Form-To-Mail Documentation

Introduction

The Form-To-Mail package is designed to work somewhat like formmail.pl - the user enters information into an HTML form on a page, and upon submitting the page the data is collected and emailed to an address of the administrator's choosing.

Form-to-Mail (FTM) is designed with reuse, and hopefully some security, in mind. Email addresses such as sender and recipient are configured by the administrator, stored in the database, and cannnot be overridden by form variables, which limits abuse of the form by third parties.

FTM is designed to be included on other pages in the site, and provides a facility for adding custom form elements to the form, using a .tcl file that can be as simple or complex as the developer requires. The package uses a single instance to generate the included HTML form, and to process the submitted form.

Getting Started

Form-to-Mail is made up of two pages: form and form-proc. To add a mail form to your site, first mount an instance of Form-To-Mail under your site. The name of the instance doesn't really matter, but there should be only one instance and it would be good to name it something generic but that does not give away its purpose (i.e., naming it "Form-to-Mail" is likely to invite malcontents to try and abuse it). I like to use 'ftm'.

Visit /yoursite/<ftm-instance>/admin. (Replace <ftm-instance> with whatever you named your Form-to-Mail instance.

Fig 1: The Form-to-Mail Admin page

Add a new form, entering the information as requested:

Form Name: a descriptive name you can remember. You'll use it when adding the form to your pages.
Subject Prefix: a prefix, often of a form like "[name of form]", but can be whatever you want. The user will not see this, but it can help the recipient recognize and filter incoming mail from the form.
Subject Default: this will be the default subject, and will appear in the subject form field when the user creates a new form. The user can replace this with whatever they want.
Recipient: valid email address where the email from the form will be directed.
Sender: email address with at least a valid domain which will be used as the "from" address in the email.

Fig 2: Adding a form

Usage

On the page or template where you want the form to appear, include it like this:

<include src="/packages/form-to-mail/www/form" form_name="name of the form" extra_form_file="/path/to/file">

src: typical include src. Should always be "/packages/form-to-mail/www/form".
form_name: This is the descriptive name you gave the form when creating it. This tells the form-to-mail package which default values to pull fromt he database, and later, which sender and recipient to use.
extra_form_file: Optional, this is a .tcl file containing at least a call to ad_form -extend, as documented below.

Fig 3: Including the form

Extra_form_file

Form-to-Mail is designed to be extensible. The forms you create in the admin area can be used as is - subject and body (actually title and comments) fields will be generated for you. However, most developers will want to collect a variety of information from the form. FTM provides for this by taking a .tcl file as a parameter to the <include> tag and sourcing it when generating the form. Create a .tcl file in your site somewhere. I usually name it after the form I'm extending, i.e. form_name_extra_form.tcl. In the file, you need at least one call to ad_form, like this:

                ad_form -extend -name mail_form -form {
                    { ftmx.field1:text ... }
                    { ftmx.field2:text(select) ... }
                }

Fig 4: The extra_form_file

The form name, "mail_form", is the name of the form generated by the package and should not be changed.

In the call to ad_form, your form elements should be named with "ftmx." as a prefix. This adds the form element to an array passed to the form processor, and makes sure that it gets added to the outgoing email.

You can use whatever techniques you want to generate your form elements. One popular technique might be to fetch a list of values from the database to create the options for a select input (drop-down list element). Another might be grabbing the url of the current page to pass as a hidden field and thereby sent with the email.

Fig 5: The rendered form

Fig 6: After submitting

Fig 7: The email

I would be completly remiss if I did not thank the denizens of #openacs - especially daveb, jadeforrest, jim, jaufrec, michaels, talli, and til - for their help, encouragement, and patience with a complete n00b.
Form-to-Mail Package, Steve Ivy, steve@redmonk.net, 2003