Extension:EmailPage

MediaWiki extensions manual - list

EmailPage Release status: stable
Implementation	Special page
Description	Send rendered HTML page to an email address or list of addresses using phpmailer
Author(s)	User:Nad
Last version	2.1.3 (2010-11-23)
MediaWiki	1.11.0+
License	GPL
Download	Download snapshot Subversion [Help] Browse source code View code changes
Check usage (experimental)

Installation

Download the latest snapshot and extract it to your extensions directory. Then include it in your LocalSettings.php file as in the following example.

include("$IP/extensions/EmailPage/EmailPage.php");

The EmailPage on SVN also contains the phpmailer HTML emailing component PHPMailer_v5.1 (tested and working), but you may want to check phpmailer.sourceforge.net in case a later version is available.

Ensure that all the files you've downloaded and saved are accessible by the webserver.

Usage

The extension adds a special page called Special:EmailPage which requires a parameter of the page title you wish to send. It also adds links to the actions and toolbox using the link names specified in $wgEmailPageToolboxLink and $wgEmailPageActionLink. Either one can be set to "" (empty) to remove the link.

The specialpage form has two main sections, one for selecting the recipients of the emailed page, the other to specify the specifics of the subject line, prepended message and CSS stylesheet.

In case you would like to create a special user group to utilize the functionality provided by this extension, use the right 'emailpage' to assign it (see also this discussion).

Selecting recipients

There are three different ways of specifying recipients for the page to be sent to, which are described below. All three can be used together in composing an overall selection of recipients.

From group

All the available MediaWiki groups are listed in a drop-down list. If one of these is selected then all the members of that group which have an email address will be added to the recipient list.

• Note that by default the "user" group which represents all registered users doesn't show, for it to show you must set $wgEmailPageAllowAllUsers to true.

From contacts category

If a category name is specified in $wgEmailPageContactsCat then its sub-categories will be listed in a drop-down list in the email page form. each of these sub-categories should contain pages which each represent a single contact. The first email address out of each contact page will be added to the list of recipients. Please note that the name of the category should not contain spaces, e. g. “[[Category:New Zealand]]” is not ok but “[[Category:NewZealand]]” is ok.

Directly from a list

A textarea is supplied or adding additional recipients directly. These recipients can be entered directly as email addresses on each line, or separated by commas, semicolons or asterisks (bullet list). If an item is not an email address, it will be treated as a contact page title from which the first email address will be extracted. This textarea is treated as wikitext and will have templates expanded before extracting the email addresses which means that it can contain a DPL query which could result in a list of email addresses or contact pages.

Personalised emails

As of version 1.3.1, articles can contain named fields enclosed in braces which will be replaced with specific values for each recipient. The records it draws the data from are in the format used by other extensions such as Semantic Forms and RecordAdmin where each kind of record is a template for example Template:Member whos named triple-brace arguments define the fields of the record. To ensure that it's known to be treated as a record rather than any other template it should be categorised into Category:Records (using noinclude tags). Articles can then become records by transcluding a record template and giving it some specific parameters.

Example record

