Extension:ReadingLists

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
Crystal Clear action run.svg
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 release branches
MediaWiki 1.30+
PHP 5.5+
Database changes Yes
License GNU General Public License 2.0 or later
Download
README.md
Parameters
see #Configuration
Services defined
ReverseInterwikiLookup
Hooks used
APIQuerySiteInfoGeneralInfo
Translate the ReadingLists extension if it is available at translatewiki.net
Check usage and version matrix.
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]

  • If using Vagrant , install with vagrant roles enable readinglists --provision
Manual installation
  • Download and place the file(s) in a directory called ReadingLists in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    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.

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.

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

Parameters:
rllist

List ID.

The value must be no less than 1.
Type: integer
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 2018-10-14T13:32:13Z. 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.

No more than 10 (10 for bots) allowed.
Type: integer or max
Default: 10
rlcontinue

When more results are available, use this to continue.

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. 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.)

Parameters:
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 bots).
rlechangedsince

Show list entries that have been changed since this timestamp. Must be after 2018-10-14T13:32:13Z.

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.

No more than 100 (100 for bots) allowed.
Type: integer or max
Default: 10
rlecontinue

When more results are available, use this to continue.

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

Parameters:
command

Command (API submodule) for reading list write operations.

create
Create a new list for the current user.
createentry
Add a new page to a list belonging to the current user.
delete
Delete a list belonging to the current user.
deleteentry
Delete a page from a list belonging to the current user.
setup
Enable lists for the current user.
teardown
Disable lists for the current user.
update
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. 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. 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. 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.

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

command=update

(main | readinglists | update)
  • This module is internal or unstable. 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.

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

command=delete

(main | readinglists | delete)
  • This module is internal or unstable. 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.

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

command=createentry

(main | readinglists | createentry)
  • This module is internal or unstable. 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.

Parameters:
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 localised 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.

command=deleteentry

(main | readinglists | deleteentry)
  • This module is internal or unstable. 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.

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

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]