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: Replace  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: If you have created any custom groups in LocalSettings.php, you can allow these groups to send mass e-mails by adding 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  by   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: 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  on the command line. Run  to get a list of options you can use. You'll probably want to run this command as a cron job.

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.

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.

Description
The list of statistics to use. You can add, remove and rearrange statistics here. The pre-defined statistics are:
 * : Basic site statistics like number of pages, etc.
 * : Top 20 most edited pages since the last newsletter
 * : Top 20 most active users since the last newsletter
 * : Top 20 most expanded (i.e. increased in size) pages whose existence predates the last newsletter

Default content
NewsletterQueryStatistics NewsletterQueryMostEdited NewsletterQueryMostActive NewsletterQueryMostEditedNew NewsletterQueryMostExpandedOld

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

Parameters

 * is replaced by the time the newsletter was built

Default content
Project:Newsletter/

Description
The edit summary to use when archiving the newsletter

Parameters

 * is replaced by the time the newsletter was built

Default content
Archiving newsletter

Description
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

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

Parameters

 * is replaced by the time the newsletter was built
 * is replaced by the URL of the archived version of the newsletter

Default content
This is the newsletter for.

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

Description
The subject of the newsletter e-mail

Parameters

 * is replaced by the time the newsletter was built

Default content
newsletter

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

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

Parameters

 * is replaced by the statistics (see also other boilerplates)
 * is replaced by the time the newsletter was built
 * is replaced by the name of the page

Default content
If your e-mail client doesn't render this message properly, you can read it on-wiki at.

by the numbers
$1

Subscribe or unsubscribe
To subscribe to or unsubscribe from this newsletter, go here. You will need to create an account if you don't have one.

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

Parameters

 * is replaced by the number of page views at the time the last newsletter was built
 * is replaced by the number of edits
 * is replaced by the number of articles (i.e. pages in the main namespace that aren't redirects and contain )
 * is replaced by the number of pages
 * is replaced by the number of users
 * is replaced by the number of sysops
 * is replaced by the number of images
 * is replaced by the time the last newsletter was built
 * is replaced by the number of page views at the time thisnewsletter was built
 * is replaced by the time this newsletter was built
 * is replaced by the time this newsletter was built

Description
The boilerplate for the most edited pages statistic

Parameters

 * is replaced by the table rows representing pages

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

Parameters

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

Default content

 * $1 || $2 || $3
 * $1 || $2 || $3

Description
The boilerplate for the most active users statistic

Parameters

 * is replaced by the table rows representing users

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

Parameters

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

Default content

 * $1 || $2 || $4
 * $1 || $2 || $4

Description
The boilerplate for the most edited new pages statistic

Parameters

 * is replaced by the table rows representing pages

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

Parameters

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

Default content

 * $1 || $2 || $3
 * $1 || $2 || $3

Description
The boilerplate for the most expanded older pages statistic

Parameters

 * is replaced by the table rows representing pages
 * is replaced by the time the last newsletter was built
 * is replaced by the time this newsletter was built

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

Parameters

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

Default content

 * $1 || $2 || $3 || $4 || $5
 * $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  that looks like this:

Then create a file called  that looks like this:

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

(Replace the path to  with whatever the appropriate path is.)

Now add a line saying  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, use
 * 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  method, use  . This is also done by the built-in statistics'   method
 * you don't need to create an  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   and   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 [mailto:roan.kattouw@home.nl roan.kattouw@home.nl] and mention "Newsletter" in the subject.