Manual:Watchlist
A watchlist is a set of pages a user has selected to monitor for changes. Watchlists are available to all logged-in users, and cause specific additional behaviour in changes lists, such as recent changes. More broadly speaking, a user's watchlist allows identification of changes that interest them. A title does not need to exist to be watched.
A user's watchlist is not available to other users except when included in aggregation, such as the unwatched pages report available to privileged users. Users are considered free to keep their watchlists private, or to share them with others to assist in monitoring for vandalism or undesirable changes on specific pages, for example.
Watching pages
Users can add pages to their watchlist via the "Watch" link present on each page. In the default skin, this can be found as an action tab at the top of the page. When AJAX watching is enabled, an AJAX request is used to add the watch and update the interface, if possible.
Pages can also be added to the watchlist during editing, and when performing certain operations, including moving and deletion. In these cases, a check box is made available when confirming the operation to allow toggling this. This behavior can also be customized further via the Watchlist tab on Special:Preferences.
Since MediaWiki 1.35, you can optionally select to watch a page for a temporary period of time. This requires $wgWatchlistExpiry to be enabled. The option is then available when editing or selecting to watch a page via the "Watch" link or action=watch. The expiry times available when editing can be customized via the MediaWiki:Watchlist-expiry-options system message.
It is also possible to bulk-add pages to the watchlist using the watchlist editor in raw mode, described below.
Unwatching pages
Removing a page from the watchlist can be done in a near-identical fashion to adding it; when viewing a page being watched, the "watch" link is replaced with an "unwatch" link which, when clicked, removes the page from the watchlist. As with watching, this uses an AJAX request if possible.
It is also possible to remove pages from the watchlist using the watchlist editor in either normal or raw mode, both described below.
Editing the watchlist
The watchlist editor provides several modes for managing the contents of the watchlist. Users can remove several items from their watchlist at once, can clear their entire watchlist, and can edit a raw list of watched pages.
Normal mode
The standard watchlist editor is accessible at Special:Watchlist/edit and provides a list of watched titles; users select titles to be removed from the watchlist, and upon confirming the operation, this is done.
Raw mode
A convenient means of editing the watchlist is to use the raw editing mode, accessible via Special:Watchlist/raw. This presents the entire contents of the watchlist in a plain text list, with one title per line, which can then be edited as desired.
This provides a convenient method to bulk-add or bulk-remove items from the watchlist, and to access the watchlist in order to copy it to other wikis or to share with other users.
Change lists
Recent changes
The presence of a page on the watchlist will cause it to become emphasised when it appears on change lists, such as Special:Recentchanges and Special:Recentchangeslinked.
Watchlist
The Special:Watchlist page provides users with a complete list of the most recent changes to the pages on their watchlist, which can be further filtered to pinpoint specific classes of edit.
Certain behaviours of this page can be customised through user preferences, accessible via the Watchlist tab in Special:Preferences, including:
- length of time to represent in the watchlist, or the maximum number of edits
- whether to limit to the most recent edit to a page, or expand to show all relevant changes
- default filtering preferences for bot, minor or one's own edits
Technical implementation details
The watchlist code is scattered over several files, including:
- /includes/actions
- WatchAction.php
- UnWatchAction.php
- /includes/user/User.php
- /includes/specials/SpecialEditWatchlist.php
- /includes/jobqueue/jobs/WatchlistExpiryJob.php
- /resources/src/mediawiki.page.watch.ajax.js
However all of the above make use of WatchedItemStore.php for performing DB related actions which is the storage layer class for WatchedItems. The WatchedItem class represents a simple watched object (user, page (LinkTarget object), notification timestamp, expiry period).
WatchedItemStore takes care of:
- Adding a page/list of pages to watchlist
- Removing a page from watchlist
- Counting watched items
- Counting number of unread notifications
- Checking if a page is watched
- Set/Reset/Update notification timestamp
- Set/Update watched items' expiration date
- Remove expired pages from the watchlist
etc.
The SpecialWatchlist class is executed when the watchlist special page is called.
How a page is added to a watchlist
- User requests to add a page to their watchlist. This can happen in the following ways
- Clicking the star
- Creating a page
- Checking "Watch this page" after editing
- Editing Special:Watchlist/edit or Special:Watchlist/raw
- The page and talk-page are added to the "watchlist" table for the user.
What happens when a page is edited
- A page is edited.
- A hook runs, which calls updateNotificationTimestamp function from WatchedItemStore. This updates the notification timestamp for the page for each of the watcher's watchlist page except for the editor. (This is done by joining the page with the watchlist table for the users).
- The notification timestamp for the user's watchlist table is not NULL anymore and thus, it's now an unread notification.
- A job is queued depending on $wgWatchlistPurgeRate and expired items are removed from the watchlist.
What happens when an unread notification is clicked
- User clicks an unread watchlist entry
- The resetNotificationTimestamp function is called from WatchedItemStore with the user and title as params. This resets the value for that entry back to NULL.
When are expired items removed from the watchlist?
- After each edit a job is queued depending on the value of $wgWatchlistPurgeRate and expired items are removed from the watchlist.
- In small wikis, a script is available to be schedule and it will purge expired items from the watchlist.
The watchlist has an API whose code comes from APIQueryWatchlist. This class makes heavy use of WatchedItemQueryService class. This class does the complicated queries relating to Recentchanges and Watchlist code. When a user loads Special:Watchlist, the watchlist table is joined on the recent changes table to display entries to the user. This is why we can't have watchlist entries from beyond 30 days.
Special watchlist modes
- Extended watchlist - This is the option in Preferences to "Expand watchlist to show all changes, not just the most recent". This options shows you all entries for all pages. If you choose not to see the extended version, you see only one (most recent) entry for each page. In both cases it joins on the recentchanges table, but in the latter it only looks at the "page_latest" revision.
- Enhanced watchlist - This is the option in Preferences to "Group changes by page in recent changes and watchlist". The formatting is done in JavaScript by the EnhancedChangesList class.
