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

See Also

  • BuildForms   Create an HTML form with Wiki markup, save values in a file, and pass values to a user defined function (obsolete)
  • CompareFormsRecipes   Comparison of various form recipes
  • EMailForm   Provide a web form that sends email to fixed email addresses
  • FormExtensions   adds fieldset, legend, and label tags to PmWiki forms
  • FormGuideSystem   Flexible, extensible, parameter-driven system to support the use of form pages
  • Forms   Form creating, configuring and processing
  • FormsPlus   Form extensions adding new HTML5 input types
  • FormValidation   How to validate forms within wiki pages
  • HtpasswdForm   Form based management of users and passwords using .htpasswd/.htgroup files
  • InputFormsAndJavaScript   Some ideas of combining Javascript with PmWiki Input forms
  • MailForm  
  • Mailform2   Set up a mail form so that visitors can send comments or suggestions to a limited list of recipients
  • Mailform3   A single wiki page mail form with feedback
  • Mailform4   Mailform4 alias Mailform2² - A contact form module with extensible form fields
  • MailListForm   Form for subscription to an email list
  • PmForm   Form processing engine for PmWiki
  • ProcessForm   Maintain values in fields and make PVs of the form name/values when a form is submitted
  • RecipeInfoForm   Form to change recipeinfo fields
  • UpdateForm   Easily create forms to display, add, and update records in a MySQL table.
  • UpForm   Allow use of a Site.UploadForm page to format the upload form
  • UploadForm   Alternative file upload form using (:input file:)

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.