PendingChanges

Summary: Browser and desktop notifications for page changes
Version: 20191117a
Prerequisites:
Status: Experimental
Maintainer: Petko
License: GPL
Categories: Security, Ajax, PHP55, PHP72
Users: (view? / edit)

Browser and desktop notifications for page changes.

Description

It was written to be used here, on Site.AllRecentChangesShort.

This recipe allows for a page on the wiki to periodically check for changes and display a message when it was modified.

When the page has been modified since the user has opened it, 3 types of notifications are possible:

  • a short highlighted message appears near the page header or title, the user can click on it to reload the page
  • the browser tab title is modified and "(3)" is inserted before it, here 3 means there were 3 changes since the page was opened
    • some browsers will change the tab appearance when the title changes, for example Firefox will show a blue ball on "pinned" tabs
  • the user can enable desktop notifications, then a brief message will appear in the desktop notification area (usually top right).

Installation

  • Place pendingchanges.phpΔ in your cookbook directory.
  • Add to local/config.php, or to local/Site.AllRecentChanges.php
    include_once("$FarmD/cookbook/pendingchanges.php");

Configuration

The following settings can be configured before the include_once(...) line, with the default shown here:

  • $PendingChanges['delayminutes'] = 5; # how long between the checks for changes, default 5 minutes
  • $PendingChanges['querySelector'] = '#wikitext'; # the document.querySelector of the element where the message is inserted - can be a parent element or a sibling
  • $PendingChanges['where'] = 'afterbegin'; # the relation to the 'querySelector', where the message to be inserted, can be 'afterbegin', 'afterend', 'beforebegin' or 'beforeend'
  • $PendingChanges['page-override'] = array('Site.AllRecentChangesShort' => 'Site.AllRecentChanges'); # override pages, for example an included page that will be modified more often; in this case, a user requesting pending changes from AllRecentChangesShort will actually receive the changes from AllRecentChanges
  • $HTMLStylesFmt['PendingChanges'] = "#pendingchanges {background-color: #ff8; cursor: pointer;}"; # the default styles for the message division block
  • $XL['en']['PendingChanges'] = '(%s) Pending changes, click to reload.'; # the message format, "%s" is required and will be replaced with the number of changes
  • $XL['en']['EnableDesktopNotifications'] = 'Enable desktop notifications'; # the button text

As an example, here is the configuration on this site, placed in local/Site.AllRecentChangesShort.php:

  $PendingChanges['querySelector'] = '#wikititle .pagegroup';
  $PendingChanges['where'] = 'beforeend';
  $HTMLStylesFmt['PendingChanges'] = '#pendingchanges {
    background-color: #f9b976; cursor: pointer; 
    margin-left: 1em; display: inline;}';
  include_once("cookbook/pendingchanges.php");

This causes the message to appear above the page title next to the "Site /" link rather than below the title, and in light orange rather than light yellow.

Internationalization

The following strings can be translated in an XLPage, for example in French:

  'PendingChanges' => '(%s) Modifications en cours, cliquez pour recharger.'
  'EnableDesktopNotifications' => 'Activer les notifications'

Usage

In a page where you want to enable notifications for pending changes, add this directive:

  (:pendingchanges:)

The first time when you or someone else opens it, there will be a button "Enable desktop notifications". To enable these click on the button, and confirm that you accept to receive notifications (the button will disappear). If you don't click on the button, or don't allow desktop notifications, you will not see these, only the tab title will change and the in-page message will appear. Same if your browser doesn't support this feature.

Keep this page open in a tab, for example a "pinned" tab in Firefox or Chrome. The recipe will check for changes every 5 minutes, and if there are changes, it will display the 3 kinds of messages outlined in the section Description.

This is currently enabled at Site.AllRecentChangesShort.

Notes

  • The recipe uses the "page revision number" which is increased every time a page is saved. It will still report a change even if someone edited and saved the page without making any change.
  • It currently doesn't "watch" for changes in included pages or sections, pagelists, or page text variables in other pages, or if for example a link like [[OtherPage|+]] had its title changed. It is possible to add a page override list, see the Configuration section.
  • This uses the simple Notification API, not the Push Notification API. It only works as long as the page is in the browser, if you close the page you will no longer receive desktop notifications.
  • The Notification API only works over the secure (HTTPS) protocol. Over HTTP, only the other 2 notifications will work.
  • Whether you allow or block the desktop notifications, you can change your settings later, see your browser documentation.

To do / some day / maybe

Some day, if there is funding:

  • A way to check for changes in included pages.
  • Use Push Notifications instead.

Change log / Release notes

  • 20191117a : made it to work with LocalTimes -- if enabled on the same page -- to update the timestamp in the page title.
  • 20191117 : Fix typo causing an error.
  • 20191116 : Initial release, ready to be tested.

See also

Cookbook /
LocalTimes  Display RecentChanges and History timestamps in the local timezone of each visitor. (Beta)
SpamFilters  Automatic blocking of some spambots (beta)
TrackChanges  Ways to more easily detect and verify all recent edits
PmWiki /
Notify  How to receive email messages whenever pages are changed on the whole wiki site, individual groups or selected watchlists of pages

Contributors

Recipe written, documented and maintained by Petko.

Comments

See discussion at PendingChanges-Talk?

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.