CZ:Newsletter/docs

Newsletter is an extension that supports the automatic generation and sending of newsletters. These newsletters typically contain news (surprise!) and statistics about the wiki.

Installation

Download the latest snapshot and extract it to your extensions directory. Then add the following to the bottom of LocalSettings.php:

require_once("$IP/extensions/Newsletter/Newsletter.setup.php");
$wgNewsletterSalt = "salt";

Replace "salt" by something random and unguessable, e.g. the output of a random password generator.

Next, you need to apply the changes to the database schema Newsletter requires by running update.php . See the upgrade manual for detailed information on how to run update.php .

Finally, go to your wiki's Special:Version to verify the installation.

Permissions

You probably don't want to allow every user to view and edit the list of subscribed users, or send mass e-mails to all subscribed users (or even all users). To control who can and who can't do these things, two approaches can be used:

Using existing groups

Add any of the following lines to LocalSettings.php to allow existing groups of users to send mass e-mails:

$wgGroupPermissions['*']['newslettermassmailer'] = true; // Allow *everyone*, including anonymous users, to send mass e-mails. You really don't want this
$wgGroupPermissions['user']['newslettermassmailer'] = true; // Only logged-in users can send mass e-mails. Probably not very wise either
$wgGroupPermissions['autoconfirmed']['newslettermassmailer'] = true; // Only users older than $wgAutoConfirmAge can send mass e-mails
$wgGroupPermissions['sysop']['newslettermassmailer'] = true; // Only sysops can send mass e-mails. This is the recommended setup
$wgGroupPermissions['bureaucrat']['newslettermassmailer'] = true; // Only bureaucrats can send mass e-mails

If you have created any custom groups in LocalSettings.php, you can allow these groups to send mass e-mails by adding

$wgGroupPermissions['groupname']['newslettermassmailer'] = true;

to LocalSettings.php (replace 'groupname' with the name of your custom group).

NOTE: If a user is in multiple groups, they will be able to even if that's allowed for only one of those groups. E.g.: if group A can't use ChangeAuthor but group B can, a user in both group A and B will be allowed to use ChangeAuthor.

To allow groups of users to view and edit the list of subscribed users, replace newslettermassmailer by newslettermembers in the example above.

Creating a new group

You can also create a separate group for users who can view and edit the list of subscribed users and send mass e-mail. To do this, add the following lines to LocalSettings.php:

$wgGroupPermissions['newsletter']['newslettermembers'] = true;
$wgGroupPermissions['newsletter']['newslettermassmailer'] = true;

This creates a new group named 'newsletter'. Only users in that group can view and edit the list of subscribed users and send mass e-mail. You can add users to the newsletter group using the Special:Userrights special page.

In this example we assigned the two rights to one group; of course you can also create a separate group for each right.

Subscribing and unsubscribing yourself

You can subscribe and unsubscribe yourself by going to the Special:NewsletterSubscribe special page. If you didn't provide an e-mail address when you registered or didn't confirm it, you won't be able to subscribe. In that case, you will be told to confirm your e-mail address first.

Managing newsletter subscriptions

Using the Special:NewsletterMembers special page, you can view a list of subscribed users and forcibly subscribe and unsubscribe users. To subscribe a user, enter their name in the first textbox from the top and click Subscribe. To unsubscribe a user, enter their name in the second textbox from the top and click Unsubscribe, or find them in the list and click the (unsubscribe) link next to their name.

Sending mass e-mails

Using the Special:NewsletterMassMailer special page, you can send mass e-mails to all subscribed users or to all users with a confirmed e-mail address. Mass e-mails can contain one-click subscribe links, which will automatically subscribe the recipient to the newsletter when they click the link.

Generating and sending the newsletter

You can generate and send the newsletter by running php extensions/Newsletter/sendNewsletter.php on the command line. Run php extensions/Newsletter/sendNewsletter.php --help to get a list of options you can use. You'll probably want to run this command as a cron job.

Customizing the Newsletter extension

Configuration variables

