MailListForm

Summary: Form for subscription to an email list

Version: 2008-08-28

Prerequisites: PmWiki 2.0 or greater

Status: working

Maintainer: Diafygi

Categories: Forms

Discussion: MailListForm-Talk

Question

How can users subscribe to a mailing list?

Answer

Add a form to the wiki for users to fill out and subscribe or unsubscribe.

Description

This is a heavily modified form of the EMailForm recipe. It will generate a form on the wiki page and allow users to submit

Requirements:

Your email list software accepts subscriptions via email
Sendmail access for php (ask your admin), allows php to send emails

Installation

download the latest emaillistform.php Δ to your /cookbook directory
add the following lines to your 'config.php' file in your local directory, customizing the variables as you need to:

           include_once('cookbook/emaillistform.php');
           $EMailListFormAddresses['foo'] = 'foo_list@foo.com';
           $EMailListFormAddressesUnSubscribe['foo'] = 'foo_list-unsub@foo.com'; #Optional
           $EMailListFormSubscribeText['foo'] = 'subscribe $EMailListFormName';
           $EMailListFormUnSubscribeText['foo'] = 'unsubscribe $EMailListFormName';
           $EMailListFormSubscribeSubject['foo'] = 'Sign Me Up!';
           $EMailListFormUnSubscribeSubject['foo'] = 'Take Me Off!';

add the following markup for the form to your wiki page:

           emaillistform:foo

This creates a form in the wiki page that will ask for a user's name, email, and whether they want to subscribe or unsubscribe. The recipe will send a message to the email list server according to the variables listed in the config file. For example, if Bob Smith (bobsmith@example.com) subscribed to the above form, it would send the following email:

           From: bobsmith@example.com
           To: foo_lists@foo.com
           Subject: Sign Me Up!
           Message: subscribe Bob Smith

Because variables are identified by their list, you can have many different subscription forms (i.e. foo1, foo2, foo3, etc.). This recipe can be used in addition to other recipes, such as EMail Form, without conflict.

Variables

$EMailListFormAddresses['foo']

The place you want the emails to be sent. Can be multiple emails, separated by commas.

$EMailListFormAddressesUnSubscribe['foo']

New Feature as of 2008-08-28! Backwards Compatible!

The place you want the emails to be sent for unsubscribe emails. This is an optional variable. If no variable is found, the recipe simply uses the subscribe email (i.e. $EMailListFormAddresses['foo']). Can be multiple emails, separated by commas.

$EMailListFormSubscribeText['foo']

What is sent in the body of the email for subscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

$EMailListFormUnSubscribeText['foo']

What is sent in the body of the email for unsubscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

$EMailListFormSubscribeSubject['foo']

What is sent in the subject of the email for subscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

$EMailListFormUnSubscribeSubject['foo']

What is sent in the subject of the email for unsubscriptions. Can contain $EMailListFormName and $EMailListFormFrom, which are the user's submitted name and email, respectively. Can also contain any other Variables or PageVariables.

Internationalizations

These variables can be used for multiple languages in a XLPage (XLPageLocal).

  'EMLFsuccess' => 'Message has been sent successfully.',
  'EMLFfailure' => 'Message could not be sent.',
  'EMLFerror' => 'An error has occurred.',
  'Your Name' => 'Your Name',
  'Your Email' => 'Your Email',
  'Subscribe' => 'Subscribe',
  'Unsubscribe' => 'Unsubscribe',
  'EnterName' => 'Please enter your name.',
  'EnterEMail' => 'Please enter your email address.',
  'EnterWhat' => 'Do you want to subscribe or unsubscribe?',
  'Submit' => 'Submit'

For German you can add the following to your XLPage:

  ### e-mail form
  'EMLFsuccess' => 'Die Nachricht wurde erfolgreich gesendet.',
  'EMLFfailure' => 'Die Nachricht konnte nicht verschickt werden.',
  'EMLFerror' => 'Ein Fehler ist aufgetreten.',
  'Your Name' => 'Ihr Name',
  'Your Email' => 'Ihre e-mail',
  'Subscribe' => 'Eintragen',
  'Unsubscribe' => 'Austragen',
  'EnterName' => 'Geben Sie bitte Ihren Namen ein.',
  'EnterEMail' => 'Geben Sie bitte eine e-mail Adresse ein.',
  'EnterWhat' => 'Wählen Sie bitte Eintragen oder Austragen!',
  'Submit' => 'Absenden',

Custom format

You can create your own custom format for the form by adding the $EMailListFormFmt variable in your 'config.php' file. This is an html variable, so you can't use markup. You must have the following names for inputs on the custom form:

                 emaillistform_address  (hidden, with a value of '$1')
                 action                 (hidden, with a value of 'emaillistform')
                 emaillistform_name     (text, user's name input)
                 emaillistform_sender   (text, user's email input)
                 emaillistform_subscribe
                        (can be radio, or hidden, with value's of 'subscribe' or 'unsubscribe')

POST the form to the same page (i.e. <form action='\$PageUrl' method='post'> )
You can also include $EMailListFormResult in the format to show results/errors.
$1 is the name of the form (i.e. 'foo')

What it looks like:

Notes

Restrictions: You can't create multiple emaillistforms on the same page.
Valid XHTML 1.0 Transitional
Released under GPL

Release Notes

2007-07-12 Released 0.1 -Diafygi
2007-07-15 Released 0.1.1 -added variable for RecipeCheck -Diafygi
2008-08-28 Released 0.2 - added unsubscribe email address variable (as requested by CarneiroTim) -Diafygi

Contributors

Diafygi

Comments

See discussion at MailListForm-Talk

User notes +1: 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.