2 * MediaWiki Widgets - APIResultsProvider class.
4 * @copyright 2011-2016 VisualEditor Team and others; see http://ve.mit-license.org
9 * API Results Provider object.
12 * @mixins OO.EventEmitter
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.
27 mw
.widgets
.APIResultsProvider
= function MwWidgetsAPIResultsProvider( apiurl
, config
) {
28 config
= config
|| {};
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
|| {} );
36 this.staticParams
= config
.staticParams
|| {};
37 this.userParams
= config
.userParams
|| {};
39 this.toggleDepleted( false );
42 OO
.EventEmitter
.call( this );
46 OO
.mixinClass( mw
.widgets
.APIResultsProvider
, OO
.EventEmitter
);
51 * Get results from the source
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.
57 mw
.widgets
.APIResultsProvider
.prototype.getResults = function () {
59 deferred
= $.Deferred(),
60 allParams
= $.extend( {}, this.getStaticParams(), this.getUserParams() );
62 xhr
= $.getJSON( this.getAPIurl(), allParams
)
63 .done( function ( data
) {
65 $.type( data
) !== 'array' ||
67 $.type( data
) === 'array' &&
73 deferred
.resolve( data
);
76 return deferred
.promise( { abort
: xhr
.abort
} );
82 * @param {string} apiurl API url
84 mw
.widgets
.APIResultsProvider
.prototype.setAPIurl = function ( apiurl
) {
91 * @return {string} API url
93 mw
.widgets
.APIResultsProvider
.prototype.getAPIurl = function () {
98 * Get the static, non-changing data parameters sent to the API
100 * @return {Object} Data parameters
102 mw
.widgets
.APIResultsProvider
.prototype.getStaticParams = function () {
103 return this.staticParams
;
107 * Get the user-inputted dynamic data parameters sent to the API
109 * @return {Object} Data parameters
111 mw
.widgets
.APIResultsProvider
.prototype.getUserParams = function () {
112 return this.userParams
;
116 * Set the data parameters sent to the API
118 * @param {Object} params User defined data parameters
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
);
131 mw
.widgets
.APIResultsProvider
.prototype.reset = function () {
134 // Reset depleted status
135 this.toggleDepleted( false );
139 * Get fetch limit or 'page' size. This is the number
140 * of results per request.
142 * @return {number} limit
144 mw
.widgets
.APIResultsProvider
.prototype.getDefaultFetchLimit = function () {
151 * @param {number} limit Default number of results to fetch from the API
153 mw
.widgets
.APIResultsProvider
.prototype.setDefaultFetchLimit = function ( limit
) {
158 * Get provider API language
160 * @return {string} Provider API language
162 mw
.widgets
.APIResultsProvider
.prototype.getLang = function () {
167 * Set provider API language
169 * @param {string} lang Provider API language
171 mw
.widgets
.APIResultsProvider
.prototype.setLang = function ( lang
) {
178 * @return {number} Offset Results offset for the upcoming request
180 mw
.widgets
.APIResultsProvider
.prototype.getOffset = function () {
187 * @param {number} offset Results offset for the upcoming request
189 mw
.widgets
.APIResultsProvider
.prototype.setOffset = function ( offset
) {
190 this.offset
= offset
;
194 * Check whether the provider is depleted and has no more results
197 * @return {boolean} The provider is depleted
199 mw
.widgets
.APIResultsProvider
.prototype.isDepleted = function () {
200 return this.depleted
;
204 * Toggle depleted state
206 * @param {boolean} isDepleted The provider is depleted
208 mw
.widgets
.APIResultsProvider
.prototype.toggleDepleted = function ( isDepleted
) {
209 this.depleted
= isDepleted
!== undefined ? isDepleted
: !this.depleted
;
213 * Get the default ajax settings
215 * @return {Object} Ajax settings
217 mw
.widgets
.APIResultsProvider
.prototype.getAjaxSettings = function () {
218 return this.ajaxSettings
;
222 * Get the default ajax settings
224 * @param {Object} settings Ajax settings
226 mw
.widgets
.APIResultsProvider
.prototype.setAjaxSettings = function ( settings
) {
227 this.ajaxSettings
= settings
;
229 }( jQuery
, mediaWiki
) );