resources/src/mediawiki.widgets/MediaSearch/mw.widgets.APIResultsProvider.js

   1 /*!
   2  * MediaWiki Widgets - APIResultsProvider class.
   3  *
   4  * @copyright 2011-2016 VisualEditor Team and others; see http://ve.mit-license.org
   5  */
   6 ( function ( $, mw ) {
   7
   8         /**
   9          * API Results Provider object.
  10          *
  11          * @class
  12          * @mixins OO.EventEmitter
  13          *
  14          * @constructor
  15          * @param {string} apiurl The URL to the api
  16          * @param {Object} [config] Configuration options
  17          * @cfg {number} fetchLimit The default number of results to fetch
  18          * @cfg {string} lang The language of the API
  19          * @cfg {number} offset Initial offset, if relevant, to call results from
  20          * @cfg {Object} ajaxSettings The settings for the ajax call
  21          * @cfg {Object} staticParams The data parameters that are static and should
  22          *  always be sent to the API request, as opposed to user parameters.
  23          * @cfg {Object} userParams Initial user parameters to be sent as data to
  24          *  the API request. These can change per request, like the search query term
  25          *  or sizing parameters for images, etc.
  26          */
  27         mw.widgets.APIResultsProvider = function MwWidgetsAPIResultsProvider( apiurl, config ) {
  28                 config = config || {};
  29
  30                 this.setAPIurl( apiurl );
  31                 this.setDefaultFetchLimit( config.fetchLimit || 30 );
  32                 this.setLang( config.lang );
  33                 this.setOffset( config.offset || 0 );
  34                 this.setAjaxSettings( config.ajaxSettings || {} );
  35
  36                 this.staticParams = config.staticParams || {};
  37                 this.userParams = config.userParams || {};
  38
  39                 this.toggleDepleted( false );
  40
  41                 // Mixin constructors
  42                 OO.EventEmitter.call( this );
  43         };
  44
  45         /* Setup */
  46         OO.mixinClass( mw.widgets.APIResultsProvider, OO.EventEmitter );
  47
  48         /* Methods */
  49
  50         /**
  51          * Get results from the source
  52          *
  53          * @param {number} howMany Number of results to ask for
  54          * @return {jQuery.Promise} Promise that is resolved into an array
  55          * of available results, or is rejected if no results are available.
  56          */
  57         mw.widgets.APIResultsProvider.prototype.getResults = function () {
  58                 var xhr,
  59                         deferred = $.Deferred(),
  60                         allParams = $.extend( {}, this.getStaticParams(), this.getUserParams() );
  61
  62                 xhr = $.getJSON( this.getAPIurl(), allParams )
  63                         .done( function ( data ) {
  64                                 if (
  65                                         $.type( data ) !== 'array' ||
  66                                         (
  67                                                 $.type( data ) === 'array' &&
  68                                                 data.length === 0
  69                                         )
  70                                 ) {
  71                                         deferred.resolve();
  72                                 } else {
  73                                         deferred.resolve( data );
  74                                 }
  75                         } );
  76                 return deferred.promise( { abort: xhr.abort } );
  77         };
  78
  79         /**
  80          * Set API url
  81          *
  82          * @param {string} apiurl API url
  83          */
  84         mw.widgets.APIResultsProvider.prototype.setAPIurl = function ( apiurl ) {
  85                 this.apiurl = apiurl;
  86         };
  87
  88         /**
  89          * Set api url
  90          *
  91          * @return {string} API url
  92          */
  93         mw.widgets.APIResultsProvider.prototype.getAPIurl = function () {
  94                 return this.apiurl;
  95         };
  96
  97         /**
  98          * Get the static, non-changing data parameters sent to the API
  99          *
 100          * @return {Object} Data parameters
 101          */
 102         mw.widgets.APIResultsProvider.prototype.getStaticParams = function () {
 103                 return this.staticParams;
 104         };
 105
 106         /**
 107          * Get the user-inputted dynamic data parameters sent to the API
 108          *
 109          * @return {Object} Data parameters
 110          */
 111         mw.widgets.APIResultsProvider.prototype.getUserParams = function () {
 112                 return this.userParams;
 113         };
 114
 115         /**
 116          * Set the data parameters sent to the API
 117          *
 118          * @param {Object} params User defined data parameters
 119          */
 120         mw.widgets.APIResultsProvider.prototype.setUserParams = function ( params ) {
 121                 // Asymmetrically compare (params is subset of this.userParams)
 122                 if ( !OO.compare( params, this.userParams, true ) ) {
 123                         this.userParams = $.extend( {}, this.userParams, params );
 124                         this.reset();
 125                 }
 126         };
 127
 128         /**
 129          * Reset the provider
 130          */
 131         mw.widgets.APIResultsProvider.prototype.reset = function () {
 132                 // Reset offset
 133                 this.setOffset( 0 );
 134                 // Reset depleted status
 135                 this.toggleDepleted( false );
 136         };
 137
 138         /**
 139          * Get fetch limit or 'page' size. This is the number
 140          * of results per request.
 141          *
 142          * @return {number} limit
 143          */
 144         mw.widgets.APIResultsProvider.prototype.getDefaultFetchLimit = function () {
 145                 return this.limit;
 146         };
 147
 148         /**
 149          * Set limit
 150          *
 151          * @param {number} limit Default number of results to fetch from the API
 152          */
 153         mw.widgets.APIResultsProvider.prototype.setDefaultFetchLimit = function ( limit ) {
 154                 this.limit = limit;
 155         };
 156
 157         /**
 158          * Get provider API language
 159          *
 160          * @return {string} Provider API language
 161          */
 162         mw.widgets.APIResultsProvider.prototype.getLang = function () {
 163                 return this.lang;
 164         };
 165
 166         /**
 167          * Set provider API language
 168          *
 169          * @param {string} lang Provider API language
 170          */
 171         mw.widgets.APIResultsProvider.prototype.setLang = function ( lang ) {
 172                 this.lang = lang;
 173         };
 174
 175         /**
 176          * Get result offset
 177          *
 178          * @return {number} Offset Results offset for the upcoming request
 179          */
 180         mw.widgets.APIResultsProvider.prototype.getOffset = function () {
 181                 return this.offset;
 182         };
 183
 184         /**
 185          * Set result offset
 186          *
 187          * @param {number} offset Results offset for the upcoming request
 188          */
 189         mw.widgets.APIResultsProvider.prototype.setOffset = function ( offset ) {
 190                 this.offset = offset;
 191         };
 192
 193         /**
 194          * Check whether the provider is depleted and has no more results
 195          * to hand off.
 196          *
 197          * @return {boolean} The provider is depleted
 198          */
 199         mw.widgets.APIResultsProvider.prototype.isDepleted = function () {
 200                 return this.depleted;
 201         };
 202
 203         /**
 204          * Toggle depleted state
 205          *
 206          * @param {boolean} isDepleted The provider is depleted
 207          */
 208         mw.widgets.APIResultsProvider.prototype.toggleDepleted = function ( isDepleted ) {
 209                 this.depleted = isDepleted !== undefined ? isDepleted : !this.depleted;
 210         };
 211
 212         /**
 213          * Get the default ajax settings
 214          *
 215          * @return {Object} Ajax settings
 216          */
 217         mw.widgets.APIResultsProvider.prototype.getAjaxSettings = function () {
 218                 return this.ajaxSettings;
 219         };
 220
 221         /**
 222          * Get the default ajax settings
 223          *
 224          * @param {Object} settings Ajax settings
 225          */
 226         mw.widgets.APIResultsProvider.prototype.setAjaxSettings = function ( settings ) {
 227                 this.ajaxSettings = settings;
 228         };
 229 }( jQuery, mediaWiki ) );