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