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