Extension:EmailForm

What can this extension do?
This extension is used to create email response forms.

Both the input form and the results, which are defined on the same wiki page, can be fully formatted using standard wikitext.

Usage
The same page is used for the email input form and the target/results.

The contents of the input form are specified between  and   tags. Even though it's an XML-style extension, EmailForm renders wikitext within the tags. This lets you specify arbitrary content for the form, including tables, links, and styles in addition to the form fields. Similarly, the result is between  and   tags.

Form fields are identified by attributes to the  tag, such as   and. The same attributes are used to display the fields in the result, though the attribute values are ignored.

Example
Create a formatted input form and result block like this:

The rendered page would look like this, with the tags visible as when EmailForm is not installed:

With EmailForm installed, the resulting page looks like this after styles are applied (input form at the top, results at the bottom):



The "Contact me" form at my own web site is here.

Attributes
This extension adds a single tag, , to Wikitext markup. Multiple copies of the tag are used in combination to define a form. The meaning of each tag is specified by its attributes.

Predefined attribute/field values
Syntax:   
 * form (optional): Acts as a container for controls. It can contain text and markup (paragraphs, lists, etc.) in addition to form controls. This attribue is optional, i.e.   is equivalent to.
 * report: Acts as a container for controls. It can contain text and markup (paragraphs, lists, etc.) in addition to form controls. Any   fields in the   section are replaced by the values passed in the POST command, and can be used to provide feedback to the user.

User-specified attribute/field values
Syntax:    Fields whose value starts with a number (like  ) are treated as text fields. All others are treated as hidden fields, which can be used to pass predefined text to the mailer.
 * inputname=cols: Creates a text field named inputname that is cols columns wide
 * textname=rowsxcolumns: Creates a multiline text field named textname that is rows rows high by cols columns wide. Multiline fields are distinguished from single line fields by the x
 * hiddenname=val: Creates a hidden field named hiddenname with the value val.
 * submit=button label: Creates a submit button to submit the form. The value of the attribute is used for the button label, i.e.   creates a button labelled Send this. Clicking the button sends the form.

Settings in MediaWiki::EmailForm
The special page, MediaWiki:EmailForm, has one line for each page with an email form on it. Each line specifies the settings for that page, separated by the '|' character. The format of each line is:


 * page name: Name of the page that the form is on, e.g.
 * send to email address: Email address used as a target for the form, e.g. To:
 * prefix for subject: Prefix for the start of the email's subject. The first 60 characters of the message contents are appended to create the Subject: field.

Example:

Installation
The extension is a single script which you can save into your extensions directory and include in your LocalSettings.php file.

Security
There are obvious concerns when adding email form support to an open wiki. To prevent users from using it for spam, this extension is intended to be activated only by system administrators (see: Help:Administration). The destination email address is stored in a separate page instead of with the form code to help discourage spam bots.
 * For security reasons, this extension is only active on protected pages, which means only system administrators can change the form(s).
 * The email settings (including the destination address) must be specified in a special page, MediaWiki:EmailForm, in the MediaWiki namespace, which means only system administrators can change it.

Implementation
When the submit button is pressed, the form is posted to the same page. When the main   field is parsed, the message parameters are extracted from the POST data using the PHP global,.

The extension uses the built-in PHP function to send the message through the sendmail binary on your server. This lowest-common-denominator function works on most systems and provides adequate functionality, at least on my host.

Tips, tricks, and hoops

 * Even though it's an XML-style extension, EmailForm renders wikitext within the tags. This lets you specify arbitrary content for the form and results, including tables, links, and styles in addition to the form fields.
 * The function  uses a cloned copy of the parser object to render the wikitext contents (see How do I render wikitext in my extension?).
 * The extension checks  to ensure it only works on protected pages. This means only system administrators can change the form contents.
 * The page with the email addresses and other settings is in the 'MediaWiki' namespace, which means only system administrators can change it.
 * The function  creates a new   to load the settings page and   to get its wikitext contents.
 * The extension won't work if MediaWiki uses cached versions of the page with the email form and results.
 * It uses  to disable the cache. (see How do I disable caching for pages using my extension?).
 * It tells MediaWiki to flush the cache before it starts parsing the result page by passing  with every request as hidden field with the name 'action' and the value 'purge'.
 * The same wiki page is used for the email form, the POST target, and the results display.
 * The code checks the PHP global variable  for a special parameter, , to distinguish between input and result modes.

Version history

 * 0.8: 1 August 2007, initial public release