Sware: 1 revision imported

2025-11-04T17:55:40Z

1 revision imported

← Older revision	Revision as of 17:55, 4 November 2025
(No difference)

wikt>Ioaxxere: docs should encourage good style

2025-09-14T16:29:49Z

docs should encourage good style

New page

/* global mw */
// <nowiki>
/*jshint shadow:true, undef:true, latedef:true, unused:true, esversion:3 */

/**
* WiktGadgetPrefs -- developed by [[wikt:en:User:Surjection]]
*
* ***********************************************************************
* Documentation for gadget authors:
* Example usage (remember to add ext.gadget.WiktGadgetPrefs as a dependency):

const preferences = mw.wiktGadgetPrefs.get("gadgetfoobar",
{
"label": {
"en": "Foobar Gadget"
}
},
{
"frobulate": {
"type": "boolean",
"default": false,
"label": {
"en": "Whether this gadget should frobulate"
}
}
}
);
const shouldFrobulate = preferences.frobulate;

// strenum example
const preferences = mw.wiktGadgetPrefs.get("gadgetfoobar",
{
"label": {
"en": "Foobar Gadget"
}
},
{
"frobulate": {
"type": "strenum",
"default": "yes",
"label": {
"en": "Whether this gadget should frobulate"
},
"choices": [
"yes",
"no",
"maybe"
],
"choiceLabels": {
"en": {
"yes": "Yes!",
"no": "No!!",
"maybe": "Maybe?"
}
}
}
}
);
const shouldFrobulate = preferences.frobulate;
***********************************************************************
*
* Dependencies needed: mw.user, user.options
*/

