resources/src/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          * @static
  10          * @context mw.Api
  11          *
  12          * @param {string|mw.Title|string[]|mw.Title[]} pages Full page name or instance of mw.Title, or an
  13          *  array thereof. If an array is passed, the return value passed to the promise will also be an
  14          *  array of appropriate objects.
  15          * @param {Function} [ok] Success callback (deprecated)
  16          * @param {Function} [err] Error callback (deprecated)
  17          * @return {jQuery.Promise}
  18          * @return {Function} return.done
  19          * @return {Object|Object[]} return.done.watch Object or list of objects (depends on the `pages`
  20          *  parameter)
  21          * @return {string} return.done.watch.title Full pagename
  22          * @return {boolean} return.done.watch.watched Whether the page is now watched or unwatched
  23          * @return {string} return.done.watch.message Parsed HTML of the confirmational interface message
  24          */
  25         function doWatchInternal( pages, ok, err, addParams ) {
  26                 // XXX: Parameter addParams is undocumented because we inherit this
  27                 // documentation in the public method...
  28                 var apiPromise = this.post(
  29                         $.extend(
  30                                 {
  31                                         action: 'watch',
  32                                         titles: $.isArray( pages ) ? pages.join( '|' ) : String( pages ),
  33                                         token: mw.user.tokens.get( 'watchToken' ),
  34                                         uselang: mw.config.get( 'wgUserLanguage' )
  35                                 },
  36                                 addParams
  37                         )
  38                 );
  39
  40                 // Backwards compatibility (< MW 1.20)
  41                 if ( ok || err ) {
  42                         mw.track( 'mw.deprecate', 'api.cbParam' );
  43                         mw.log.warn( 'Use of mediawiki.api callback params is deprecated. Use the Promise instead.' );
  44                 }
  45
  46                 return apiPromise
  47                         .then( function ( data ) {
  48                                 // If a single page was given (not an array) respond with a single item as well.
  49                                 return $.isArray( pages ) ? data.watch : data.watch[0];
  50                         } )
  51                         .done( ok )
  52                         .fail( err )
  53                         .promise( { abort: apiPromise.abort } );
  54         }
  55
  56         $.extend( mw.Api.prototype, {
  57                 /**
  58                  * Convenience method for `action=watch`.
  59                  *
  60                  * @inheritdoc #doWatchInternal
  61                  */
  62                 watch: function ( pages, ok, err ) {
  63                         return doWatchInternal.call( this, pages, ok, err );
  64                 },
  65                 /**
  66                  * Convenience method for `action=watch&unwatch=1`.
  67                  *
  68                  * @inheritdoc #doWatchInternal
  69                  */
  70                 unwatch: function ( pages, ok, err ) {
  71                         return doWatchInternal.call( this, pages, ok, err, { unwatch: 1 } );
  72                 }
  73         } );
  74
  75         /**
  76          * @class mw.Api
  77          * @mixins mw.Api.plugin.watch
  78          */
  79
  80 }( mediaWiki, jQuery ) );