Mailform Library

The Mailform Library simplifies the creation of email forms.

Mailforms are among the most common CGI applications, as evidenced by the number of Web Sites which make use of them. Mail Forms are extremely useful, whether their purpose is to reply to a message, submit comments about a Web Site, request information, or fill out an order form. Regardless of the application, the objective is to take whatever content has been entered by a User and forward it to a designated recipient via email.

Here are some of the advantages you can expect from the Tags in heitml's Mailform Library:

• Creating Forms is much simpler and a lot less work than using conventional HTML-Form and Table Tags explicitly.
• Text from an email Form can be formatted and enhanced before it is sent.
• If you wish, Users can be added to the cc list so that they receive a copy for their own records.
• Users can be given an opportunity to see how the email will look in final form (particularly if heitml has processed, formatted, or enhanced it in any way) and they can even go back and edit it, should they feel the need.
• If heitml detects an error in the Form data, the User is shown the form again, with the error marked for his attention. This is a friendlier, if not more efficient method than simply sending the User an error message (which (s)he may or may not find confusing).
• heitml can be used as a filter (e.g. to send the email to different people depending on topic, etc.).

Structure of a Mailform Application

A Mailform Application consists of a special heitml Form which specifies the type and appearance of data fields that need to be filled out by the User. These data fields are then used to create and format the final email.

A Mailform Application basically consists of two Environment Tags:

1. <mailform> - to specify the Mail Form
2. <mailtext> - to specify the main body of text.

Inside the Mailform, various Tags are allowed to display empty fields on the screen (e.g. <mailfield> and <mailtextarea>, as well as Tags to display, send, preview and edit, etc.).

For formatting purposes the <mailtable> Tag can be used. It creates a Table consisting of two elements in each row: a Field Name and the field itself (i.e. the place where the data is to be entered).

Here is a short example of a Mailform:

<mailform> How do you like heitml? // mailtable lines up fields nicely in a table <mailtable> <mailfield "FirstName" 20> <mailfield "Name" 20> <mailfield "Email" 20> <mailtextarea "Comment"> </mailtable> // buttons can be placed anywhere in the mailform // or simply omitted. < mailbutton> <mailbuttonpreview> <mailbuttonedit> </mailform>

Alternatively, a less-structured (i.e. more "free form") approach can be employed by using another Tag called <mailtext>. Inside the <mailtext> Tag you can write any text and include form fields simply by writing <? ff.formfieldname> in the appropriate place.

Here is an example to illustrate this concept:

// This is text which is prepared and sent to // the specified email address. // With <? ff.First> a form field can be // inserted anywhere in the text. <mailtext to="contact@radpage.com"> // This next Tag puts a header into the email // containing the date. <mailhead> H(e)i Heitml-Team, my name is <? ff.FirstName> <? ff.Name>. My answer on the question if I like heitml is: <? ff.Comment> You can reach me under <? ff.Email>. Best regards, <? ff.FirstName> </mailtext>

Table Format

Table Format acts like an abbreviation to create simple forms without a lot of unnecessary typing. Table Format creates a Table with two columns. The first column contains the field names, and the second column the field itself. For each field just one Tag needs to be specified. No HTML Table formatting Tags are required.

Table Format can be used within the whole form, or for just parts of it. If it is used for parts, the <mailtable> Tag must be used.

The formatting of the field label can be influenced by the addition of HTML formatting commands.

Compatibility with HTML

The Mail Form Library is powerful, but it can't do everything. It is simple to learn and can be easily used by beginners. Advanced Users can use it as a nice short-hand mechanism to increase efficiency in creating email forms.

If you want to use more HTML form features, use them in conjunction with the <mailform> Tags to create even more impressive email forms.

Tags to define the Form

< mailform table=false labelformat="" > ... </mailform>

Using the <mailform> Tag you define the form displayed on the screen. Inside the Mail Form, you can use the Tags described in this section to define what the User see.

The table and labelformat must be specified if you want to use Table Format for the entire Mail Form. In this case you must write table=true. Labelformat is a string of HTML Tags defining how the field labels should be printed. For example: labelformat="<b>" results in label names with bold type.

< mailfield name size=20 label=name maxlength=size />

Use <mailfield> to create a Form Field. The name must specify the Field Name. Usually a size must be stated. If it is not given, however, a default value of 20 is assumed.

