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          * 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 ( 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          * Set 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 = $.extend( {}, 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          * Get 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 }() );