Jump to content

Extension:ReadingLists

Issue tracker: #reading_list_service
From mediawiki.org
MediaWiki extensions manual
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
Download extension
Git [?]:

README.md
Parameters
  • $wgReadingListsWebAuthenticatedPreviews
  • $wgReadingListsDeveloperMode
  • $wgReadingListsAnonymizedPreviews
  • $wgReadingListAndroidAppDownloadLink
  • $wgReadingListiOSAppDownloadLink
  • $wgReadingListsMaxListsPerUser
  • $wgReadingListsDeletedRetentionDays
  • $wgReadingListsMaxEntriesPerList
  • $wgReadingListsCentralWiki
Services defined
Hooks used
Quarterly downloads 2 (Ranked 131st)
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 your extensions/ 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.
  • Yes 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]
Configuration settings
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)

(main | query | readinglists)
  • 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.

Specific parameters:
Other general parameters are available.
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-10-11T21:47:41Z. 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.

Examples:
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)

(main | query | readinglistentries)
  • 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.)

Specific parameters:
Other general parameters are available.
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-10-11T21:47:41Z.

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.

Examples:
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

(main | 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.

Specific parameters:
Other general parameters are available.
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 "csrf" token retrieved from action=query&meta=tokens

This parameter is required.


command=setup

(main | readinglists | 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.

Example:
Set up reading lists for the current user.
api.php?action=readinglists&command=setup&token=123ABC [open in sandbox]

command=teardown

(main | readinglists | 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.

Example:
Disable reading lists for the current user.
api.php?action=readinglists&command=teardown&token=123ABC [open in sandbox]

command=create

(main | readinglists | 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.

Specific parameters:
Other general parameters are available.
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.

Examples:
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

(main | readinglists | 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.

Specific parameters:
Other general parameters are available.
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.

Examples:
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

(main | readinglists | 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.

Specific parameters:
Other general parameters are available.
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.

Examples:
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

(main | readinglists | 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.

Specific parameters:
Other general parameters are available.
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.

Examples:
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

(main | readinglists | 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.

Specific parameters:
Other general parameters are available.
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.

Examples:
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.

Options
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]
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:ReadingLists&oldid=5590799"