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
) {
64 if ( Array
.isArray( data
) && data
.length
) {
65 deferred
.resolve( data
);
70 return deferred
.promise( { abort
: xhr
.abort
} );
76 * @param {string} apiurl API url
78 mw
.widgets
.APIResultsProvider
.prototype.setAPIurl = function ( apiurl
) {
85 * @return {string} API url
87 mw
.widgets
.APIResultsProvider
.prototype.getAPIurl = function () {
92 * Get the static, non-changing data parameters sent to the API
94 * @return {Object} Data parameters
96 mw
.widgets
.APIResultsProvider
.prototype.getStaticParams = function () {
97 return this.staticParams
;
101 * Get the user-inputted dynamic data parameters sent to the API
103 * @return {Object} Data parameters
105 mw
.widgets
.APIResultsProvider
.prototype.getUserParams = function () {
106 return this.userParams
;
110 * Set the data parameters sent to the API
112 * @param {Object} params User defined data parameters
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
);
125 mw
.widgets
.APIResultsProvider
.prototype.reset = function () {
128 // Reset depleted status
129 this.toggleDepleted( false );
133 * Get fetch limit or 'page' size. This is the number
134 * of results per request.
136 * @return {number} limit
138 mw
.widgets
.APIResultsProvider
.prototype.getDefaultFetchLimit = function () {
145 * @param {number} limit Default number of results to fetch from the API
147 mw
.widgets
.APIResultsProvider
.prototype.setDefaultFetchLimit = function ( limit
) {
152 * Get provider API language
154 * @return {string} Provider API language
156 mw
.widgets
.APIResultsProvider
.prototype.getLang = function () {
161 * Set provider API language
163 * @param {string} lang Provider API language
165 mw
.widgets
.APIResultsProvider
.prototype.setLang = function ( lang
) {
172 * @return {number} Offset Results offset for the upcoming request
174 mw
.widgets
.APIResultsProvider
.prototype.getOffset = function () {
181 * @param {number} offset Results offset for the upcoming request
183 mw
.widgets
.APIResultsProvider
.prototype.setOffset = function ( offset
) {
184 this.offset
= offset
;
188 * Check whether the provider is depleted and has no more results
191 * @return {boolean} The provider is depleted
193 mw
.widgets
.APIResultsProvider
.prototype.isDepleted = function () {
194 return this.depleted
;
198 * Toggle depleted state
200 * @param {boolean} isDepleted The provider is depleted
202 mw
.widgets
.APIResultsProvider
.prototype.toggleDepleted = function ( isDepleted
) {
203 this.depleted
= isDepleted
!== undefined ? isDepleted
: !this.depleted
;
207 * Get the default ajax settings
209 * @return {Object} Ajax settings
211 mw
.widgets
.APIResultsProvider
.prototype.getAjaxSettings = function () {
212 return this.ajaxSettings
;
216 * Get the default ajax settings
218 * @param {Object} settings Ajax settings
220 mw
.widgets
.APIResultsProvider
.prototype.setAjaxSettings = function ( settings
) {
221 this.ajaxSettings
= settings
;