The Newsletter extension has two configuration variables, whose default values are set in Newsletter.setup.php . You can customize them by setting them in LocalSettings.php , below the require_once() line mentioned here.

# The salt used to generate one-click subscribe links
# Set it to something random and unguessable,
# and don't change it shortly after sending mass e-mails
# with one-click subscribe links in them.
$wgNewsletterSalt = "salt";

# By default, creations of newsletter archive pages will
# be marked with the bot flag, hiding them from Special:Recentchanges.
# Set this variable to false to disable this
$wgNewsletterArchiveAsBot = false;

Messages

Most customization in Newsletter happens by editing interface messages. Only sysops can edit interface messages, by going to MediaWiki:name-of-message .

Configuration messages

The following messages are used for configuration.

newsletter-queryclasses

Description

The list of statistics to use. You can add, remove and rearrange statistics here. The pre-defined statistics are:

NewsletterQueryStatistics: Basic site statistics like number of pages, etc.
NewsletterQueryMostEdited: Top 20 most edited pages since the last newsletter
NewsletterQueryMostActive: Top 20 most active users since the last newsletter
NewsletterQueryMostEditedNew</code: Top 20 most edited pages created after the last newsletter


NewsletterQueryMostExpandedOld: Top 20 most expanded (i.e. increased in size) pages whose existence predates the last newsletter

Default content

NewsletterQueryStatistics
NewsletterQueryMostEdited
NewsletterQueryMostActive
NewsletterQueryMostEditedNew
NewsletterQueryMostExpandedOld

newsletter-archiveDescription

The name of the wiki page the newsletter should be saved (archived) to

Parameters$1 is replaced by the time the newsletter was builtDefault content

