Jump to content

Extension:EmailPage

From mediawiki.org
MediaWiki extensions manual
EmailPage
Release status: stable
Implementation Special page , Notify
Description Allows to send rendered HTML pages to an email address or list of addresses
Author(s)
Latest version 3.0.0 (2023-06-29)
Compatibility policy For every MediaWiki release that is a Long Term Support release there is a corresponding branch in the extension.
MediaWiki 1.39.x
PHP 8.0.x
Database changes No
License GNU General Public License 2.0 or later
Download

GitHub:

Note:
No localisation updates are
provided by translatewiki.net .

Parameters

  • $wgEmailPageGroup
  • $wgEmailPageCss
  • $wgEmailPageAllowRemoteAddr
  • $wgEmailPageAllowAllUsers
  • $wgEmailPageToolboxLink
  • $wgEmailPageActionLink
  • $wgEmailPageSepPattern
  • $wgEmailPageNoLinks
  • $wgEmailPageCharSet
Hooks used

The EmailPage extension allows to send rendered HTML page to an email address or list of addresses using PHPMailer (6.1+).

Installation

[edit]
  • Download, extract and place the file(s) in a directory called EmailPage in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php file: 
    wfLoadExtension( 'EmailPage' );
  • Run composer install in the extension directory to download PHPMailer
  • Configure as required.
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Usage

[edit]

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 can be set to false to remove the respective link.

The special page form has two main sections: one for selecting the recipients of the emailed page and the other for specifying 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 correct 'emailpage' to assign it (see also this discussion).

Selecting recipients

[edit]

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

From group

A drop-down list lists all the available MediaWiki groups. If one is selected, all the group members with an email address will be added to the recipient list.

Note that by default, the "user" group, which represents all registered users, does not show; for it to show, you must set$wgEmailPageAllowAllUsers to true.

Directly from a list

A text area is supplied to add 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 text area is treated as wikitext and will have templates expanded before extracting the email addresses. It can contain a DPL query, which could result in a list of email addresses or contact pages.

Personalised emails

[edit]

Pages 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 Page Forms 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 categorized into Category:Records (using "noinclude" tags). Articles can then become records by transcluding a record template and giving it specific parameters.

Example record

[edit]

This example is for those who don't already have a system of maintaining records in wiki articles. First, we will define a new template article called "Template:Person", 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 page called "Jane Doe" may contain the following: 

{{Person
 |Name=Jane Doe
 |Email=jane.doe@example.org
}}

Messages containing fields

[edit]

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

Dear {name|valued customer},
We want 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") has 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 sent content.

Default values can be supplied if no record is found or the record doesn't contain some 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 sent content.

Configuration

[edit]

Here are the parameters that affect the extension's operation. After invoking the extension, you should set these in your "LocalSettings.php" file.

Parameter Default value Meaning
$wgEmailPageGroup 'sysop' Defines the user group that is allowed to send emails. An empty string means that anyone can send
$wgEmailPageCss false Defines whether or not a minimal CSS page should be embedded in the email, e.g., \"monobook/main.css\" without portlets, actions, etc.
$wgEmailPageAllowRemoteAddr [ '127.0.0.1' ] Defines that anonymous sending from these addresses is done
$wgEmailPageAllowAllUsers false Defines whether or not to allow sending to all users, i.e., the "user" group
$wgEmailPageToolboxLink true Defines whether or not a link should be shown in the sidebar toolbox
$wgEmailPageActionLink true Defines whether or not a link should be shown as an action link
$wgEmailPageSepPattern '|[\r\n ,;*]+|' Defines the regular expression for splitting emails
$wgEmailPageNoLinks false Defines whether or not to change links in the message to spans if set
$wgEmailPageCharSet 'utf-8' Defines the character set for the message. Either "us-ascii", "iso-8859-1" or "utf-8"

Customization

[edit]
CSS Stylesheets

By default, the CSS used is called "MediaWiki:EmailPage.css", intended to be a cut-down compact CSS based on the stylesheet for your 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).

Issues with PHPMailer

[edit]

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

This can be achieved by setting the global variable $wgEmailPageCharSet on your "LocalSettings.php" file to the desired character set.

PHPMailer supports "us-ascii", "iso-8859-1", and "utf-8" with the latter being the extension's default.

See also

[edit]
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:EmailPage&oldid=6758974"