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