This example is for those who don't already have a system of maintaining records in wiki articles. First we'll define a new template article called Template:Person containing defining a name and an email address, and a simple layout table so that the record articles are easy to read (the layout in the template doesn't have anything to do with emailing though).

<table>
    <tr>
        <th>Name:</th>
        <td>{{{name}}}</td>
    </tr>
    <tr>
        <th>Email:</th>
        <td>{{{email}}}</td>
    </tr>
</table>
<noinclude>[[Category:Records]]</noinclude>

You can then create as many records as you like for example a new article called Maryjane may contain the following:

{{Person
 | name  = Maryjane
 | email = maryjane@smokyjoes.com
}}

Messages containing fields

Using our new records, we can send an article to the recipients with their proper name in the message, for example our article may contain the following wikitext content:

Dear {name|valued customer},
We'd like to remind you that some say our products can be up to
three times better quality than many other leading brands!

In the EmailPage form, select "Person" from the optional record drop-down box and send as normal. For each recipient, the extension will check if any record (article transcluding Template:Person) have the current email address in their parameters. If so, all the parameter values will be extracted from that article and used to replace the corresponding fields in the content being sent.

Default values can be supplied in case there is no record found, or the record doesn't contain some of the parameters. This is done using the pipe character as in the example above which replaces the name field with "valued customer" if the field can't be replaced. If there is no default, the brace enclosed name will be left unchanged in the content that gets sent.

Configuration settings

Here are some global variables which affect the operation of the extension. These should be set in your LocalSettings file after the include of the EmailPage.php script.

Variable	Default value	Meaning
$wgEmailPageGroup	sysop	Users must belong to this group to send emails (empty string means anyone can send)
$wgEmailPageCss	false	The name of a minimal CSS page to embed in the email (eg. monobook/main.css without portlets, actions etc).
$wgEmailPageAllowRemoteAddr	server-IP, 127.0.0.1	Trusted addresses for which anonymous sending is allowed. This allows local scripts and cron-jobs on the server to send email directly from and HTTP request.
$wgEmailPageAllowAllUsers	false	Whether to allow sending to all users (the "user" group)
$wgEmailPageToolboxLink	true	Add an email-page link to sidebar toolbox
$wgEmailPageActionLink	true	Add an email-page tab to the action links
$wgEmailPageSepPattern	[\\x00-\\x20,;*]+|	Regular expression for splitting emails

Example

Standard settings of version 2.1.3 (2010-11-23) included in ‚EmailPage.php‘

$wgEmailPageGroup           = "sysop";               # Users must belong to this group to send emails (empty string means anyone can send)
$wgEmailPageCss             = false;                 # A minimal CSS page to embed in the email (eg. monobook/main.css without portlets, actions etc)
$wgEmailPageAllowRemoteAddr = array( "127.0.0.1" );  # Allow anonymous sending from these addresses
$wgEmailPageAllowAllUsers   = false;                 # Whether to allow sending to all users (the "user" group)
$wgEmailPageToolboxLink     = true;                  # Add a link to the sidebar toolbox?
$wgEmailPageActionLink      = true;                  # Add a link to the actions links?
$wgEmailPageSepPattern      = "|[\\x00-\\x20,;*]+|"; # Regular expression for splitting emails

CSS Stylesheets

By default the CSS used is called EmailPage.css which is intended to be a cut down compact css based on the stylesheet for you wiki but with all the portlet, actions and other skin related styles removed.

The EmailPage form also has a dropdown list containing all the other CSS pages found in the wiki (all pages with titles ending in .css).

Multibyte Character Set

For most languages it is necessary to switch to a Multibyte Character Set (MBCS), e.g. UTF-8.

In order to do so you just have to change

public $CharSet = 'iso-8859-1';

to

public $CharSet = 'UTF-8';

in line 59 of ‘class.phpmailer.php’

This file is located in .../extensions/EmailPage/phpMailer_v5.1/class.phpmailer.php';

Todo & bugs

• Usage documentation !!
• Multibyte characters not rendering in emails properly
• Add toolbox link automatically
• ea_autherror message not working
• PLURAL's not working
• Title not showing in subject's default message anymore
• Should log sends to an MW log
• Allow setting FROM field, default to users email address

Change log

See SVN for change log.

Version 2.1.3 (2010-11-23)

Rename special page name from "EmailPage" to "E-MailPage" because the message key "emailpage" conflicts with the core message "emailpage" ('E-mail user')

Version 1.2.0 (2008-07-13)

Extension renamed from EmailArticle to EmailPage. All configurable settings have also been renamed. Update your LocalSettings.php on update!

Version 1.0.9 (2008-01-19)

Don't rely on REGEXP for SQL queries, not supported by some database types

Version 1.0.5 (2007-09-14)

Fixed warning messages in MW1.11

Version 1.0.4 (2007-08-27)

Needs $this->setHeaders() in execute()

Version 1.0.3 (2007-07-10)

Fixed blank page title in subject line, and fixed problem when using empty $wgEmailPageGroup

Version 1.0.1 (2007-06-08)

Added $wgEmailPageToolboxLink and $wgEmailPageActionLink globals for adding toolbox and action links

See also

• Extension:EmailToWiki - append, prepend or replace content in wiki pages by emailing title@wiki.domain
• Extension:FormMailer - Formats and sends posted forms to email recipients