Jump to content

Extension:GlobalPreferences/API

From mediawiki.org

Getting global preferences

[edit]

If only the effective preferences for a user are required, the usual meta=userinfo&uiprop=options can be used, however if you need to know where is every preference value coming from, you will need to use this API.

Parameters

[edit]
  • gprprop: Which preferences to get (Default: preferences|localoverrides)
    • preferences: Global preferences
    • localoverrides: Local overrides

Example

[edit]
Getting global preferences
Result
{
    "batchcomplete": "",
    "query": {
        "globalpreferences": {
            "preferences": {
                "advancedsearch": "1",
                "ccmeonemails": "1",
                "disablemail": "0",
                "email-allow-new-users": 1
            },
            "localoverrides": {
                "ccmeonemails": 0,
                "email-allow-new-users": 0
            }
        }
    }
}

Possible errors

[edit]

None.

Setting global preferences and local overrides

[edit]

Token

[edit]

To change options, a CSRF token is required.

Tokens can be obtained via action=query&meta=tokens

Obtaining a token
Result
{
    "query": {
        "tokens": {
            "csrftoken": "f38d52ee5c9b49ce17f5e55c48bb1166547cbc71+\\"
        }
    }
}

Changing options

[edit]

GlobalPreferences provides two modules to change preferences, action=globalpreferences and action=globalpreferenceoverrides. They work exactly like action=options and have the same parameters.

Parameters

[edit]
  • reset: Resets all preferences.
    • Resetting a global preference means it will not be global anymore while resetting a local override means that the global preference will be used.
  • resetkinds: List of types of preferences to reset when the reset parameter is set. (Default: all)
  • change: Pipe-separated list of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters.
Note: Providing only names of preferences without equal sign (e.g. hideminor|skin) results in resetting them.
  • optionname: A name of a preference which should have an optionvalue set.
  • optionvalue: A value of the preference specified by the optionname, can contain pipe characters.
  • token: A "csrf" token retrieved from action=query&meta=tokens

The change parameter cannot be used to set a value which contains a pipe character "|", as it is used by the API to separate options. If you need to set such a value (for example, a user signature) use an optionname & optionvalue pair.

Example

[edit]

Note: In this example, all parameters are passed in a GET request for the sake of simplicity. However, changing preferences requires POST requests; GET requests will cause an error.

Changing a single preference
Result
{
    "globalpreferences": "success"
}
Resetting all preferences and then setting a single one
Result
{
    "globalpreferences": "success"
}
Changing three preferences
Result
{
    "globalpreferenceoverrides": "success"
}

Possible errors

[edit]

In addition to the usual stuff :

Code Info
notloggedin Anonymous users cannot change preferences
nochanges No changes were requested