Project:Newsletter/{{#time:Y/m|$1}}<!--
NOTE: YOU CANNOT USE PAGE-SPECIFIC MAGIC WORDS LIKE {{PAGENAME}} IN THIS MESSAGE -->

newsletter-archive-summaryDescription

The edit summary to use when archiving the newsletter

Parameters$1 is replaced by the time the newsletter was builtDefault content

Archiving {{#time:F Y|$1}} newsletter

newsletter-archive-userDescription

The user name to attribute the archiving edit to. This user doesn't have to exist, and doesn't get any special privileges.

Default content

Newsletter

newsletter-plaintextDescription

What to show if the recipient's e-mail client doesn't support HTML

Parameters

$1 is replaced by the time the newsletter was built
$2 is replaced by the URL of the archived version of the newsletter

Default content

This is the {{SITENAME}} newsletter for {{#time:F Y|$1}}.

Unfortunately, your e-mail client can't display HTML e-mails. To view the newsletter, go to <$2>.

newsletter-subjectDescription

The subject of the newsletter e-mail

Parameters$1 is replaced by the time the newsletter was builtDefault content

{{SITENAME}} newsletter {{#time:F Y|$1}}

Boilerplates

Boilerplates are messages that are used to build (parts of) the newsletter.

newsletter-boilerplateDescription

The main boilerplate for the newsletter. The result of processing this boilerplate is the newsletter wikitext.

Parameters

$1 is replaced by the statistics (see also other boilerplates)
$2 is replaced by the time the newsletter was built
$3 is replaced by the name of the page

Default content

__NOEDITSECTION__
If your e-mail client doesn't render this message properly, you can read it on-wiki at {{fullurl:$3}}.

=== News ==
{{Project:Newsletter/news/{{#time:F|$2}}}}

__TOC__

== {{SITENAME}} by the numbers ==
$1

== Subscribe or unsubscribe ==
To subscribe to or unsubscribe from this newsletter, go [[Special:NewsletterSubscribe|here]]. You will need to [[Special:Createaccount|create an account]] if you don't have one.

newsletterquerystatistics-boilerplateDescription

The boilerplate for the general statistics table (number of pages, etc.)

Parameters

$1 is replaced by the number of page views at the time the last newsletter was built
$2 is replaced by the number of edits
$3 is replaced by the number of articles (i.e. pages in the main namespace that aren't redirects and contain [[)
$4 is replaced by the number of pages
$5 is replaced by the number of users
$6 is replaced by the number of sysops
$7 is replaced by the number of images
$8 is replaced by the time the last newsletter was built
$9 is replaced by the number of page views at the time thisnewsletter was built
...
$16 is replaced by the time this newsletter was built

Default content

=== General statistics ===
{|
! Statistic !! {{#time:F n, Y|$8}} !! {{#time:F n, Y| $16}} !! Increase
|-
| Page views || $1 || $9 || {{#expr:$9-$1}}
|-
| Edits || $2 || $10 || {{#expr:$10-$2}}
|-
| Articles || $3 || $11 || {{#expr:$11-$3}}
|-
| Pages || $4 || $12 || {{#expr:$12-$4}}
|-
| Users || $5 || $13 || {{#expr:$13-$5}}
|-
| Administrators || $6 || $14 || {{#expr:$14-$6}}
|-
| Images || $7 || $15 || {{#expr:$15-$7}}
|}

newsletterquerymostedited-boilerplateDescription

The boilerplate for the most edited pages statistic

Parameters$1 is replaced by the table rows representing pagesDefault content

=== 20 most edited pages in the last month ===
<pre>
{|
! Rank !! Page !! Edits
$1
|}

newsletterquerymostedited-rowDescription

The boilerplate for creating a single row in the most edited pages table

Parameters

$1 is replaced by the 'rank' of the page (a number between 1 and 20) or by nothing in the event of a tie
$2 is replaced by the title of the page
$3 is replaced by the number of edits to the page

Default content

|-
| $1 || [[:$2]] || $3

newsletterquerymostactive-boilerplateDescription

The boilerplate for the most active users statistic

Parameters$1 is replaced by the table rows representing usersDefault content

=== 20 most active users in the last month ===
<pre>
{|
! Rank !! User !! Edits
$1
|}

newsletterquerymostactive-rowDescription

The boilerplate for creating a single row in the most active users table

Parameters

$1 is replaced by the 'rank' of the user (a number between 1 and 20) or by nothing in the event of a tie
$2 is replaced by the name of the user
$3 is replaced by the name of the user's user page
$4 is replaced by the number of edits by the user

Default content

|-
| $1 || [[$3|$2]] || $4

newsletterquerymosteditednew-boilerplateDescription

The boilerplate for the most edited new pages statistic

Parameters$1 is replaced by the table rows representing pagesDefault content

=== 20 most edited new pages in the last month ===
<pre>
{|
! Rank !! Page !! Edits
$1
|}

newsletterquerymosteditednew-rowDescription

The boilerplate for creating a single row in the most edited new pages table

Parameters

$1 is replaced by the 'rank' of the page (a number between 1 and 20) or by nothing in the event of a tie
$2 is replaced by the title of the page
$3 is replaced by the number of edits to the page

Default content

|-
| $1 || [[:$2]] || $3

newsletterquerymostexpandedold-boilerplateDescription

The boilerplate for the most expanded older pages statistic

Parameters

$1 is replaced by the table rows representing pages
$2 is replaced by the time the last newsletter was built
$3 is replaced by the time this newsletter was built

Default content

=== 20 most expanded older pages in the last month ===
<pre>
{|
! Rank !! Page !! Size at {{#time:F n, Y|$2}} !! Size at {{#time:F n, Y|$3}} !! Increase
$1
|}

newsletterquerymostexpandedold-rowDescription

The boilerplate for creating a single row in the most expanded older pages table

Parameters

$1 is replaced by the 'rank' of the page (a number between 1 and 20) or by nothing in the event of a tie
$2 is replaced by the title of the page
$3 is replaced by the size of the page at the time of the last newsletter
$4 is replaced by the current size of the page
$5 is replaced by the difference between $3 and $4

Default content

|-
| $1 || [[:$2]] || $3 || $4 || $5

Custom statistics

It's possible to add your own statistic types. New types can either implement an entirely new kind of statistic, or extend an existing one.

Creating a new type

In this example, we'll be creating a new type that lists the longest pages on the wiki.
Create a file called NewsletterQueryLongestPages.php that looks like this:

<?php
$wgExtensionMessagesFiles['Newsletter-LongestPages'] = dirname(__FILE__) . '/NewsletterQueryLongestPages.i18n.php';

class NewsletterQueryLongestPages extends NewsletterQuery
{
	protected function getQuery()
	{
		// The database query needs to be specified here
		// For examples on how to specify more complex
		// queries than this extremely simple example,
		// see the getQuery() functions in NewsletterQuery.php

		// SELECT page_namespace, page_title, page_len
		// FROM page
		// ORDER BY page_len DESC
		// LIMIT 20
		return array(
			'tables' => 'page',
			'fields' => array('page_namespace', 'page_title', 'page_len'),
			'options' => array('ORDER BY' => 'page_len DESC', 'LIMIT' => 20)
		);
	}

	protected function formatRow($row)
	{
		// This function formats a single row in the resulting table

		wfLoadExtensionMessages('Newsletter-LongestPages');
		// Create a title object corresponding to the page
		$title = Title::makeTitle($row->page_namespace, $row->page_title);
		// Use the newsletterquerylongestpages-row message here
		// $this->getRank($row->page_len) gets the rank number for this row
		// $title->getPrefixedText() gets the full title of the page
		return wfMsgExt('newsletterquerylongestpages-row', array(),
				$this->getRank($row->page_len), $title->getPrefixedText(),
				$row->page_len);
	}

	protected function fullOutput($rows)
	{
		// This function formats the entire statistic

		wfLoadExtensionMessages('Newsletter-LongestPages');
		// Use the newsletterquerylongestpages-boilerplate message here
		// $rows is the result of calling formatRow() on every row
		return wfMsgExt('newsletterquerylongestpages-boilerplate', array(), $rows);
	}
}

Then create a file called NewsletterQueryLongestPages.i18n.php that looks like this:

<?php
$messages['en'] = array(
	'newsletterquerymostedited-boilerplate'	=>	"=== 20 longest pages ===\n{|\n! Rank !! Page !! Length\n$1\n|}\n",
	'newsletterquerymostedited-row'		=>	"|-\n| $1 || [[:$2]] || $3\n",
);

Now add the following line to LocalSettings.php, BELOW the require_once() line mentioned here:

require_once("$IP/extensions/Newsletter/extended/NewsletterQueryLongestPages.php");

(Replace the path to NewsletterQueryLongestPages.php with whatever the appropriate path is.)
Now add a line saying NewsletterQueryLongestPages to the newsletter-queryclasses message, and you're done.

Extending existing types

It's also possible to extend existing types. What you're really doing in that case is creating a new type that's very much like the old type, but slightly different. To extend an existing type, you need to follow the same steps for creating a new one, except:

instead of class NewsletterQueryNewType extends NewsletterQuery, use class NewsletterQueryNewType extends NewsletterQueryOldType
you don't need to implement all three methods from the example. If you don't implement one, the code from the 'old' type will be used instead.
in methods that you do implement, it's usually best to run the old type's method and modify its return value. To e.g. call the old type's getQuery() method, use parent::getQuery(). This is also done by the built-in statistics' __construct() method
you don't need to create an .i18n.php file if you're not adding any messages (because you're only using the old type's messages). In that case, you can also remove the $wgExtensionMessagesFiles and wfLoadExtensionMessages() lines

Licensing and downloads

The extension is available under the GNU General Public License version 3 or later, and can be downloaded from Subversion, or accessed via the web-based viewer.
The software is provided as-is. Updates will be made where critical vulnerabilities are discovered.

Translating Newsletter

If Newsletter hasn't been translated to your language (completely), feel free to help out. Visit BetaWiki for more information.

Contact

Newsletter is currently maintained by Roan Kattouw. If you have any questions, complaints, feature requests, found a bug, or any other reason to contact the maintainer, please send your e-mails to [email protected] and mention "Newsletter" in the subject.