2 * MediaWiki Widgets - CategorySelector class.
4 * @copyright 2011-2015 MediaWiki Widgets Team and others; see AUTHORS.txt
5 * @license The MIT License (MIT); see LICENSE.txt
9 NS_CATEGORY
= mw
.config
.get( 'wgNamespaceIds' ).category
;
12 * Category selector widget. Displays an OO.ui.CapsuleMultiSelectWidget
13 * and autocompletes with available categories.
15 * var selector = new mw.widgets.CategorySelector( {
17 * mw.widgets.CategorySelector.SearchType.OpenSearch,
18 * mw.widgets.CategorySelector.SearchType.InternalSearch
22 * $( '#content' ).append( selector.$element );
24 * selector.setSearchType( [ mw.widgets.CategorySelector.SearchType.SubCategories ] );
26 * @class mw.widgets.CategorySelector
28 * @extends OO.ui.CapsuleMultiSelectWidget
29 * @mixins OO.ui.mixin.PendingElement
32 * @param {Object} [config] Configuration options
33 * @cfg {number} [limit=10] Maximum number of results to load
34 * @cfg {mw.widgets.CategorySelector.SearchType[]} [searchTypes=[mw.widgets.CategorySelector.SearchType.OpenSearch]]
35 * Default search API to use when searching.
37 function CategorySelector( config
) {
38 // Config initialization
41 searchTypes
: [ CategorySelector
.SearchType
.OpenSearch
]
43 this.limit
= config
.limit
;
44 this.searchTypes
= config
.searchTypes
;
45 this.validateSearchTypes();
48 mw
.widgets
.CategorySelector
.parent
.call( this, $.extend( true, {}, config
, {
50 filterFromInput
: false
52 // This allows the user to both select non-existent categories, and prevents the selector from
53 // being wiped from #onMenuItemsChange when we change the available options in the dropdown
58 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$handle
} ) );
60 // Event handler to call the autocomplete methods
61 this.$input
.on( 'change input cut paste', OO
.ui
.debounce( this.updateMenuItems
.bind( this ), 100 ) );
64 this.api
= new mw
.Api();
69 OO
.inheritClass( CategorySelector
, OO
.ui
.CapsuleMultiSelectWidget
);
70 OO
.mixinClass( CategorySelector
, OO
.ui
.mixin
.PendingElement
);
71 CSP
= CategorySelector
.prototype;
76 * Gets new items based on the input by calling
77 * {@link #getNewMenuItems getNewItems} and updates the menu
78 * after removing duplicates based on the data value.
83 CSP
.updateMenuItems = function () {
84 this.getMenu().clearItems();
85 this.getNewMenuItems( this.$input
.val() ).then( function ( items
) {
86 var existingItems
, filteredItems
,
87 menu
= this.getMenu();
89 // Never show the menu if the input lost focus in the meantime
90 if ( !this.$input
.is( ':focus' ) ) {
94 // Array of strings of the data of OO.ui.MenuOptionsWidgets
95 existingItems
= menu
.getItems().map( function ( item
) {
99 // Remove if items' data already exists
100 filteredItems
= items
.filter( function ( item
) {
101 return existingItems
.indexOf( item
) === -1;
104 // Map to an array of OO.ui.MenuOptionWidgets
105 filteredItems
= filteredItems
.map( function ( item
) {
106 return new OO
.ui
.MenuOptionWidget( {
112 menu
.addItems( filteredItems
).toggle( true );
119 CSP
.clearInput = function () {
120 CategorySelector
.parent
.prototype.clearInput
.call( this );
121 // Abort all pending requests, we won't need their results
126 * Searches for categories based on the input.
130 * @param {string} input The input used to prefix search categories
131 * @return {jQuery.Promise} Resolves with an array of categories
133 CSP
.getNewMenuItems = function ( input
) {
136 deferred
= new $.Deferred();
138 if ( $.trim( input
) === '' ) {
139 deferred
.resolve( [] );
140 return deferred
.promise();
143 // Abort all pending requests, we won't need their results
145 for ( i
= 0; i
< this.searchTypes
.length
; i
++ ) {
146 promises
.push( this.searchCategories( input
, this.searchTypes
[ i
] ) );
151 $.when
.apply( $, promises
).done( function () {
152 var categories
, categoryNames
,
154 dataSets
= Array
.prototype.slice
.apply( arguments
);
156 // Collect values from all results
157 allData
= allData
.concat
.apply( allData
, dataSets
);
160 categories
= allData
.filter( function ( value
, index
, self
) {
161 return self
.indexOf( value
) === index
;
165 categoryNames
= categories
.map( function ( name
) {
166 return mw
.Title
.newFromText( name
, NS_CATEGORY
).getMainText();
169 deferred
.resolve( categoryNames
);
171 } ).always( this.popPending
.bind( this ) );
173 return deferred
.promise();
179 CSP
.createItemWidget = function ( data
) {
180 return new mw
.widgets
.CategoryCapsuleItemWidget( {
181 title
: mw
.Title
.newFromText( data
, NS_CATEGORY
)
186 * Validates the values in `this.searchType`.
191 CSP
.validateSearchTypes = function () {
192 var validSearchTypes
= false,
193 searchTypeEnumCount
= Object
.keys( CategorySelector
.SearchType
).length
;
195 // Check if all values are in the SearchType enum
196 validSearchTypes
= this.searchTypes
.every( function ( searchType
) {
197 return searchType
> -1 && searchType
< searchTypeEnumCount
;
200 if ( validSearchTypes
=== false ) {
201 throw new Error( 'Unknown searchType in searchTypes' );
204 // If the searchTypes has CategorySelector.SearchType.SubCategories
205 // it can be the only search type.
206 if ( this.searchTypes
.indexOf( CategorySelector
.SearchType
.SubCategories
) > -1 &&
207 this.searchTypes
.length
> 1
209 throw new Error( 'Can\'t have additional search types with CategorySelector.SearchType.SubCategories' );
212 // If the searchTypes has CategorySelector.SearchType.ParentCategories
213 // it can be the only search type.
214 if ( this.searchTypes
.indexOf( CategorySelector
.SearchType
.ParentCategories
) > -1 &&
215 this.searchTypes
.length
> 1
217 throw new Error( 'Can\'t have additional search types with CategorySelector.SearchType.ParentCategories' );
224 * Sets and validates the value of `this.searchType`.
226 * @param {mw.widgets.CategorySelector.SearchType[]} searchTypes
228 CSP
.setSearchTypes = function ( searchTypes
) {
229 this.searchTypes
= searchTypes
;
230 this.validateSearchTypes();
234 * Searches categories based on input and searchType.
238 * @param {string} input The input used to prefix search categories
239 * @param {mw.widgets.CategorySelector.SearchType} searchType
240 * @return {jQuery.Promise} Resolves with an array of categories
242 CSP
.searchCategories = function ( input
, searchType
) {
243 var deferred
= new $.Deferred();
245 switch ( searchType
) {
246 case CategorySelector
.SearchType
.OpenSearch
:
248 action
: 'opensearch',
249 namespace: NS_CATEGORY
,
252 } ).done( function ( res
) {
253 var categories
= res
[ 1 ];
254 deferred
.resolve( categories
);
255 } ).fail( deferred
.reject
.bind( deferred
) );
258 case CategorySelector
.SearchType
.InternalSearch
:
262 apnamespace
: NS_CATEGORY
,
266 } ).done( function ( res
) {
267 var categories
= res
.query
.allpages
.map( function ( page
) {
270 deferred
.resolve( categories
);
271 } ).fail( deferred
.reject
.bind( deferred
) );
274 case CategorySelector
.SearchType
.Exists
:
275 if ( input
.indexOf( '|' ) > -1 ) {
276 deferred
.resolve( [] );
283 titles
: 'Category:' + input
284 } ).done( function ( res
) {
288 for ( page
in res
.query
.pages
) {
289 if ( parseInt( page
, 10 ) > -1 ) {
290 categories
.push( res
.query
.pages
[ page
].title
);
294 deferred
.resolve( categories
);
295 } ).fail( deferred
.reject
.bind( deferred
) );
298 case CategorySelector
.SearchType
.SubCategories
:
299 if ( input
.indexOf( '|' ) > -1 ) {
300 deferred
.resolve( [] );
306 list
: 'categorymembers',
309 cmtitle
: 'Category:' + input
310 } ).done( function ( res
) {
311 var categories
= res
.query
.categorymembers
.map( function ( category
) {
312 return category
.title
;
314 deferred
.resolve( categories
);
315 } ).fail( deferred
.reject
.bind( deferred
) );
318 case CategorySelector
.SearchType
.ParentCategories
:
319 if ( input
.indexOf( '|' ) > -1 ) {
320 deferred
.resolve( [] );
328 titles
: 'Category:' + input
329 } ).done( function ( res
) {
333 for ( page
in res
.query
.pages
) {
334 if ( parseInt( page
, 10 ) > -1 ) {
335 if ( $.isArray( res
.query
.pages
[ page
].categories
) ) {
336 categories
.push
.apply( categories
, res
.query
.pages
[ page
].categories
.map( function ( category
) {
337 return category
.title
;
343 deferred
.resolve( categories
);
344 } ).fail( deferred
.reject
.bind( deferred
) );
348 throw new Error( 'Unknown searchType' );
351 return deferred
.promise();
355 * @enum mw.widgets.CategorySelector.SearchType
356 * Types of search available.
358 CategorySelector
.SearchType
= {
359 /** Search using action=opensearch */
362 /** Search using action=query */
365 /** Search for existing categories with the exact title */
368 /** Search only subcategories */
371 /** Search only parent categories */
375 mw
.widgets
.CategorySelector
= CategorySelector
;
376 }( jQuery
, mediaWiki
) );