Extension:GlobalPreferences/API

From MediaWiki.org
Jump to navigation Jump to search

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

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

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. In the case of an arbitrary userjs- name/value pair, the resetting results in the removal of the name/value pair; in other words - deletion.
  • 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

Resetting all preferences and then setting a single one

Changing three preferences

Possible errors[edit]

In addition to the usual stuff :

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