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 an
  12          *  array thereof. If an array is passed, the return value passed to the promise will also be an
  13          *  array of appropriate objects.
  14          * @param {Function} [ok] Success callback (deprecated)
  15          * @param {Function} [err] Error callback (deprecated)
  16          * @return {jQuery.Promise}
  17          * @return {Function} return.done
  18          * @return {Object|Object[]} return.done.watch
  19          * @return {string} return.done.watch.title Full pagename
  20          * @return {boolean} return.done.watch.watched
  21          * @return {string} return.done.watch.message Parsed HTML of the confirmational interface message
  22          */
  23         function doWatchInternal( page, ok, err, addParams ) {
  24                 // XXX: Parameter addParams is undocumented because we inherit this
  25                 // documentation in the public method..
  26                 var params, apiPromise,
  27                         d = $.Deferred();
  28
  29                 // Backwards compatibility (< MW 1.20)
  30                 if ( ok || err ) {
  31                         mw.track( 'mw.deprecate', 'api.cbParam' );
  32                         mw.log.warn( 'Use of mediawiki.api callback params is deprecated. Use the Promise instead.' );
  33                         d.done( ok ).fail( err );
  34                 }
  35
  36                 params = {
  37                         action: 'watch',
  38                         token: mw.user.tokens.get( 'watchToken' ),
  39                         uselang: mw.config.get( 'wgUserLanguage' )
  40                 };
  41
  42                 if ( $.isArray( page ) ) {
  43                         params.titles = page.join( '|' );
  44                 } else {
  45                         // The 'title' parameter is deprecated, keeping this for compatibility instead of
  46                         // converting to array because the API response changes from object to array of objects
  47                         // as well (bug 62422).
  48                         params.title = String( page );
  49                 }
  50
  51                 if ( addParams ) {
  52                         $.extend( params, addParams );
  53                 }
  54
  55                 apiPromise = this.post( params )
  56                         .done( function ( data ) {
  57                                 d.resolve( data.watch );
  58                         } )
  59                         .fail( d.reject );
  60
  61                 return d.promise( { abort: apiPromise.abort } );
  62         }
  63
  64         $.extend( mw.Api.prototype, {
  65                 /**
  66                  * Convenience method for `action=watch`.
  67                  *
  68                  * @inheritdoc #doWatchInternal
  69                  */
  70                 watch: function ( page, ok, err ) {
  71                         return doWatchInternal.call( this, page, ok, err );
  72                 },
  73                 /**
  74                  * Convenience method for `action=watch&unwatch=1`.
  75                  *
  76                  * @inheritdoc #doWatchInternal
  77                  */
  78                 unwatch: function ( page, ok, err ) {
  79                         return doWatchInternal.call( this, page, ok, err, { unwatch: 1 } );
  80                 }
  81
  82         } );
  83
  84         /**
  85          * @class mw.Api
  86          * @mixins mw.Api.plugin.watch
  87          */
  88
  89 }( mediaWiki, jQuery ) );