resources/src/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 {Object} [addParams]
  16          * @return {jQuery.Promise}
  17          * @return {Function} return.done
  18          * @return {Object|Object[]} return.done.watch Object or list of objects (depends on the `pages`
  19          *  parameter)
  20          * @return {string} return.done.watch.title Full pagename
  21          * @return {boolean} return.done.watch.watched Whether the page is now watched or unwatched
  22          * @return {string} return.done.watch.message Parsed HTML of the confirmational interface message
  23          */
  24         function doWatchInternal( pages, addParams ) {
  25                 // XXX: Parameter addParams is undocumented because we inherit this
  26                 // documentation in the public method...
  27                 var apiPromise = this.postWithToken( 'watch',
  28                         $.extend(
  29                                 {
  30                                         action: 'watch',
  31                                         titles: $.isArray( pages ) ? pages.join( '|' ) : String( pages ),
  32                                         uselang: mw.config.get( 'wgUserLanguage' )
  33                                 },
  34                                 addParams
  35                         )
  36                 );
  37
  38                 return apiPromise
  39                         .then( function ( data ) {
  40                                 // If a single page was given (not an array) respond with a single item as well.
  41                                 return $.isArray( pages ) ? data.watch : data.watch[ 0 ];
  42                         } )
  43                         .promise( { abort: apiPromise.abort } );
  44         }
  45
  46         $.extend( mw.Api.prototype, {
  47                 /**
  48                  * Convenience method for `action=watch`.
  49                  *
  50                  * @inheritdoc #doWatchInternal
  51                  */
  52                 watch: function ( pages ) {
  53                         return doWatchInternal.call( this, pages );
  54                 },
  55
  56                 /**
  57                  * Convenience method for `action=watch&unwatch=1`.
  58                  *
  59                  * @inheritdoc #doWatchInternal
  60                  */
  61                 unwatch: function ( pages ) {
  62                         return doWatchInternal.call( this, pages, { unwatch: 1 } );
  63                 }
  64         } );
  65
  66         /**
  67          * @class mw.Api
  68          * @mixins mw.Api.plugin.watch
  69          */
  70
  71 }( mediaWiki, jQuery ) );