resources/mediawiki.api/mediawiki.api.watch.js

   1 /**
   2  * @class mw.Api.plugin.watch
   3  * @since 1.19
   4  */
   5 ( function ( mw, $ ) {
   6
   7         /**
   8          * @private
   9          * @context mw.Api
  10          *
  11          * @param {string|mw.Title|string[]|mw.Title[]} page Full page name or instance of mw.Title or array of pages
  12          * @param {Function} [ok] Success callback (deprecated)
  13          * @param {Function} [err] Error callback (deprecated)
  14          * @return {jQuery.Promise}
  15          * @return {Function} return.done
  16          * @return {Object} return.done.watch
  17          * @return {string} return.done.watch.title Full pagename
  18          * @return {boolean} return.done.watch.watched
  19          * @return {string} return.done.watch.message Parsed HTML of the confirmational interface message
  20          */
  21         function doWatchInternal( page, ok, err, addParams ) {
  22                 // XXX: Parameter addParams is undocumented because we inherit this
  23                 // documentation in the public method..
  24                 var params, apiPromise,
  25                         d = $.Deferred();
  26
  27                 // Backwards compatibility (< MW 1.20)
  28                 if ( ok || err ) {
  29                         mw.track( 'mw.deprecate', 'api.cbParam' );
  30                         mw.log.warn( 'Use of mediawiki.api callback params is deprecated. Use the Promise instead.' );
  31                         d.done( ok ).fail( err );
  32                 }
  33
  34                 params = {
  35                         action: 'watch',
  36                         titles: $.isArray( page ) ? page.join( '|' ) : String( page ),
  37                         token: mw.user.tokens.get( 'watchToken' ),
  38                         uselang: mw.config.get( 'wgUserLanguage' )
  39                 };
  40
  41                 if ( addParams ) {
  42                         $.extend( params, addParams );
  43                 }
  44
  45                 apiPromise = this.post( params )
  46                         .done( function ( data ) {
  47                                 d.resolve( data.watch );
  48                         } )
  49                         .fail( d.reject );
  50
  51                 return d.promise( { abort: apiPromise.abort } );
  52         }
  53
  54         $.extend( mw.Api.prototype, {
  55                 /**
  56                  * Convenience method for `action=watch`.
  57                  *
  58                  * @inheritdoc #doWatchInternal
  59                  */
  60                 watch: function ( page, ok, err ) {
  61                         return doWatchInternal.call( this, page, ok, err );
  62                 },
  63                 /**
  64                  * Convenience method for `action=watch&unwatch=1`.
  65                  *
  66                  * @inheritdoc #doWatchInternal
  67                  */
  68                 unwatch: function ( page, ok, err ) {
  69                         return doWatchInternal.call( this, page, ok, err, { unwatch: 1 } );
  70                 }
  71
  72         } );
  73
  74         /**
  75          * @class mw.Api
  76          * @mixins mw.Api.plugin.watch
  77          */
  78
  79 }( mediaWiki, jQuery ) );