diff options
Diffstat (limited to 'resources/mediawiki.api')
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.category.js | 183 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.edit.js | 108 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.js | 161 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.login.js | 54 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.parse.js | 41 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.titleblacklist.js | 52 | ||||
| -rw-r--r-- | resources/mediawiki.api/mediawiki.api.watch.js | 70 |
7 files changed, 371 insertions, 298 deletions
diff --git a/resources/mediawiki.api/mediawiki.api.category.js b/resources/mediawiki.api/mediawiki.api.category.js index cc6f704f..98a9c54b 100644 --- a/resources/mediawiki.api/mediawiki.api.category.js +++ b/resources/mediawiki.api/mediawiki.api.category.js @@ -1,104 +1,133 @@ /** - * 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 ); - }; - - return this.get( params, { ok: ok, err: err } ); + isCategory: function ( title, ok, err ) { + var d = $.Deferred(), + apiPromise; + + // Backwards compatibility (< MW 1.20) + d.done( ok ).fail( err ); + + apiPromise = 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( { abort: apiPromise.abort } ); }, /** * 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(), + apiPromise; + + // Backwards compatibility (< MW 1.20) + d.done( ok ).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 ); - }; - - return this.get( params, { ok: ok, err: err } ); + apiPromise = 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 d.promise( { abort: apiPromise.abort } ); }, /** * 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(), + apiPromise; + + // Backwards compatibility (< MW 1.20) + d.done( ok ).fail( err ); + + apiPromise = 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 ); - }; - - return this.get( params, { ok: ok, err: err, async: async } ); + } ); + } + d.resolve( ret ); + } ) + .fail( d.reject ); + + return d.promise( { abort: apiPromise.abort } ); } } ); + /** + * @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..cc83a4b8 100644 --- a/resources/mediawiki.api/mediawiki.api.edit.js +++ b/resources/mediawiki.api/mediawiki.api.edit.js @@ -1,11 +1,8 @@ /** - * Additional mw.Api methods to assist with API calls related to editing wiki pages. + * @class mw.Api.plugin.edit */ ( function ( mw, $ ) { - // Cache token so we don't have to keep fetching new ones for every single request. - var cachedToken = null; - $.extend( mw.Api.prototype, { /** @@ -13,102 +10,53 @@ * 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, - api = this; - if ( cachedToken === null ) { - // We don't have a valid cached token, so get a fresh one and try posting. - // We do not trap any 'badtoken' or 'notoken' errors, because we don't want - // an infinite loop. If this fresh token is bad, something else is very wrong. - useTokenToPost = function ( token ) { - params.token = token; - api.post( params, ok, err ); - }; - return api.getEditToken( useTokenToPost, err ); - } else { - // We do have a token, but it might be expired. So if it is 'bad' then - // start over with a new token. - params.token = cachedToken; - getTokenIfBad = function ( code, result ) { - if ( code === 'badtoken' ) { - // force a new token, clear any old one - cachedToken = null; - api.postWithEditToken( params, ok, err ); - } else { - err( code, result ); - } - }; - return api.post( params, { ok : ok, err : getTokenIfBad }); - } + return this.postWithToken( 'edit', params ).done( ok ).fail( err ); }, /** - * 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' + * Api helper to grab an edit token. * - * @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 = { - action: 'tokens', - type: 'edit' - }, - ok = 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 ); - } else { - err( '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 - }; - - return this.get( parameters, ajaxOptions ); + getEditToken: function ( ok, err ) { + return this.getToken( 'edit' ).done( ok ).fail( err ); }, /** * 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..cdc67679 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 @@ -26,26 +20,28 @@ dataType: 'json' } - }; + }, + tokenCache = {}; /** * 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 +65,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 +82,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 +94,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,15 +110,14 @@ /** * 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, - apiDeferred = $.Deferred(); + apiDeferred = $.Deferred(), + xhr; parameters = $.extend( {}, this.defaults.parameters, parameters ); ajaxOptions = $.extend( {}, this.defaults.ajax, ajaxOptions ); @@ -154,7 +149,7 @@ } // Make the AJAX request - $.ajax( ajaxOptions ) + xhr = $.ajax( ajaxOptions ) // If AJAX fails, reject API call with error code 'http' // and details in second argument. .fail( function ( xhr, textStatus, exception ) { @@ -179,15 +174,91 @@ } ); // Return the Promise - return apiDeferred.promise().fail( function ( code, details ) { + return apiDeferred.promise( { abort: xhr.abort } ).fail( function ( code, details ) { mw.log( 'mw.Api error: ', code, details ); - }); - } + } ); + }, + /** + * Post to API with specified type of token. If we have no token, get one and try to post. + * If we have a cached token try using that, and if it fails, blank out the + * cached token and start over. For example to change an user option you could do: + * + * new mw.Api().postWithToken( 'options', { + * action: 'options', + * optionname: 'gender', + * optionvalue: 'female' + * } ); + * + * @param {string} tokenType The name of the token, like options or edit. + * @param {Object} params API parameters + * @return {jQuery.Promise} See #post + */ + postWithToken: function ( tokenType, params ) { + var api = this, hasOwn = tokenCache.hasOwnProperty; + if ( hasOwn.call( tokenCache, tokenType ) && tokenCache[tokenType] !== undefined ) { + params.token = tokenCache[tokenType]; + return api.post( params ).then( + null, + function ( code ) { + if ( code === 'badtoken' ) { + // force a new token, clear any old one + tokenCache[tokenType] = params.token = undefined; + return api.post( params ); + } + // Pass the promise forward, so the caller gets error codes + return this; + } + ); + } else { + return api.getToken( tokenType ).then( function ( token ) { + tokenCache[tokenType] = params.token = token; + return api.post( params ); + } ); + } + }, + + /** + * Api helper to grab any token. + * + * @param {string} type Token type. + * @return {jQuery.Promise} + * @return {Function} return.done + * @return {string} return.done.token Received token. + */ + getToken: function ( type ) { + var apiPromise, + d = $.Deferred(); + + apiPromise = this.get( { + action: 'tokens', + type: type + }, { + // 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? + } ) + .done( function ( data ) { + // If token type is not available for this user, + // key '...token' is missing or can contain Boolean false + if ( data.tokens && data.tokens[type + 'token'] ) { + d.resolve( data.tokens[type + 'token'] ); + } else { + d.reject( 'token-missing', data ); + } + } ) + .fail( d.reject ); + + return d.promise( { abort: apiPromise.abort } ); + } }; /** - * @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 +308,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.login.js b/resources/mediawiki.api/mediawiki.api.login.js new file mode 100644 index 00000000..ccbae06c --- /dev/null +++ b/resources/mediawiki.api/mediawiki.api.login.js @@ -0,0 +1,54 @@ +/** + * Make the two-step login easier. + * @author Niklas Laxström + * @class mw.Api.plugin.login + * @since 1.22 + */ +( function ( mw, $ ) { + 'use strict'; + + $.extend( mw.Api.prototype, { + /** + * @param {string} username + * @param {string} password + * @return {jQuery.Promise} See mw.Api#post + */ + login: function ( username, password ) { + var params, request, + deferred = $.Deferred(), + api = this; + + params = { + action: 'login', + lgname: username, + lgpassword: password + }; + + request = api.post( params ); + request.fail( deferred.reject ); + request.done( function ( data ) { + params.lgtoken = data.login.token; + api.post( params ) + .fail( deferred.reject ) + .done( function ( data ) { + var code; + if ( data.login && data.login.result === 'Success' ) { + deferred.resolve( data ); + } else { + // Set proper error code whenever possible + code = data.error && data.error.code || 'unknown'; + deferred.reject( code, data ); + } + } ); + } ); + + return deferred.promise( { abort: request.abort } ); + } + } ); + + /** + * @class mw.Api + * @mixins mw.Api.plugin.login + */ + +}( mediaWiki, jQuery ) ); diff --git a/resources/mediawiki.api/mediawiki.api.parse.js b/resources/mediawiki.api/mediawiki.api.parse.js index e8d1b3e6..c4d23b82 100644 --- a/resources/mediawiki.api/mediawiki.api.parse.js +++ b/resources/mediawiki.api/mediawiki.api.parse.js @@ -1,42 +1,45 @@ /** - * 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(), + apiPromise; // Backwards compatibility (< MW 1.20) - if ( ok ) { - apiDeferred.done( ok ); - } - if ( err ) { - apiDeferred.fail( err ); - } + d.done( ok ).fail( err ); - this.get( { + apiPromise = this.get( { action: 'parse', - text: wikiText + contentmodel: '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( { abort: apiPromise.abort } ); } } ); + /** + * @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..49a4c622 100644 --- a/resources/mediawiki.api/mediawiki.api.watch.js +++ b/resources/mediawiki.api/mediawiki.api.watch.js @@ -1,56 +1,74 @@ /** - * 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(), + apiPromise; + + // Backwards compatibility (< MW 1.20) + d.done( ok ).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 } ); + + apiPromise = this.post( params ) + .done( function ( data ) { + d.resolve( data.watch ); + } ) + .fail( d.reject ); + + return d.promise( { abort: apiPromise.abort } ); } $.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 ) ); |