(function() {
"use strict";
/**
* @typedef WiktGadgetOptions
* - Represents gadget options.
* @property {{[languageCode: string]: string}} [label]
* - The label to display on the preferences page for this
* gadget/namespace. The language code should be a MediaWiki
* language code, e.g. "en" for English.
*/

/**
* @typedef WiktGadgetPreference
* - Represents a single preference.
* @property {{"boolean"|"integer"|"string"|"strenum"|"object"}} type
* - Must be one of the following:
* - "boolean" for boolean values, either true or false.
* - "integer" for an integer value.
* - "string" for a string value.
* - "strenum" for a string value that must be one of the options.
* - "object" for an arbitrary JSON value, including null.
* No type checks are done.
* @property {any} default
* - The default value for this preference if missing, or if
* the value is invalid.
* - The developer is responsible for ensuring that this value is
* given, and that it meets the preconditions defined below.
* @property {string[]} [choices]
* - If the type is "strenum", then this must be an array of
* allowed options. If the value is not in this list, the default
* value will be returned.
* @property {number} [minimum]
* - If the type is "integer", this is the minimum allowed value.
* @property {number} [maximum]
* - If the type is "integer", this is the maximum allowed value.
* @property {number} [maximumLength]
* - If the type is "string", this is the maximum allowed length.
* @property {{[languageCode: string]: string}} [label]
* - The label to display on the preferences page for this
* preference. The language code should be a MediaWiki
* language code, e.g. "en" for English.
* @property {{[languageCode: string]: {[choice: string]: string}}} [choiceLabels]
* - The label to display on the preferences page for the choices
* of this preference (if it is an enum type). The language code
* should be a MediaWiki language code, e.g. "en" for English.
*/

var wiktGadgetPrefs__registeredPrefs = {};

var wiktGadgetPrefs__error = (Error ?
function (message) {
return new Error(message);
} :
function (message) {
return message;
});

var wiktGadgetPrefs__asciify = function (text) {
return text.replace(/[^A-Za-z0-9-]/g, function (match) {
if (match == "_") {
return "__";
} else {
return "_" + match.charCodeAt(0).toString(16) + "_";
}
});
};

var wiktGadgetPrefs__namespace_to_key = function (namespace) {
return "wiktgadgetprefs-" + wiktGadgetPrefs__asciify(namespace);
};

var wiktGadgetPrefs__is_integer = function (num) {
return num == (num | 0);
};

var wiktGadgetPrefs__parse_one = function (value, preference, key) {
var defaultValue = preference["default"];
switch (preference.type) {
case "boolean":
// data type
if (typeof value != "boolean") return defaultValue;
return value;
case "integer":
// data type
if (typeof value != "number") return defaultValue;
// integer check
if (!wiktGadgetPrefs__is_integer(value)) return defaultValue;
// constraints
if ((preference.minimum != null && value < preference.minimum) ||
(preference.maximum != null && value > preference.maximum))
return defaultValue;
return value;
case "string":
// data type
if (typeof value != "string") return defaultValue;
// constraints
if (preference.maximumLength != null && value.length > preference.maximumLength)
return defaultValue;
return value;
case "strenum":
// data type
if (typeof value != "string") return defaultValue;
// constraints
if (preference.choices.indexOf(value) < 0)
return defaultValue;
return value;
case "object":
if (typeof value == "undefined") return defaultValue;
return value;
}

throw wiktGadgetPrefs__error("Invalid preference specification '" + key + "'");
};

var wiktGadgetPrefs__parse_all = function (values, preferences) {
var parsed = {};
if (!values) values = {};

for (var key in preferences) {
if (preferences.hasOwnProperty(key)) {
parsed[key] = wiktGadgetPrefs__parse_one(values[key], preferences[key], key);
}
}
return parsed;
};

var wiktGadgetPrefs__resolve = function (namespaceKey, preferences) {
var resolved;
var mwOptions;
try {
mwOptions = mw.user.options;
} catch (e) {
}

if (!resolved && window.localStorage && window.localStorage.getItem("anon" + namespaceKey) != null) {
try {
resolved = JSON.parse(window.localStorage.getItem("anon" + namespaceKey));
} catch (e) { }
}

if (!resolved && mwOptions && mwOptions.exists("userjs-" + namespaceKey)) {
try {
resolved = JSON.parse(mwOptions.get("userjs-" + namespaceKey));
} catch (e) { }
}

return wiktGadgetPrefs__parse_all(resolved || {}, preferences);
};

/**
* Resolve preferences.
*
* Note that there is a maximum length imposed by MediaWiki
* on the total size of the preferences for each namespace.
*
* @param {string} namespace
* - An arbitrary string. This should be unique to each gadget.
* @param {WiktGadgetOptions} options
* - Options.
* @param {{[key: string]: WiktGadgetPreference}} preferences
* - Requested preferences, indexed by name.
* @returns {{[key: string]: any}}
*/
var wiktGadgetPrefs_get = function (namespace, options, preferences) {
if (wiktGadgetPrefs__registeredPrefs[namespace]) {
throw wiktGadgetPrefs__error("wiktGadgetPrefs_get has already been called with the namespace '" + namespace + "'.");
}
wiktGadgetPrefs__registeredPrefs[namespace] = {
options: options,
preferences: preferences
};

var namespaceKey = wiktGadgetPrefs__namespace_to_key(namespace);
if (namespaceKey.length >= 240) {
throw wiktGadgetPrefs__error("Namespace key '" + namespace + "' is too long. " +
"Please prefer ASCII characters A-Z, a-z, 0-9 and the hyphen, " +
"as other characters need to be converted, which increases their size.");
}

return wiktGadgetPrefs__resolve(namespaceKey, preferences);
};

mw.wiktGadgetPrefs = {};
mw.wiktGadgetPrefs.get = wiktGadgetPrefs_get;

// Only to be used by the preferences page.
mw.wiktGadgetPrefs._namespaceToKey = wiktGadgetPrefs__namespace_to_key;
mw.wiktGadgetPrefs._resolve = wiktGadgetPrefs__resolve;
mw.wiktGadgetPrefs._registeredPrefs = wiktGadgetPrefs__registeredPrefs;
})();

// </nowiki>

MediaWiki:Gadget-WiktGadgetPrefs.js - Revision history

Sware: 1 revision imported

wikt>Ioaxxere: docs should encourage good style