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.setSearchTypes( [ 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 {mw.Api} [api] Instance of mw.Api (or subclass thereof) to use for queries
34 * @cfg {number} [limit=10] Maximum number of results to load
35 * @cfg {mw.widgets.CategorySelector.SearchType[]} [searchTypes=[mw.widgets.CategorySelector.SearchType.OpenSearch]]
36 * Default search API to use when searching.
38 function CategorySelector( config
) {
39 // Config initialization
42 searchTypes
: [ CategorySelector
.SearchType
.OpenSearch
]
44 this.limit
= config
.limit
;
45 this.searchTypes
= config
.searchTypes
;
46 this.validateSearchTypes();
49 mw
.widgets
.CategorySelector
.parent
.call( this, $.extend( true, {}, config
, {
51 filterFromInput
: false
53 // This allows the user to both select non-existent categories, and prevents the selector from
54 // being wiped from #onMenuItemsChange when we change the available options in the dropdown
59 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$handle
} ) );
61 // Event handler to call the autocomplete methods
62 this.$input
.on( 'change input cut paste', OO
.ui
.debounce( this.updateMenuItems
.bind( this ), 100 ) );
65 this.api
= config
.api
|| new mw
.Api();
70 OO
.inheritClass( CategorySelector
, OO
.ui
.CapsuleMultiselectWidget
);
71 OO
.mixinClass( CategorySelector
, OO
.ui
.mixin
.PendingElement
);
72 CSP
= CategorySelector
.prototype;
77 * Gets new items based on the input by calling
78 * {@link #getNewMenuItems getNewItems} and updates the menu
79 * after removing duplicates based on the data value.
84 CSP
.updateMenuItems = function () {
85 this.getMenu().clearItems();
86 this.getNewMenuItems( this.$input
.val() ).then( function ( items
) {
87 var existingItems
, filteredItems
,
88 menu
= this.getMenu();
90 // Never show the menu if the input lost focus in the meantime
91 if ( !this.$input
.is( ':focus' ) ) {
95 // Array of strings of the data of OO.ui.MenuOptionsWidgets
96 existingItems
= menu
.getItems().map( function ( item
) {
100 // Remove if items' data already exists
101 filteredItems
= items
.filter( function ( item
) {
102 return existingItems
.indexOf( item
) === -1;
105 // Map to an array of OO.ui.MenuOptionWidgets
106 filteredItems
= filteredItems
.map( function ( item
) {
107 return new OO
.ui
.MenuOptionWidget( {
113 menu
.addItems( filteredItems
).toggle( true );
120 CSP
.clearInput = function () {
121 CategorySelector
.parent
.prototype.clearInput
.call( this );
122 // Abort all pending requests, we won't need their results
127 * Searches for categories based on the input.
131 * @param {string} input The input used to prefix search categories
132 * @return {jQuery.Promise} Resolves with an array of categories
134 CSP
.getNewMenuItems = function ( input
) {
137 deferred
= $.Deferred();
139 if ( $.trim( input
) === '' ) {
140 deferred
.resolve( [] );
141 return deferred
.promise();
144 // Abort all pending requests, we won't need their results
146 for ( i
= 0; i
< this.searchTypes
.length
; i
++ ) {
147 promises
.push( this.searchCategories( input
, this.searchTypes
[ i
] ) );
152 $.when
.apply( $, promises
).done( function () {
155 dataSets
= Array
.prototype.slice
.apply( arguments
);
157 // Collect values from all results
158 allData
= allData
.concat
.apply( allData
, dataSets
);
160 categoryNames
= allData
162 .filter( function ( value
, index
, self
) {
163 return self
.indexOf( value
) === index
;
166 .map( function ( name
) {
167 return mw
.Title
.newFromText( name
);
169 // Keep only titles from 'Category' namespace
170 .filter( function ( title
) {
171 return title
&& title
.getNamespaceId() === NS_CATEGORY
;
173 // Convert back to strings, strip 'Category:' prefix
174 .map( function ( title
) {
175 return title
.getMainText();
178 deferred
.resolve( categoryNames
);
180 } ).always( this.popPending
.bind( this ) );
182 return deferred
.promise();
188 CSP
.createItemWidget = function ( data
) {
189 var title
= mw
.Title
.makeTitle( NS_CATEGORY
, data
);
193 return new mw
.widgets
.CategoryCapsuleItemWidget( {
194 apiUrl
: this.api
.apiUrl
|| undefined,
202 CSP
.getItemFromData = function ( data
) {
203 // This is a bit of a hack... We have to canonicalize the data in the same way that
204 // #createItemWidget and CategoryCapsuleItemWidget will do, otherwise we won't find duplicates.
205 var title
= mw
.Title
.makeTitle( NS_CATEGORY
, data
);
209 return OO
.ui
.mixin
.GroupElement
.prototype.getItemFromData
.call( this, title
.getMainText() );
213 * Validates the values in `this.searchType`.
218 CSP
.validateSearchTypes = function () {
219 var validSearchTypes
= false,
220 searchTypeEnumCount
= Object
.keys( CategorySelector
.SearchType
).length
;
222 // Check if all values are in the SearchType enum
223 validSearchTypes
= this.searchTypes
.every( function ( searchType
) {
224 return searchType
> -1 && searchType
< searchTypeEnumCount
;
227 if ( validSearchTypes
=== false ) {
228 throw new Error( 'Unknown searchType in searchTypes' );
231 // If the searchTypes has CategorySelector.SearchType.SubCategories
232 // it can be the only search type.
233 if ( this.searchTypes
.indexOf( CategorySelector
.SearchType
.SubCategories
) > -1 &&
234 this.searchTypes
.length
> 1
236 throw new Error( 'Can\'t have additional search types with CategorySelector.SearchType.SubCategories' );
239 // If the searchTypes has CategorySelector.SearchType.ParentCategories
240 // it can be the only search type.
241 if ( this.searchTypes
.indexOf( CategorySelector
.SearchType
.ParentCategories
) > -1 &&
242 this.searchTypes
.length
> 1
244 throw new Error( 'Can\'t have additional search types with CategorySelector.SearchType.ParentCategories' );
251 * Sets and validates the value of `this.searchType`.
253 * @param {mw.widgets.CategorySelector.SearchType[]} searchTypes
255 CSP
.setSearchTypes = function ( searchTypes
) {
256 this.searchTypes
= searchTypes
;
257 this.validateSearchTypes();
261 * Searches categories based on input and searchType.
265 * @param {string} input The input used to prefix search categories
266 * @param {mw.widgets.CategorySelector.SearchType} searchType
267 * @return {jQuery.Promise} Resolves with an array of categories
269 CSP
.searchCategories = function ( input
, searchType
) {
270 var deferred
= $.Deferred();
272 switch ( searchType
) {
273 case CategorySelector
.SearchType
.OpenSearch
:
276 action
: 'opensearch',
277 namespace: NS_CATEGORY
,
280 } ).done( function ( res
) {
281 var categories
= res
[ 1 ];
282 deferred
.resolve( categories
);
283 } ).fail( deferred
.reject
.bind( deferred
) );
286 case CategorySelector
.SearchType
.InternalSearch
:
291 apnamespace
: NS_CATEGORY
,
295 } ).done( function ( res
) {
296 var categories
= res
.query
.allpages
.map( function ( page
) {
299 deferred
.resolve( categories
);
300 } ).fail( deferred
.reject
.bind( deferred
) );
303 case CategorySelector
.SearchType
.Exists
:
304 if ( input
.indexOf( '|' ) > -1 ) {
305 deferred
.resolve( [] );
313 titles
: 'Category:' + input
314 } ).done( function ( res
) {
317 $.each( res
.query
.pages
, function ( index
, page
) {
318 if ( !page
.missing
) {
319 categories
.push( page
.title
);
323 deferred
.resolve( categories
);
324 } ).fail( deferred
.reject
.bind( deferred
) );
327 case CategorySelector
.SearchType
.SubCategories
:
328 if ( input
.indexOf( '|' ) > -1 ) {
329 deferred
.resolve( [] );
336 list
: 'categorymembers',
339 cmtitle
: 'Category:' + input
340 } ).done( function ( res
) {
341 var categories
= res
.query
.categorymembers
.map( function ( category
) {
342 return category
.title
;
344 deferred
.resolve( categories
);
345 } ).fail( deferred
.reject
.bind( deferred
) );
348 case CategorySelector
.SearchType
.ParentCategories
:
349 if ( input
.indexOf( '|' ) > -1 ) {
350 deferred
.resolve( [] );
359 titles
: 'Category:' + input
360 } ).done( function ( res
) {
363 $.each( res
.query
.pages
, function ( index
, page
) {
364 if ( !page
.missing
) {
365 if ( $.isArray( page
.categories
) ) {
366 categories
.push
.apply( categories
, page
.categories
.map( function ( category
) {
367 return category
.title
;
373 deferred
.resolve( categories
);
374 } ).fail( deferred
.reject
.bind( deferred
) );
378 throw new Error( 'Unknown searchType' );
381 return deferred
.promise();
385 * @enum mw.widgets.CategorySelector.SearchType
386 * Types of search available.
388 CategorySelector
.SearchType
= {
389 /** Search using action=opensearch */
392 /** Search using action=query */
395 /** Search for existing categories with the exact title */
398 /** Search only subcategories */
401 /** Search only parent categories */
405 mw
.widgets
.CategorySelector
= CategorySelector
;
406 }( jQuery
, mediaWiki
) );