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.postWithToken( 'watch',
  29                         $.extend(
  30                                 {
  31                                         action: 'watch',
  32                                         titles: $.isArray( pages ) ? pages.join( '|' ) : String( pages ),
  33                                         uselang: mw.config.get( 'wgUserLanguage' )
  34                                 },
  35                                 addParams
  36                         )
  37                 );
  38
  39                 // Backwards compatibility (< MW 1.20)
  40                 if ( ok || err ) {
  41                         mw.track( 'mw.deprecate', 'api.cbParam' );
  42                         mw.log.warn( 'Use of mediawiki.api callback params is deprecated. Use the Promise instead.' );
  43                 }
  44
  45                 return apiPromise
  46                         .then( function ( data ) {
  47                                 // If a single page was given (not an array) respond with a single item as well.
  48                                 return $.isArray( pages ) ? data.watch : data.watch[0];
  49                         } )
  50                         .done( ok )
  51                         .fail( err )
  52                         .promise( { abort: apiPromise.abort } );
  53         }
  54
  55         $.extend( mw.Api.prototype, {
  56                 /**
  57                  * Convenience method for `action=watch`.
  58                  *
  59                  * @inheritdoc #doWatchInternal
  60                  */
  61                 watch: function ( pages, ok, err ) {
  62                         return doWatchInternal.call( this, pages, ok, err );
  63                 },
  64                 /**
  65                  * Convenience method for `action=watch&unwatch=1`.
  66                  *
  67                  * @inheritdoc #doWatchInternal
  68                  */
  69                 unwatch: function ( pages, ok, err ) {
  70                         return doWatchInternal.call( this, pages, ok, err, { unwatch: 1 } );
  71                 }
  72         } );
  73
  74         /**
  75          * @class mw.Api
  76          * @mixins mw.Api.plugin.watch
  77          */
  78
  79 }( mediaWiki, jQuery ) );