mwstake/periodic-related-changes

MediaWiki extension to set up periodic notifications of related changes

dev-master 2018-03-05 00:20 UTC

README

Periodic Related Changes (PRC) is a MediaWiki extension to specify that a user should get the related changes for a page during a specified period of time (usually a week).

Read the user manual to understand how to use this tool better.

Installation

Installing the PRC is straightforward.

Make sure Echo is installed

This extension relies on the Echo extension to send messages. Echo cannot (currently) be installed with composer, so you’ll need to install Echo separately before continuing.

Fetch the extension with composer

If you’re familiar with composer, then, to install PRC you just need to add a dependency on mwstake/periodic-related-changes.

If you don’t already have composer, you’ll need to download it.

From the command line, run the following:

	php composer.phar require mwstake/periodic-related-changes dev-master

Update LocalSettings.php

Add the following line to your LocalSettings.php:

	wfLoadExtension( 'PeriodicRelatedChanges' );

Run update.php

On the command line:

	php maintenance/update.php --quick

Verify installation

You should see “PeriodicRelatedChanges” listed on your wiki’s Special:Version page.

Setting up batched email notifications

Finally, if you want notifications sent in a batch on a daily or weekly basis, then it is absolutely necessary that you ensure that the auxillary script, processEchoEmailBatch.php is run.

You need to set up a recurring job that will run the following command at least once a day:

	php extensions/Echo/maintenance/processEchoEmailBatch.php

On a Unix-derived system like Linux or OS X, this can be done with a cron job. On Windows, you’ll probably want to use scheduled task cmdlets in PowerShell or SCHTASKS.

Forcing notices to a specific schedule.

Because of limitations of how Echo handles notifications, fine grained scheduling is not available. Administrators can, however, force all batched Echo notifications to go out at a specified time.

On Unix

For instance, if you want all PRC notifications to go out at 5pm on a Friday afternoon in a Unix cron job, the following cron entry would work:

0 17 * * 5 	php extensions/Echo/maintenance/processEchoEmailBatch.php -i

On Windows

Similarly, using SCHTASKS to perform this in Windows would look something like the following:

SCHTASKS /Create /SC weekly /D FRI /TN PRCNotifications /ST 17:00 /TR c:\do_prc.bat

You would have to execute the following command in do_prc.bat, or course:

php extensions/Echo/maintenance/processEchoEmailBatch.php -i

Cautions

Note that setting up weekly notifications in this way will affect all batched Echo notifications, not just those for PRC. This means that if a user has specified they want to be notified via email on a daily basis of comments on their page, but you only run processEchoEmailBatch.php once a week, they’ll only get the notices once a week.

Configuration

There are a few items you might want to configure for Echo and PRC. Each of the lines of code below can be put in your LocalSettings.php file.

PRC can send HTML email using Echo, but you need to enable it. (doc)

$wgAllowHTMLEmail = true;

If you want to batch up emails (that’s the “Periodic” part, after all), you need to enable batch notifications in Echo. (doc)

$wgEchoEnableEmailBatch = true;

You can send set the default email format for your users to HTML if you’d like. (doc)

$wgDefaultUserOptions['echo-email-format'] = 'html';

Optionally, don’t allow your users to change to the text-only email format.

$wgHiddenPrefs[] = 'echo-email-format';

Enable emailed PRC notifications for all users by default.

$wgDefaultUserOptions['echo-subscriptions-email-periodic-related-changes'] = true;

Don’t allow your users to turn off the notifications.

$wgHiddenPrefs[] = 'echo-subscriptions-email-periodic-related-changes';

Set your user’s to receive emails on a weekly basis by default.

$wgDefaultUserOptions['echo-email-frequency'] = 7;

The constant =EchoEmailFrequency::WEEKLY_DIGEST= is set to this number (7), but the constant can’t be used in the LocalSettings.php file in some versions of MediaWiki.

Optionally, don’t allow your users to change to daily to emails.

$wgHiddenPrefs[] = 'echo-email-frequency';

Disable (by default) un-batched, on-wiki Echo notifications for PRC.

$wgDefaultUserOptions['echo-subscriptions-web-periodic-related-changes'] = false;

User Permissions

PRC exposes two new permissions that can be assigned to groups:

  • periodic-related-changes - View and change the PRC notices for logged in user.
  • periodic-related-changes-any-user - View and change the PRC notices for any user.

By default, the periodic-related-changes right is assigned to the user group so that any logged in user can view and modify their own PRC notices; the periodic-related-changes-any-user right is assigned to the sysop (often displayed as “administrator” on the wiki) group.

If you want to take the rights away from these groups you would do something like the following in your LocalSettings.php:

// Take away the default rights
$wgGroupPermissions['user']['periodic-related-changes'] = false;
$wgGroupPermissions['sysop']['periodic-related-changes-any-user'] = false;

// Give them to other groups
$wgGroupPermissions['watchers']['periodic-related-changes'] = true;
$wgGroupPermissions['watch-admin']['periodic-related-changes-any-user'] = true;

Support

If you run into problems, please post a question on MediaWiki’s Support Desk and tag me (@MarkAHershberger).