Normally, just the data field itself is shown on the screen. In Table Format the label and the field are shown in two columns. Usually the label is simply the field name. However, a label can be given to specify the field label explicitly.

The maxlength parameter specifies the maximum size of the field content. It is usually bigger than size, in which case the field content is scrolled on screen.

< mailtextarea name label=name cols=40 rows=6 wrap="physical" />

This works very much like <mailfield> but creates a textarea (i.e. a multi-line input field. The cols and rows parameters specify the number of columns and rows for the field. The wrap parameter is rather specialized and is not usually needed. It has the same meaning as in HTML.

< mailButtonSend name="Send" />

Creates a "Send" button. If the button is pressed, then the email is sent.

< mailccUserCheckbox checked=false label="Send Copy" />

Creates a Checkbox. If the box is checked by the User, (s)he receives a copy of the email for reference purposes. The input form must have a field named email, where the User can enter his/her own email address.

With checked=true the box can be displayed initially checked. Using the label parameter, the label can be changed in Table Format. To enable this feature allowusercc=true must be specified in the <mailtext> Tag.

< mailButtonPreview name="Preview" />

Creates a "Preview" button. If the button is pressed, then the User is shown a preview of the email generated. The text cannot be modified, but the form is still shown and the User can modify the content of the fields and press send or preview again. To enable this feature allowedit=preview must be specified in the <mailtext> Tag.

< mailButtonEdit name="Edit" />

Creates an "Edit" button. If the button is pressed, then the User is shown an input box with the complete email generated. (S)he can modify the content of the box before really sending the email. To enable this feature allowedit=true must be specified in the <mailtext> Tag.

< mailTable > ... </mailTable>

The inner part of the <mailTable> Tag is shown in Table Format (i.e. it is shown as a two column Table. The left-hand side contains the field labels and the right-hand side the field itself.)

The <mailTable> Tag is very useful to quickly create nice email forms.

Tags to define the Email

< mailtext to subject cc="" rows=10 cols=60 allowusercc usersubject=subject allowpreview=false allowedit=false > ... </mailtext>

The inner part of the <mailtext> Environment Tag contains the text to be sent when the User presses the send button. Naturally, the text should contain the form fields entered by the User. A field can be included by writing <? ff.name>, where name is the Field Name. There are several formatting possibilities (e.g. to simply include all fields). These are handled by the Tags described in this section.

The to parameter of the <mailtext> Tag must specify the email address where the email should be sent. subject specifies the subject of the email, and cc specifies another email address where a copy should be sent.

The additional parameters are used for the advanced features: With allowusercc=true you can activate the UserCheckbox, where a User can request a copy of the email (see the <mailccUserCheckbox> Tag). With usersubject a different subject can be defined for the email that is sent to the user.

With allowpreview=true the preview button can be activated, (see the <mailButtonPreview> Tag). With allowedit=true the edit button can be activated, (see the <mailButtonEdit> Tag). In this case the rows and cols parameter specify the size of the edit box to be displayed.

< mailhead />

Inserts a heading line into the email, containing date, time and the name of the Mail Form.

< mailfields />

Inserts a Table of all Form Fields into the email.

< mailIntoUserMail > ... </mailIntoUserMail>

The text will be included into the email copy for the user, but not into the main email.

< mailIntoFeedbackMail > ... </mailIntoFeedbackMail>

The text will be included into the main email, but not into the copy for the user.

Additional Tags

< mailRequire name label=name />

This Tag must be used in front of the <mailform> and the <mailtext> Tags. The name parameter must be the name of a Form Field. <mailrequire> checks if the User has entered the field. If not, no email is sent, but an error message is displayed. The label is used as a field label within the error message. Here is an example:

// Specify which fields have to be filled out < mailrequire "Email" > <mailrequire "Name">

< mailError />

Use this Tag if you create your own test routines for User input. Call this Tag if one of your routines has detected an error. A subsequent Mail Form will re-display, and a subsequent <mailtext> will not send the email.

< mailSent > ... </mailSent>

The inner part of this Environment is displayed after the email has been sent.

Example:

// The following text is shown to the User // after the email has been sent. < mailsent > Thank you very much for entering your comment. < /mailsent>