diff options
Diffstat (limited to 'resources/mediawiki.api')
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.category.js | 174 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.edit.js | 85 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.js | 73 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.parse.js | 39 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.titleblacklist.js | 52 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.watch.js | 68 |
6 files changed, 243 insertions, 248 deletions
diff --git a/resources/mediawiki.api/mediawiki.api.category.js b/resources/mediawiki.api/mediawiki.api.category.js index cc6f704f..4de52911 100644 --- a/resources/mediawiki.api/mediawiki.api.category.js +++ b/resources/mediawiki.api/mediawiki.api.category.js @@ -1,104 +1,130 @@ /** - * Additional mw.Api methods to assist with API calls related to categories. + * @class mw.Api.plugin.category */ ( function ( mw, $ ) { $.extend( mw.Api.prototype, { /** * Determine if a category exists. - * @param title {mw.Title} - * @param success {Function} callback to pass boolean of category's existence - * @param err {Function} optional callback to run if api error - * @return ajax call object + * @param {mw.Title} title + * @param {Function} [ok] Success callback (deprecated) + * @param {Function} [err] Error callback (deprecated) + * @return {jQuery.Promise} + * @return {Function} return.done + * @return {boolean} return.done.isCategory Whether the category exists. */ - isCategory: function ( title, success, err ) { - var params, ok; - params = { - prop: 'categoryinfo', - titles: title.toString() - }; - ok = function ( data ) { - var exists = false; - if ( data.query && data.query.pages ) { - $.each( data.query.pages, function ( id, page ) { - if ( page.categoryinfo ) { - exists = true; - } - } ); - } - success( exists ); - }; + isCategory: function ( title, ok, err ) { + var d = $.Deferred(); + // Backwards compatibility (< MW 1.20) + d.done( ok ); + d.fail( err ); - return this.get( params, { ok: ok, err: err } ); + this.get( { + prop: 'categoryinfo', + titles: title.toString() + } ) + .done( function ( data ) { + var exists = false; + if ( data.query && data.query.pages ) { + $.each( data.query.pages, function ( id, page ) { + if ( page.categoryinfo ) { + exists = true; + } + } ); + } + d.resolve( exists ); + }) + .fail( d.reject ); + + return d.promise(); }, /** * Get a list of categories that match a certain prefix. * e.g. given "Foo", return "Food", "Foolish people", "Foosball tables" ... - * @param prefix {String} prefix to match - * @param success {Function} callback to pass matched categories to - * @param err {Function} optional callback to run if api error - * @return {jqXHR} + * @param {string} prefix Prefix to match. + * @param {Function} [ok] Success callback (deprecated) + * @param {Function} [err] Error callback (deprecated) + * @return {jQuery.Promise} + * @return {Function} return.done + * @return {String[]} return.done.categories Matched categories */ - getCategoriesByPrefix: function ( prefix, success, err ) { + getCategoriesByPrefix: function ( prefix, ok, err ) { + var d = $.Deferred(); + // Backwards compatibility (< MW 1.20) + d.done( ok ); + d.fail( err ); + // Fetch with allpages to only get categories that have a corresponding description page. - var params, ok; - params = { - 'list': 'allpages', - 'apprefix': prefix, - 'apnamespace': mw.config.get('wgNamespaceIds').category - }; - ok = function ( data ) { - var texts = []; - if ( data.query && data.query.allpages ) { - $.each( data.query.allpages, function ( i, category ) { - texts.push( new mw.Title( category.title ).getNameText() ); - } ); - } - success( texts ); - }; + this.get( { + list: 'allpages', + apprefix: prefix, + apnamespace: mw.config.get('wgNamespaceIds').category + } ) + .done( function ( data ) { + var texts = []; + if ( data.query && data.query.allpages ) { + $.each( data.query.allpages, function ( i, category ) { + texts.push( new mw.Title( category.title ).getNameText() ); + } ); + } + d.resolve( texts ); + }) + .fail( d.reject ); - return this.get( params, { ok: ok, err: err } ); + return d.promise(); }, /** * Get the categories that a particular page on the wiki belongs to - * @param title {mw.Title} - * @param success {Function} callback to pass categories to (or false, if title not found) - * @param err {Function} optional callback to run if api error - * @param async {Boolean} optional asynchronousness (default = true = async) - * @return {jqXHR} + * @param {mw.Title} title + * @param {Function} [ok] Success callback (deprecated) + * @param {Function} [err] Error callback (deprecated) + * @param {boolean} [async=true] Asynchronousness + * @return {jQuery.Promise} + * @return {Function} return.done + * @return {boolean|mw.Title[]} return.done.categories List of category titles or false + * if title was not found. */ - getCategories: function ( title, success, err, async ) { - var params, ok; - params = { - prop: 'categories', - titles: title.toString() - }; - if ( async === undefined ) { - async = true; - } - ok = function ( data ) { - var ret = false; - if ( data.query && data.query.pages ) { - $.each( data.query.pages, function ( id, page ) { - if ( page.categories ) { - if ( typeof ret !== 'object' ) { - ret = []; + getCategories: function ( title, ok, err, async ) { + var d = $.Deferred(); + // Backwards compatibility (< MW 1.20) + d.done( ok ); + d.fail( err ); + + this.get( { + prop: 'categories', + titles: title.toString() + }, { + async: async === undefined ? true : async + } ) + .done( function ( data ) { + var ret = false; + if ( data.query && data.query.pages ) { + $.each( data.query.pages, function ( id, page ) { + if ( page.categories ) { + if ( typeof ret !== 'object' ) { + ret = []; + } + $.each( page.categories, function ( i, cat ) { + ret.push( new mw.Title( cat.title ) ); + } ); } - $.each( page.categories, function ( i, cat ) { - ret.push( new mw.Title( cat.title ) ); - } ); - } - } ); - } - success( ret ); - }; + } ); + } + d.resolve( ret ); + }) + .fail( d.reject ); - return this.get( params, { ok: ok, err: err, async: async } ); + return d.promise(); } } ); + /** + * @class mw.Api + * @mixins mw.Api.plugin.category + */ + }( mediaWiki, jQuery ) ); diff --git a/resources/mediawiki.api/mediawiki.api.edit.js b/resources/mediawiki.api/mediawiki.api.edit.js index 49af9375..3c775ad0 100644 --- a/resources/mediawiki.api/mediawiki.api.edit.js +++ b/resources/mediawiki.api/mediawiki.api.edit.js @@ -1,5 +1,5 @@ /** - * Additional mw.Api methods to assist with API calls related to editing wiki pages. + * @class mw.Api.plugin.edit */ ( function ( mw, $ ) { @@ -13,10 +13,10 @@ * If we have a cached token try using that, and if it fails, blank out the * cached token and start over. * - * @param params {Object} API parameters - * @param ok {Function} callback for success - * @param err {Function} [optional] error callback - * @return {jqXHR} + * @param {Object} params API parameters + * @param {Function} [ok] Success callback (deprecated) + * @param {Function} [err] Error callback (deprecated) + * @return {jQuery.Promise} See #post */ postWithEditToken: function ( params, ok, err ) { var useTokenToPost, getTokenIfBad, @@ -48,67 +48,74 @@ }, /** - * Api helper to grab an edit token + * Api helper to grab an edit token. * - * token callback has signature ( String token ) - * error callback has signature ( String code, Object results, XmlHttpRequest xhr, Exception exception ) - * Note that xhr and exception are only available for 'http_*' errors - * code may be any http_* error code (see mw.Api), or 'token_missing' - * - * @param tokenCallback {Function} received token callback - * @param err {Function} error callback - * @return {jqXHR} + * @param {Function} [ok] Success callback + * @param {Function} [err] Error callback + * @return {jQuery.Promise} + * @return {Function} return.done + * @return {string} return.done.token Received token. */ - getEditToken: function ( tokenCallback, err ) { - var parameters = { + getEditToken: function ( ok, err ) { + var d = $.Deferred(); + // Backwards compatibility (< MW 1.20) + d.done( ok ); + d.fail( err ); + + this.get( { action: 'tokens', type: 'edit' - }, - ok = function ( data ) { + }, { + // Due to the API assuming we're logged out if we pass the callback-parameter, + // we have to disable jQuery's callback system, and instead parse JSON string, + // by setting 'jsonp' to false. + // TODO: This concern seems genuine but no other module has it. Is it still + // needed and/or should we pass this by default? + jsonp: false + } ) + .done( function ( data ) { var token; // If token type is not available for this user, // key 'edittoken' is missing or can contain Boolean false if ( data.tokens && data.tokens.edittoken ) { token = data.tokens.edittoken; cachedToken = token; - tokenCallback( token ); + d.resolve( token ); } else { - err( 'token-missing', data ); + d.reject( 'token-missing', data ); } - }, - ajaxOptions = { - ok: ok, - err: err, - // Due to the API assuming we're logged out if we pass the callback-parameter, - // we have to disable jQuery's callback system, and instead parse JSON string, - // by setting 'jsonp' to false. - jsonp: false - }; + }) + .fail( d.reject ); - return this.get( parameters, ajaxOptions ); + return d.promise(); }, /** * Create a new section of the page. - * @param title {mw.Title|String} target page - * @param header {String} - * @param message {String} wikitext message - * @param ok {Function} success handler - * @param err {Function} error handler - * @return {jqXHR} + * @see #postWithEditToken + * @param {mw.Title|String} title Target page + * @param {string} header + * @param {string} message wikitext message + * @param {Function} [ok] Success handler + * @param {Function} [err] Error handler + * @return {jQuery.Promise} */ newSection: function ( title, header, message, ok, err ) { - var params = { + return this.postWithEditToken( { action: 'edit', section: 'new', format: 'json', title: title.toString(), summary: header, text: message - }; - return this.postWithEditToken( params, ok, err ); + }, ok, err ); } } ); + /** + * @class mw.Api + * @mixins mw.Api.plugin.edit + */ + }( mediaWiki, jQuery ) ); diff --git a/resources/mediawiki.api/mediawiki.api.js b/resources/mediawiki.api/mediawiki.api.js index a184e3ca..cf7443f3 100644 --- a/resources/mediawiki.api/mediawiki.api.js +++ b/resources/mediawiki.api/mediawiki.api.js @@ -1,15 +1,9 @@ -/** - * mw.Api objects represent the API of a particular MediaWiki server. - */ ( function ( mw, $ ) { - /** - * @var defaultOptions {Object} - * We allow people to omit these default parameters from API requests - * there is very customizable error handling here, on a per-call basis - * wondering, would it be simpler to make it easy to clone the api object, - * change error handling, and use that instead? - */ + // We allow people to omit these default parameters from API requests + // there is very customizable error handling here, on a per-call basis + // wondering, would it be simpler to make it easy to clone the api object, + // change error handling, and use that instead? var defaultOptions = { // Query parameters for API requests @@ -30,22 +24,23 @@ /** * Constructor to create an object to interact with the API of a particular MediaWiki server. + * mw.Api objects represent the API of a particular MediaWiki server. + * + * TODO: Share API objects with exact same config. * - * @todo Share API objects with exact same config. - * @example - * <code> - * var api = new mw.Api(); - * api.get( { - * action: 'query', - * meta: 'userinfo' - * }, { - * ok: function () { console.log( arguments ); } - * } ); - * </code> + * var api = new mw.Api(); + * api.get( { + * action: 'query', + * meta: 'userinfo' + * } ).done ( function ( data ) { + * console.log( data ); + * } ); + * + * @class * * @constructor - * @param options {Object} See defaultOptions documentation above. Ajax options can also be - * overridden for each individual request to jQuery.ajax() later on. + * @param {Object} options See defaultOptions documentation above. Ajax options can also be + * overridden for each individual request to {@link jQuery#ajax} later on. */ mw.Api = function ( options ) { @@ -69,13 +64,12 @@ /** * Normalize the ajax options for compatibility and/or convenience methods. * - * @param {undefined|Object|Function} An object contaning one or more of options.ajax, - * or just a success function (options.ajax.ok). + * @param {Object} [arg] An object contaning one or more of options.ajax. * @return {Object} Normalized ajax options. */ normalizeAjaxOptions: function ( arg ) { // Arg argument is usually empty - // (before MW 1.20 it was often used to pass ok/err callbacks) + // (before MW 1.20 it was used to pass ok callbacks) var opts = arg || {}; // Options can also be a success callback handler if ( typeof arg === 'function' ) { @@ -87,8 +81,8 @@ /** * Perform API get request * - * @param {Object} request parameters - * @param {Object|Function} [optional] ajax options + * @param {Object} parameters + * @param {Object|Function} [ajaxOptions] * @return {jQuery.Promise} */ get: function ( parameters, ajaxOptions ) { @@ -99,10 +93,11 @@ /** * Perform API post request - * @todo Post actions for nonlocal will need proxy * - * @param {Object} request parameters - * @param {Object|Function} [optional] ajax options + * TODO: Post actions for non-local hostnames will need proxy. + * + * @param {Object} parameters + * @param {Object|Function} [ajaxOptions] * @return {jQuery.Promise} */ post: function ( parameters, ajaxOptions ) { @@ -114,11 +109,9 @@ /** * Perform the API call. * - * @param {Object} request parameters - * @param {Object} ajax options - * @return {jQuery.Promise} - * - done: API response data as first argument - * - fail: errorcode as first arg, details (string or object) as second arg. + * @param {Object} parameters + * @param {Object} [ajaxOptions] + * @return {jQuery.Promise} Done: API response data. Fail: Error code */ ajax: function ( parameters, ajaxOptions ) { var token, @@ -187,7 +180,9 @@ }; /** - * @var {Array} List of errors we might receive from the API. + * @static + * @property {Array} + * List of errors we might receive from the API. * For now, this just documents our expectation that there should be similar messages * available. */ @@ -237,7 +232,9 @@ ]; /** - * @var {Array} List of warnings we might receive from the API. + * @static + * @property {Array} + * List of warnings we might receive from the API. * For now, this just documents our expectation that there should be similar messages * available. */ diff --git a/resources/mediawiki.api/mediawiki.api.parse.js b/resources/mediawiki.api/mediawiki.api.parse.js index e8d1b3e6..ea0388c1 100644 --- a/resources/mediawiki.api/mediawiki.api.parse.js +++ b/resources/mediawiki.api/mediawiki.api.parse.js @@ -1,42 +1,43 @@ /** - * mw.Api methods for parsing wikitext. + * @class mw.Api.plugin.parse */ ( function ( mw, $ ) { $.extend( mw.Api.prototype, { /** - * Convinience method for 'action=parse'. Parses wikitext into HTML. + * Convinience method for 'action=parse'. * - * @param wikiText {String} - * @param ok {Function} [optional] deprecated (success callback) - * @param err {Function} [optional] deprecated (error callback) + * @param {string} wikitext + * @param {Function} [ok] Success callback (deprecated) + * @param {Function} [err] Error callback (deprecated) * @return {jQuery.Promise} + * @return {Function} return.done + * @return {string} return.done.data Parsed HTML of `wikitext`. */ - parse: function ( wikiText, ok, err ) { - var apiDeferred = $.Deferred(); - + parse: function ( wikitext, ok, err ) { + var d = $.Deferred(); // Backwards compatibility (< MW 1.20) - if ( ok ) { - apiDeferred.done( ok ); - } - if ( err ) { - apiDeferred.fail( err ); - } + d.done( ok ); + d.fail( err ); this.get( { action: 'parse', - text: wikiText + text: wikitext } ) .done( function ( data ) { if ( data.parse && data.parse.text && data.parse.text['*'] ) { - apiDeferred.resolve( data.parse.text['*'] ); + d.resolve( data.parse.text['*'] ); } } ) - .fail( apiDeferred.reject ); + .fail( d.reject ); - // Return the promise - return apiDeferred.promise(); + return d.promise(); } } ); + /** + * @class mw.Api + * @mixins mw.Api.plugin.parse + */ + }( mediaWiki, jQuery ) ); diff --git a/resources/mediawiki.api/mediawiki.api.titleblacklist.js b/resources/mediawiki.api/mediawiki.api.titleblacklist.js deleted file mode 100644 index 1f7e275a..00000000 --- a/resources/mediawiki.api/mediawiki.api.titleblacklist.js +++ /dev/null @@ -1,52 +0,0 @@ -/** - * Additional mw.Api methods to assist with API calls to the API module of the TitleBlacklist extension. - */ - -( function ( mw, $ ) { - - $.extend( mw.Api.prototype, { - /** - * Convinience method for 'action=titleblacklist'. - * Note: This action is not provided by MediaWiki core, but as part of the TitleBlacklist extension. - * - * @param title {mw.Title} - * @param success {Function} Called on successfull request. First argument is false if title wasn't blacklisted, - * object with 'reason', 'line' and 'message' properties if title was blacklisted. - * @param err {Function} optional callback to run if api error - * @return {jqXHR} - */ - isBlacklisted: function ( title, success, err ) { - var params = { - action: 'titleblacklist', - tbaction: 'create', - tbtitle: title.toString() - }, - ok = function ( data ) { - var result; - - // this fails open (if nothing valid is returned by the api, allows the title) - // also fails open when the API is not present, which will be most of the time - // as this API module is part of the TitleBlacklist extension. - if ( data.titleblacklist && data.titleblacklist.result && data.titleblacklist.result === 'blacklisted') { - if ( data.titleblacklist.reason ) { - result = { - reason: data.titleblacklist.reason, - line: data.titleblacklist.line, - message: data.titleblacklist.message - }; - } else { - mw.log('mw.Api.titleblacklist::isBlacklisted> no reason data for blacklisted title', 'debug'); - result = { reason: 'Blacklisted, but no reason supplied', line: 'Unknown', message: null }; - } - success( result ); - } else { - success ( false ); - } - }; - - return this.get( params, { ok: ok, err: err } ); - } - - } ); - -}( mediaWiki, jQuery ) ); diff --git a/resources/mediawiki.api/mediawiki.api.watch.js b/resources/mediawiki.api/mediawiki.api.watch.js index d3234421..c86a90a7 100644 --- a/resources/mediawiki.api/mediawiki.api.watch.js +++ b/resources/mediawiki.api/mediawiki.api.watch.js @@ -1,56 +1,72 @@ /** - * Additional mw.Api methods to assist with (un)watching wiki pages. + * @class mw.Api.plugin.watch * @since 1.19 */ ( function ( mw, $ ) { /** - * @context {mw.Api} + * @private + * @context mw.Api + * + * @param {String|mw.Title} page Full page name or instance of mw.Title + * @param {Function} [ok] Success callback (deprecated) + * @param {Function} [err] Error callback (deprecated) + * @return {jQuery.Promise} + * @return {Function} return.done + * @return {Object} return.done.watch + * @return {string} return.done.watch.title Full pagename + * @return {boolean} return.done.watch.watched + * @return {string} return.done.watch.message Parsed HTML of the confirmational interface message */ - function doWatchInternal( page, success, err, addParams ) { - var params = { + function doWatchInternal( page, ok, err, addParams ) { + var params, d = $.Deferred(); + // Backwards compatibility (< MW 1.20) + d.done( ok ); + d.fail( err ); + + params = { action: 'watch', title: String( page ), token: mw.user.tokens.get( 'watchToken' ), uselang: mw.config.get( 'wgUserLanguage' ) }; - function ok( data ) { - success( data.watch ); - } + if ( addParams ) { $.extend( params, addParams ); } - return this.post( params, { ok: ok, err: err } ); + + this.post( params ) + .done( function ( data ) { + d.resolve( data.watch ); + } ) + .fail( d.reject ); + + return d.promise(); } $.extend( mw.Api.prototype, { /** - * Convinience method for 'action=watch'. + * Convenience method for `action=watch`. * - * @param page {String|mw.Title} Full page name or instance of mw.Title - * @param success {Function} Callback to which the watch object will be passed. - * Watch object contains properties 'title' (full pagename), 'watched' (boolean) and - * 'message' (parsed HTML of the 'addedwatchtext' message). - * @param err {Function} Error callback (optional) - * @return {jqXHR} + * @inheritdoc #doWatchInternal */ - watch: function ( page, success, err ) { - return doWatchInternal.call( this, page, success, err ); + watch: function ( page, ok, err ) { + return doWatchInternal.call( this, page, ok, err ); }, /** - * Convinience method for 'action=watch&unwatch=1'. + * Convenience method for `action=watch&unwatch=1`. * - * @param page {String|mw.Title} Full page name or instance of mw.Title - * @param success {Function} Callback to which the watch object will be passed. - * Watch object contains properties 'title' (full pagename), 'watched' (boolean) and - * 'message' (parsed HTML of the 'removedwatchtext' message). - * @param err {Function} Error callback (optional) - * @return {jqXHR} + * @inheritdoc #doWatchInternal */ - unwatch: function ( page, success, err ) { - return doWatchInternal.call( this, page, success, err, { unwatch: 1 } ); + unwatch: function ( page, ok, err ) { + return doWatchInternal.call( this, page, ok, err, { unwatch: 1 } ); } } ); + /** + * @class mw.Api + * @mixins mw.Api.plugin.watch + */ + }( mediaWiki, jQuery ) ); |