[Summary view] [Print] [Text view]

   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 ) );