Extension:ReadingLists
![]() Release status: beta |
|
---|---|
Implementation | API |
Description | Provides an API for storing and retrieving private lists of pages. |
Author(s) | User:Tgr (WMF) |
Latest version | 0.1.0 (2017-07-20) |
Compatibility policy | Snapshots releases along with MediaWiki. Master is not backward compatible. |
MediaWiki | 1.30+ |
PHP | 5.5+ |
Database changes | Yes |
Tables | reading_list reading_list_entry reading_list_project |
License | GNU General Public License 2.0 or later |
Download | README.md |
|
|
Quarterly downloads | 7 (Ranked 126th) |
Public wikis using | 859 (Ranked 305th) |
Translate the ReadingLists extension if it is available at translatewiki.net | |
Vagrant role | readinglists |
Issues | Open tasks · Report a bug |
The ReadingLists extension provides an API to store and retrieve private lists of pages, e.g. for a "bookmark" or "read it later" feature. On wikifarms, lists can contain pages from multiple wikis.
When RESTBase is installed, the extension powers the Reading List Service.
Installation
[edit]- Download and move the extracted
ReadingLists
folder to yourextensions/
directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/ReadingLists - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'ReadingLists' );
- Run the update script which will automatically create the necessary database tables that this extension needs.
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Vagrant installation:
- If using Vagrant , install with
vagrant roles enable readinglists --provision
Setting up project whitelist
[edit]The project part of list entries needs to be selected from a static list stored in readinglists.sql
. If the SiteMatrix extension is installed, you can run the populateProjectsFromSiteMatrix.php
maintenance script to fill the list with project domain names (in the format http://example.org
). Alternatively you can just fill it by hand.
Setting up read only web interface
[edit]In 1.40 a read only web interface will be provided. See gerrit patch. you will be able to enable it using the following feature flags:
$wgReadingListsWeb = true;
$wgReadingListsWebAuthenticatedPreviews = true;
Setting up import functionality with apps
[edit]The reading list page supports ?limport and lexport query string parameters that can be read by an app to support importing/exporting lists.
To enable this functionality you will need to configure URLs to suitable apps like so:
$wgReadingListsWeb = true;
$wgReadingListAndroidAppDownloadLink = "https://play.google.com/store/apps/details?id=org.wikipedia&referrer=utm_source%3DreadingListsShare";
$wgReadingListiOSAppDownloadLink = "https://itunes.apple.com/app/apple-store/id324715238?pt=208305&ct=readingListsShare";
// Optionally you can also anonymize the import URL (enable anonymized previews)
$wgReadingListsAnonymizedPreviews = true;
You will also need to define the message keys MediaWiki:readinglists-import-app, MediaWiki:readinglists-list-empty-message to mention the application.
On Wikimedia wikis this is done using WikimediaMessages.
Configuration
[edit]parameter | default | comment |
---|---|---|
$wgReadingListsCluster | false
|
Database cluster to use, or false for using the default cluster |
$wgReadingListsDatabase | false
|
Database to use, or false for using the default database. |
$wgReadingListsCentralWiki | true
|
Database name of the central wiki, or false to always assume the current wiki is the central one. This will only be used to make sure things like DB schema upgrades or scheduled jobs are not executed multiple times. |
$wgReadingListsMaxListsPerUser | 100
|
Maximum allowed number of lists per user. |
$wgReadingListsMaxEntriesPerList | 1000
|
Maximum allowed number of entries per list. |
$wgReadingListsDeletedRetentionDays | 30
|
Number of days after which soft-deleted lists and list entries become hard-deleted. Clients which haven't synced changes for this long cannot use sync, and need to re-download all lists. |
API
[edit]meta=readinglists (rl)
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- Source: ReadingLists
- License: GPL-2.0-or-later
List or filter the user's reading lists and show metadata about them.
This module has four modes of operation. With the rllist parameter, it returns information about the specified list. With the rlchangedsince parameter, it returns all lists of the current user which have been changed since the given date. (This is meant for device sync and, unlike the other modes, includes deleted lists. Only changes to list metadata are considered, not changes to list items.) With the rlproject and rltitle parameters, it returns all lists that include that page. Without any of those parameters, it returns all lists.
- rllist
List ID.
- Type: integer
- The value must be no less than 1.
- rlproject
Project of the page to filter on. Must be used together with rltitle. Will only return lists which include this project and title.
- rltitle
Title of the page to filter on. Must be used together with rlproject. Will only return lists which include this project and title.
- rlchangedsince
Show lists that have been changed since this timestamp. Must be after 2024-07-26T12:49:31Z. Clients should use the timestamp returned in the readinglists-synctimestamp field from an earlier call if they want to ensure that no changes are missed, and should be prepared to receive changes that have already been returned in an earlier response, and handle them in an idempotent way.
- Type: timestamp (allowed formats)
- rlsort
Property to sort by. Ignored when rlproject and rltitle is set (results are returned in DB order). Defaults to updated when rlchangedsince is set, and to name otherwise.
- name
- List name. (Sorting is by binary value; e.g. any uppercase ASCII character will sort before any lowercase one.)
- updated
- Last update timestamp. (Updates include list metadata changes but not changes to list items.)
- One of the following values: name, updated
- rldir
Sort direction: ascending (A to Z, oldest to newest) or descending. Ignored when rlproject and rltitle is set.
- One of the following values: ascending, descending
- Default: ascending
- rllimit
Number of result items to return.
- Type: integer or max
- The value must be between 1 and 10.
- Default: 10
- rlcontinue
When more results are available, use this to continue. More detailed information on how to continue queries can be found on mediawiki.org.
- Get the reading lists of the current user.
- api.php?action=query&meta=readinglists [open in sandbox]
- Get the reading lists of the current user which have changed since 2013-01-01T00:00:00Z.
- api.php?action=query&meta=readinglists&rlchangedsince=2013-01-01T00:00:00Z [open in sandbox]
- Get the reading lists of the current user which contain the page Dog from project en.wikipedia.org
- api.php?action=query&meta=readinglists&rlproject=https%3A%2F%2Fen.wikipedia.org&rltitle=Dog [open in sandbox]
list=readinglistentries (rle)
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module can be used as a generator.
- Source: ReadingLists
- License: GPL-2.0-or-later
List the pages of a certain list.
This module has two modes of operation. With the rlelists parameter, it returns the pages in the given list(s). With the rlechangedsince parameter, it returns all list entries from any list of the current user which have been changed since the given date. (This is meant for device sync and, unlike the other modes, includes deleted entries, although not entries of deleted lists.)
- rlelists
The list IDs for which to return pages.
- Type: list of integers
- Separate values with | or alternative.
- Maximum number of values is 50 (500 for clients that are allowed higher limits).
- rlechangedsince
Show list entries that have been changed since this timestamp. Must be after 2024-07-26T12:49:31Z.
- Type: timestamp (allowed formats)
- rlesort
Property to sort by. name cannot be used together with rlechangedsince. Defaults to updated when rlechangedsince is set, and to name otherwise.
- name
- Article title. (Project name is ignored. Sorting is by binary value; e.g. any uppercase ASCII character will sort before any lowercase one.)
- updated
- Last update timestamp.
- One of the following values: name, updated
- rledir
Sort direction: ascending (A to Z, oldest to newest) or descending.
- One of the following values: ascending, descending
- Default: ascending
- rlelimit
Number of result items to return.
- Type: integer or max
- The value must be between 1 and 100.
- Default: 10
- rlecontinue
When more results are available, use this to continue. More detailed information on how to continue queries can be found on mediawiki.org.
- Get the pages from the reading lists with ID 10, 11 and 12.
- api.php?action=query&list=readinglistentries&rlelists=10|11|12 [open in sandbox]
- Get the list entries of the current user which have changed since 2013-01-01T00:00:00Z.
- api.php?action=query&list=readinglistentries&rlechangedsince=2013-01-01T00:00:00Z [open in sandbox]
action=readinglists
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Reading list write operations.
Create/update/delete/sort reading lists and entries. See the documentation of the various commands for details.
- command
Command (API submodule) for reading list write operations.
- create
- Internal. Create a new list for the current user.
- createentry
- Internal. Add a new page to a list belonging to the current user.
- delete
- Internal. Delete a list belonging to the current user.
- deleteentry
- Internal. Delete a page from a list belonging to the current user.
- setup
- Internal. Enable lists for the current user.
- teardown
- Internal. Disable lists for the current user.
- update
- Internal. Update a list belonging to the current user.
- This parameter is required.
- One of the following values: create, createentry, delete, deleteentry, setup, teardown, update
- token
A "readinglists+" token retrieved from action=query&meta=tokens
- This parameter is required.
command=setup
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Enable lists for the current user.
This command must be used before the user can do anything else with reading lists. Also creates a default list. To undo it, use teardown.
- Set up reading lists for the current user.
- api.php?action=readinglists&command=setup&token=123ABC [open in sandbox]
command=teardown
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Disable lists for the current user.
Removes all reading list data for the user. The setup command must be used if the user wishes to begin using reading lists again.
- Disable reading lists for the current user.
- api.php?action=readinglists&command=teardown&token=123ABC [open in sandbox]
command=create
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Create a new list for the current user.
The user must have fewer than 100 (non-deleted) lists.
- name
List name. Required unless using batch creation.
- Cannot be longer than 255 bytes.
- description
List description.
- Cannot be longer than 767 bytes.
- batch
Batch data for creating multiple lists in a single request, in the form of a JSON array with one or more objects with name and (optionally) description fields.
- Create a new reading list.
- api.php?action=readinglists&command=create&name=dogs&description=Woof!&token=123ABC [open in sandbox]
- Create multiple new lists.
- api.php?action=readinglists&command=create&batch=%5B%7B%22name%22%3A%22dogs%22%2C%22description%22%3A%22Woof%21%22%7D%2C%7B%22name%22%3A%22cats%22%2C%22description%22%3A%22Meow%22%7D%5D&token=123ABC [open in sandbox]
command=update
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Update a list belonging to the current user.
- list
List ID. Required unless using batch update.
- Type: integer
- name
New list name. Either this or description is required unless doing batch update.
- Cannot be longer than 255 bytes.
- description
New list description.
- Cannot be longer than 767 bytes.
- batch
Batch data for updating multiple lists in a single request, in the form of a JSON array with one or more objects with list, name and description fields. Name and description are optional but at least one of them must be present.
- Change the name of the reading list with ID 42.
- api.php?action=readinglists&command=update&list=42&name=New+name&token=123ABC [open in sandbox]
- Update multiple lists.
- api.php?action=readinglists&command=update&batch=%5B%7B%22list%22%3A42%2C%22name%22%3A%22New+name%22%7D%2C%7B%22list%22%3A43%2C%22description%22%3A%22New+description%22%7D%5D&token=123ABC [open in sandbox]
command=delete
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Delete a list belonging to the current user.
Deleted lists remain available for some amount of time through the readinglists and readinglistentries modules (via the changedsince parameter). There is no way to undelete.
- list
List ID. Required unless doing batch deletion.
- Type: integer
- batch
Batch data for deleting multiple lists in a single request, in the form of a JSON array with one or more objects with a list field.
- Delete the reading list with ID 11.
- api.php?action=readinglists&command=delete&list=11&token=123ABC [open in sandbox]
- Delete multiple lists.
- api.php?action=readinglists&command=delete&batch=%5B%7B%22list%22%3A11%7D%2C%7B%22list%22%3A12%7D%5D&token=123ABC [open in sandbox]
command=createentry
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Add a new page to a list belonging to the current user.
List entries must be unique. Pages are not limited to the wiki where the API is accessed. The user must have fewer than 5000 (non-deleted) entries in the list.
- list
List ID.
- This parameter is required.
- Type: integer
- project
Project name of the wiki hosting the page. (Typically this is the domain name of the wiki.) Required unless doing batch creation.
- Cannot be longer than 255 bytes.
- title
Page title (including the localized namespace name). Required unless doing batch creation. Human-readable format (spaces not underscores) is recommended. The API treats titles as raw strings; normalization (such as title casing) is left to the clients.
- Cannot be longer than 383 bytes.
- batch
Batch data for creating multiple list entries (in the same list) in a single request, in the form of a JSON array with one or more objects with project and title fields.
- Add the page Dog from project en.wikipedia.org to the list with ID 33.
- api.php?action=readinglists&command=createentry&list=33&project=https%3A%2F%2Fen.wikipedia.org&title=Dog&token=123ABC [open in sandbox]
- Add multiple pages to a list.
- api.php?action=readinglists&command=createentry&list=33&batch=%5B%7B%22project%22%3A%22https%3A%5C%2F%5C%2Fen.wikipedia.org%22%2C%22title%22%3A%22Dog%22%7D%2C%7B%22project%22%3A%22https%3A%5C%2F%5C%2Fen.wikipedia.org%22%2C%22title%22%3A%22Cat%22%7D%5D&token=123ABC [open in sandbox]
command=deleteentry
- This module is internal or unstable, and you should not use it. Its operation may change without notice.
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: ReadingLists
- License: GPL-2.0-or-later
Delete a page from a list belonging to the current user.
- entry
Entry ID. Required unless doing batch deletion.
- Type: integer
- batch
Batch data for deleting multiple list entries in a single request, in the form of a JSON array with one or more objects with an entry field.
- Delete the list entry with ID 8.
- api.php?action=readinglists&command=deleteentry&entry=8&token=123ABC [open in sandbox]
- Delete multiple list entries.
- api.php?action=readinglists&command=deleteentry&batch=%5B%7B%22entry%22%3A8%7D%2C%7B%22entry%22%3A9%7D%5D&token=123ABC [open in sandbox]
Maintenance scripts
[edit]purge.php
[edit]Hard-deletes deleted lists and entries older than a cutoff date. Also does other DB cleanup that has no effect on functionality. Meant to be called from a cron job.
Option | Description |
---|---|
--before <timestamp> | Cutoff date in a wfTimestamp() -compatible format. Defaults to $wgReadingListsDeletedRetentionDays days ago.
|
populateProjectsFromSiteMatrix.php
[edit]Fills the reading_list_project
with the origins (schema + domain name) of the wikifarm's wikis. Requires the SiteMatrix extension.
See also
[edit]- Reading/Reading_Lists
- Browser plugin to add articles to a list: Chrome, Firefox, source
![]() | This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |