Merge "Removing badge drop shadow per Vibha"

[lhc/web/wiklou.git] / resources / mediawiki.api / mediawiki.api.edit.js

diff --git a/resources/mediawiki.api/mediawiki.api.edit.js b/resources/mediawiki.api/mediawiki.api.edit.js
index 49af937..3c775ad 100644 (file)
--- 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 ) );