Mailform2

Summary: Set up a mail form so that visitors can send comments or suggestions to a limited list of recipients
Version: 0.9 - 26 June 2005
Prerequisites:
Status:
Maintainer: JoachimDurchholz
Categories: Forms
Discussion: Mailform2-Talk?

WARNING: This recipe broke when PmWiki acquired the (:input...:) directive in version 2.0beta44. It works with the native form handling in newer versions of PmWiki, but you must make a small modification to mailform2.phpΔ and you must edit config.php (which you had to before as well).

Question

How do I set up a mail form so that visitors can send comments or suggestions to a limited list of recipients?

Answer

Software installation

Download mailform2.phpΔ into the cookbook/ directory and place the following line in your config.php:

   include_once('cookbook/mailform2.php'); 

mailform2.php will install a handler for ?action=mailform2 which will send a mail if given the right parameters.

Designing the mail form

In PmWiki 2.1.11 and up

This may work in any version since 2.0beta44 which has native form input, but I've only tested it in 2.1.11. You MUST modify one line in mailform2.php and edit your config.php -- see below.

The following is for a basic contact form which only sends mail to an address predefined in config.php (see below). It will generate a form with an input box for the subject and the message.

  (:input form "http://YOURDOMAIN.COM/PATH/TO/pmwiki.php?action=mailform2" post:)
  Subject: (:input text name="mail-subject" value="DEFAULT VALUE":)\\
  (:input textarea name="mail-text" rows=10 cols=65:)\\
  (:input submit value="Send Message":)
  (:input end:)

Want the subject to be hidden and unchangeable by the sender? Change the "text" to "hidden":

  (:input hidden name="mail-subject" value="SUBJECT TEXT":)

The old way

Mail forms are built using the markup defined by input.php. A typical mail form would look like this:

  (:input start "http://domain.tld/path/to/pmwiki.php?action=mailform2":)
  ...
  (:input line mail-recipients:)
  ...
  (:input line mail-subject:)
  ...
  (:input text mail-text rows=10 cols=65:)
  ...
  (:input button "Send the mail!":)
  ...
  (:inputend:)

Notes

  • The quotes around the script URL are mandatory. Without them, input.php would interpret it as a parameter named http://domain.tld/path/to/pmwiki.php?action with a value of mailform2, and carp about a missing script parameter.
  • If you applied the CleanUrls recipe and have a redirect rule installed, make sure that the ?action=mailform2 URL above goes to the "unclean" URL (the one that contains pmwiki.php). Otherwise, form input data will be dropped by Apache, and all you'll get is seemingly empty input fields.
  • Data from the input fields isn't automatically moved into the ?action=mailform2 script. You'll have to do that in config.php (see below; it's simple).

Using Mailform2 with newer versions of PmWiki

Since PmWiki 2.0.beta44, the (:input:) method of making forms has been a native part of PmWiki. You do not need to install the Input cookbook.

To use Mailform2 with these versions, simply comment out the line in mailform2.phpΔ which reads

  require_once('cookbook/input.php');

After you comment it out it should read

  // require_once('cookbook/input.php');

Controlling action=mailform2

The action handler expects the following variables, which must be set or filled from the form in config.php. See below for details on how to do this.

$Mailform2Recipient

The address to send the mail to.
No default value. If this isn't set, no mail will be sent and the visitor will be redirected to the $Mailform2FailurePage.

$Mailform2Sender

The Sender: header to attach to the message.
Note that this value is ignored except for installations on Windows.
Default value: An empty string.

$Mailform2Subject

The Subject: header to attach to the message.
Default value: An empty string.

$Mailform2Text

The contents of the mail message to send.
Default value: an empty string.

$Mailform2SuccessPage

The wiki page name to display (in Group.Name format) if sending was successful.
Default:
$Mailform2SuccessPage = 'Main.MailSentSuccessfully';

$Mailform2FailurePage

The wiki page name to display (in Group.Name format) if sending was not successful.
Potential failure reasons are things like empty subject and text, misconfigured mail software, unknown hosts, and similar. Depending on how the recipe was set up, some of these problems may be fixable by the visitor, and some may not (a broken mail configuration probably isn't, empty input fields are).
Whatever the reason, the page should tell the visitor that no mail was sent, explaining those reasons that the visitor might want to fix, and tell the visitor that he should otherwise send a mail to wikimaster@yoursite.com to have the problem corrected.
Default:
$Mailform2FailurePage = 'Main.MailSendFailure';

$Mailform2Disabled

Whether to accept mail requests at all. You'd want to set this to 1 (true) if both $Mailform2Subject and $Mailform2Text are empty, e.g. with this line in config.php:
$Mailform2Disabled = $Mailform2Subject == '' && $Mailform2Text == '';
If $Mailform2Disabled is set, the user will be redirected to $Mailform2FailurePage.

Defining the variables

These variables should be set up in config.php. Good ways to do that would be:

  • Initialise with a fixed string, as in
    $Mailform2Recipient = 'webmaster@host.tld';
This is useful for things that are nailed down for the entire site.
  • Initialise from a POST variable. This is how you get the data input by the user. For example, if the name of your message text field were 'mail-text', you would fill $Mailform2Text as follows:
    $Mailform2Text = $_POST['mail-text'];
If you happen to use the GET method (which you shouldn't), you'll find the data in $_GET[] instead of in $_POST[].
  • Initialise from a session variable, as in
    session_start();
    $Mailform2SuccessPage = $_SESSION['SuccessPage'];
    session_write_close();
This is useful if Mailform2 is being controlled from another script. The other script would set up the session variables, then redirect to ...pmwiki.php?action=mailform2.

Some non-obvious ways to use this

Restricting to specific pages or groups

If you want to prevent casual visitors from setting up an input form, you can write-protect a group and limit the recipe's scope like this:

  if ($Group == 'PmWiki') {
    include_once('cookbook/mailform2.php');
  }

You can also restrict to a single page, like this:

  if ($FullName == 'PmWiki.Feedback') {
    include_once('cookbook/mailform2.php');
  }

Notes

  • This recipe was last tested on PmWiki version: 2.0beta36
  • This recipe requires at least PmWiki version 2.0beta25, and Input V0.92.
  • Input won't work for PmWiki version 2.0beta44 or later; this means that Mailform2 won't work, too. If you have other means to generate HTML forms, you can make Mailform2 work by removing the require_once ('cookbook/mailform2.php'); line from input.php.

Clean URLs

This method of creating clean URLs -- http://www.pmichaud.com/wiki/Cookbook/CleanUrls#samedir -- breaks Mailform2. Most of the time, instead of sending mail, the user is just redirected to the site's home page without confirmation or error. -- Neurophyre, 7 Aug 2006

Since MailForm does nothing particularly sneaky, I suspect that this is a bug in the rewrite rules given in that sub-recipe, and that it would break every other recipe that processes form data.
JoachimDurchholz January 05, 2007, at 12:52 PM

See Also

Change and contribution history

DateContributorVer.Comments
2005-06-26Joachim Durchholz0.90First beta release.
2005-07-29Joachim Durchholz0.91Reworked the recipe so that it's simpler to use.

Comments

See discussion at Mailform2-Talk?

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.