resources/src/mediawiki.widgets/mw.widgets.CategoryMultiselectWidget.js

   1 /*!
   2  * MediaWiki Widgets - CategoryMultiselectWidget class.
   3  *
   4  * @copyright 2011-2015 MediaWiki Widgets Team and others; see AUTHORS.txt
   5  * @license The MIT License (MIT); see LICENSE.txt
   6  */
   7 ( function ( $, mw ) {
   8         var hasOwn = Object.prototype.hasOwnProperty,
   9                 NS_CATEGORY = mw.config.get( 'wgNamespaceIds' ).category;
  10
  11         /**
  12          * Category selector widget. Displays an OO.ui.CapsuleMultiselectWidget
  13          * and autocompletes with available categories.
  14          *
  15          *     mw.loader.using( 'mediawiki.widgets.CategoryMultiselectWidget', function () {
  16          *       var selector = new mw.widgets.CategoryMultiselectWidget( {
  17          *         searchTypes: [
  18          *           mw.widgets.CategoryMultiselectWidget.SearchType.OpenSearch,
  19          *           mw.widgets.CategoryMultiselectWidget.SearchType.InternalSearch
  20          *         ]
  21          *       } );
  22          *
  23          *       $( 'body' ).append( selector.$element );
  24          *
  25          *       selector.setSearchTypes( [ mw.widgets.CategoryMultiselectWidget.SearchType.SubCategories ] );
  26          *     } );
  27          *
  28          * @class mw.widgets.CategoryMultiselectWidget
  29          * @uses mw.Api
  30          * @extends OO.ui.CapsuleMultiselectWidget
  31          * @mixins OO.ui.mixin.PendingElement
  32          *
  33          * @constructor
  34          * @param {Object} [config] Configuration options
  35          * @cfg {mw.Api} [api] Instance of mw.Api (or subclass thereof) to use for queries
  36          * @cfg {number} [limit=10] Maximum number of results to load
  37          * @cfg {mw.widgets.CategoryMultiselectWidget.SearchType[]} [searchTypes=[mw.widgets.CategoryMultiselectWidget.SearchType.OpenSearch]]
  38          *   Default search API to use when searching.
  39          */
  40         mw.widgets.CategoryMultiselectWidget = function MWCategoryMultiselectWidget( config ) {
  41                 // Config initialization
  42                 config = $.extend( {
  43                         limit: 10,
  44                         searchTypes: [ mw.widgets.CategoryMultiselectWidget.SearchType.OpenSearch ]
  45                 }, config );
  46                 this.limit = config.limit;
  47                 this.searchTypes = config.searchTypes;
  48                 this.validateSearchTypes();
  49
  50                 // Parent constructor
  51                 mw.widgets.CategoryMultiselectWidget.parent.call( this, $.extend( true, {}, config, {
  52                         menu: {
  53                                 filterFromInput: false
  54                         },
  55                         placeholder: mw.msg( 'mw-widgets-categoryselector-add-category-placeholder' ),
  56                         // This allows the user to both select non-existent categories, and prevents the selector from
  57                         // being wiped from #onMenuItemsChange when we change the available options in the dropdown
  58                         allowArbitrary: true
  59                 } ) );
  60
  61                 // Mixin constructors
  62                 OO.ui.mixin.PendingElement.call( this, $.extend( {}, config, { $pending: this.$handle } ) );
  63
  64                 // Event handler to call the autocomplete methods
  65                 this.$input.on( 'change input cut paste', OO.ui.debounce( this.updateMenuItems.bind( this ), 100 ) );
  66
  67                 // Initialize
  68                 this.api = config.api || new mw.Api();
  69                 this.searchCache = {};
  70         };
  71
  72         /* Setup */
  73
  74         OO.inheritClass( mw.widgets.CategoryMultiselectWidget, OO.ui.CapsuleMultiselectWidget );
  75         OO.mixinClass( mw.widgets.CategoryMultiselectWidget, OO.ui.mixin.PendingElement );
  76
  77         /* Methods */
  78
  79         /**
  80          * Gets new items based on the input by calling
  81          * {@link #getNewMenuItems getNewItems} and updates the menu
  82          * after removing duplicates based on the data value.
  83          *
  84          * @private
  85          * @method
  86          */
  87         mw.widgets.CategoryMultiselectWidget.prototype.updateMenuItems = function () {
  88                 this.getMenu().clearItems();
  89                 this.getNewMenuItems( this.$input.val() ).then( function ( items ) {
  90                         var existingItems, filteredItems,
  91                                 menu = this.getMenu();
  92
  93                         // Never show the menu if the input lost focus in the meantime
  94                         if ( !this.$input.is( ':focus' ) ) {
  95                                 return;
  96                         }
  97
  98                         // Array of strings of the data of OO.ui.MenuOptionsWidgets
  99                         existingItems = menu.getItems().map( function ( item ) {
 100                                 return item.data;
 101                         } );
 102
 103                         // Remove if items' data already exists
 104                         filteredItems = items.filter( function ( item ) {
 105                                 return existingItems.indexOf( item ) === -1;
 106                         } );
 107
 108                         // Map to an array of OO.ui.MenuOptionWidgets
 109                         filteredItems = filteredItems.map( function ( item ) {
 110                                 return new OO.ui.MenuOptionWidget( {
 111                                         data: item,
 112                                         label: item
 113                                 } );
 114                         } );
 115
 116                         menu.addItems( filteredItems ).toggle( true );
 117                 }.bind( this ) );
 118         };
 119
 120         /**
 121          * @inheritdoc
 122          */
 123         mw.widgets.CategoryMultiselectWidget.prototype.clearInput = function () {
 124                 mw.widgets.CategoryMultiselectWidget.parent.prototype.clearInput.call( this );
 125                 // Abort all pending requests, we won't need their results
 126                 this.api.abort();
 127         };
 128
 129         /**
 130          * Searches for categories based on the input.
 131          *
 132          * @private
 133          * @method
 134          * @param {string} input The input used to prefix search categories
 135          * @return {jQuery.Promise} Resolves with an array of categories
 136          */
 137         mw.widgets.CategoryMultiselectWidget.prototype.getNewMenuItems = function ( input ) {
 138                 var i,
 139                         promises = [],
 140                         deferred = $.Deferred();
 141
 142                 if ( input.trim() === '' ) {
 143                         deferred.resolve( [] );
 144                         return deferred.promise();
 145                 }
 146
 147                 // Abort all pending requests, we won't need their results
 148                 this.api.abort();
 149                 for ( i = 0; i < this.searchTypes.length; i++ ) {
 150                         promises.push( this.searchCategories( input, this.searchTypes[ i ] ) );
 151                 }
 152
 153                 this.pushPending();
 154
 155                 $.when.apply( $, promises ).done( function () {
 156                         var categoryNames,
 157                                 allData = [],
 158                                 dataSets = Array.prototype.slice.apply( arguments );
 159
 160                         // Collect values from all results
 161                         allData = allData.concat.apply( allData, dataSets );
 162
 163                         categoryNames = allData
 164                                 // Remove duplicates
 165                                 .filter( function ( value, index, self ) {
 166                                         return self.indexOf( value ) === index;
 167                                 } )
 168                                 // Get Title objects
 169                                 .map( function ( name ) {
 170                                         return mw.Title.newFromText( name );
 171                                 } )
 172                                 // Keep only titles from 'Category' namespace
 173                                 .filter( function ( title ) {
 174                                         return title && title.getNamespaceId() === NS_CATEGORY;
 175                                 } )
 176                                 // Convert back to strings, strip 'Category:' prefix
 177                                 .map( function ( title ) {
 178                                         return title.getMainText();
 179                                 } );
 180
 181                         deferred.resolve( categoryNames );
 182
 183                 } ).always( this.popPending.bind( this ) );
 184
 185                 return deferred.promise();
 186         };
 187
 188         /**
 189          * @inheritdoc
 190          */
 191         mw.widgets.CategoryMultiselectWidget.prototype.createItemWidget = function ( data ) {
 192                 var title = mw.Title.makeTitle( NS_CATEGORY, data );
 193                 if ( !title ) {
 194                         return null;
 195                 }
 196                 return new mw.widgets.CategoryCapsuleItemWidget( {
 197                         apiUrl: this.api.apiUrl || undefined,
 198                         title: title
 199                 } );
 200         };
 201
 202         /**
 203          * @inheritdoc
 204          */
 205         mw.widgets.CategoryMultiselectWidget.prototype.findItemFromData = function ( data ) {
 206                 // This is a bit of a hack... We have to canonicalize the data in the same way that
 207                 // #createItemWidget and CategoryCapsuleItemWidget will do, otherwise we won't find duplicates.
 208                 var title = mw.Title.makeTitle( NS_CATEGORY, data );
 209                 if ( !title ) {
 210                         return null;
 211                 }
 212                 return OO.ui.mixin.GroupElement.prototype.findItemFromData.call( this, title.getMainText() );
 213         };
 214
 215         /**
 216          * Validates the values in `this.searchType`.
 217          *
 218          * @private
 219          * @return {boolean}
 220          */
 221         mw.widgets.CategoryMultiselectWidget.prototype.validateSearchTypes = function () {
 222                 var validSearchTypes = false,
 223                         searchTypeEnumCount = Object.keys( mw.widgets.CategoryMultiselectWidget.SearchType ).length;
 224
 225                 // Check if all values are in the SearchType enum
 226                 validSearchTypes = this.searchTypes.every( function ( searchType ) {
 227                         return searchType > -1 && searchType < searchTypeEnumCount;
 228                 } );
 229
 230                 if ( validSearchTypes === false ) {
 231                         throw new Error( 'Unknown searchType in searchTypes' );
 232                 }
 233
 234                 // If the searchTypes has mw.widgets.CategoryMultiselectWidget.SearchType.SubCategories
 235                 // it can be the only search type.
 236                 if ( this.searchTypes.indexOf( mw.widgets.CategoryMultiselectWidget.SearchType.SubCategories ) > -1 &&
 237                         this.searchTypes.length > 1
 238                 ) {
 239                         throw new Error( 'Can\'t have additional search types with mw.widgets.CategoryMultiselectWidget.SearchType.SubCategories' );
 240                 }
 241
 242                 // If the searchTypes has mw.widgets.CategoryMultiselectWidget.SearchType.ParentCategories
 243                 // it can be the only search type.
 244                 if ( this.searchTypes.indexOf( mw.widgets.CategoryMultiselectWidget.SearchType.ParentCategories ) > -1 &&
 245                         this.searchTypes.length > 1
 246                 ) {
 247                         throw new Error( 'Can\'t have additional search types with mw.widgets.CategoryMultiselectWidget.SearchType.ParentCategories' );
 248                 }
 249
 250                 return true;
 251         };
 252
 253         /**
 254          * Sets and validates the value of `this.searchType`.
 255          *
 256          * @param {mw.widgets.CategoryMultiselectWidget.SearchType[]} searchTypes
 257          */
 258         mw.widgets.CategoryMultiselectWidget.prototype.setSearchTypes = function ( searchTypes ) {
 259                 this.searchTypes = searchTypes;
 260                 this.validateSearchTypes();
 261         };
 262
 263         /**
 264          * Searches categories based on input and searchType.
 265          *
 266          * @private
 267          * @method
 268          * @param {string} input The input used to prefix search categories
 269          * @param {mw.widgets.CategoryMultiselectWidget.SearchType} searchType
 270          * @return {jQuery.Promise} Resolves with an array of categories
 271          */
 272         mw.widgets.CategoryMultiselectWidget.prototype.searchCategories = function ( input, searchType ) {
 273                 var deferred = $.Deferred(),
 274                         cacheKey = input + searchType.toString();
 275
 276                 // Check cache
 277                 if ( hasOwn.call( this.searchCache, cacheKey ) ) {
 278                         return this.searchCache[ cacheKey ];
 279                 }
 280
 281                 switch ( searchType ) {
 282                         case mw.widgets.CategoryMultiselectWidget.SearchType.OpenSearch:
 283                                 this.api.get( {
 284                                         formatversion: 2,
 285                                         action: 'opensearch',
 286                                         namespace: NS_CATEGORY,
 287                                         limit: this.limit,
 288                                         search: input
 289                                 } ).done( function ( res ) {
 290                                         var categories = res[ 1 ];
 291                                         deferred.resolve( categories );
 292                                 } ).fail( deferred.reject.bind( deferred ) );
 293                                 break;
 294
 295                         case mw.widgets.CategoryMultiselectWidget.SearchType.InternalSearch:
 296                                 this.api.get( {
 297                                         formatversion: 2,
 298                                         action: 'query',
 299                                         list: 'allpages',
 300                                         apnamespace: NS_CATEGORY,
 301                                         aplimit: this.limit,
 302                                         apfrom: input,
 303                                         apprefix: input
 304                                 } ).done( function ( res ) {
 305                                         var categories = res.query.allpages.map( function ( page ) {
 306                                                 return page.title;
 307                                         } );
 308                                         deferred.resolve( categories );
 309                                 } ).fail( deferred.reject.bind( deferred ) );
 310                                 break;
 311
 312                         case mw.widgets.CategoryMultiselectWidget.SearchType.Exists:
 313                                 if ( input.indexOf( '|' ) > -1 ) {
 314                                         deferred.resolve( [] );
 315                                         break;
 316                                 }
 317
 318                                 this.api.get( {
 319                                         formatversion: 2,
 320                                         action: 'query',
 321                                         prop: 'info',
 322                                         titles: 'Category:' + input
 323                                 } ).done( function ( res ) {
 324                                         var categories = [];
 325
 326                                         $.each( res.query.pages, function ( index, page ) {
 327                                                 if ( !page.missing ) {
 328                                                         categories.push( page.title );
 329                                                 }
 330                                         } );
 331
 332                                         deferred.resolve( categories );
 333                                 } ).fail( deferred.reject.bind( deferred ) );
 334                                 break;
 335
 336                         case mw.widgets.CategoryMultiselectWidget.SearchType.SubCategories:
 337                                 if ( input.indexOf( '|' ) > -1 ) {
 338                                         deferred.resolve( [] );
 339                                         break;
 340                                 }
 341
 342                                 this.api.get( {
 343                                         formatversion: 2,
 344                                         action: 'query',
 345                                         list: 'categorymembers',
 346                                         cmtype: 'subcat',
 347                                         cmlimit: this.limit,
 348                                         cmtitle: 'Category:' + input
 349                                 } ).done( function ( res ) {
 350                                         var categories = res.query.categorymembers.map( function ( category ) {
 351                                                 return category.title;
 352                                         } );
 353                                         deferred.resolve( categories );
 354                                 } ).fail( deferred.reject.bind( deferred ) );
 355                                 break;
 356
 357                         case mw.widgets.CategoryMultiselectWidget.SearchType.ParentCategories:
 358                                 if ( input.indexOf( '|' ) > -1 ) {
 359                                         deferred.resolve( [] );
 360                                         break;
 361                                 }
 362
 363                                 this.api.get( {
 364                                         formatversion: 2,
 365                                         action: 'query',
 366                                         prop: 'categories',
 367                                         cllimit: this.limit,
 368                                         titles: 'Category:' + input
 369                                 } ).done( function ( res ) {
 370                                         var categories = [];
 371
 372                                         $.each( res.query.pages, function ( index, page ) {
 373                                                 if ( !page.missing && Array.isArray( page.categories ) ) {
 374                                                         categories.push.apply( categories, page.categories.map( function ( category ) {
 375                                                                 return category.title;
 376                                                         } ) );
 377                                                 }
 378                                         } );
 379
 380                                         deferred.resolve( categories );
 381                                 } ).fail( deferred.reject.bind( deferred ) );
 382                                 break;
 383
 384                         default:
 385                                 throw new Error( 'Unknown searchType' );
 386                 }
 387
 388                 // Cache the result
 389                 this.searchCache[ cacheKey ] = deferred.promise();
 390
 391                 return deferred.promise();
 392         };
 393
 394         /**
 395          * @enum mw.widgets.CategoryMultiselectWidget.SearchType
 396          * Types of search available.
 397          */
 398         mw.widgets.CategoryMultiselectWidget.SearchType = {
 399                 /** Search using action=opensearch */
 400                 OpenSearch: 0,
 401
 402                 /** Search using action=query */
 403                 InternalSearch: 1,
 404
 405                 /** Search for existing categories with the exact title */
 406                 Exists: 2,
 407
 408                 /** Search only subcategories */
 409                 SubCategories: 3,
 410
 411                 /** Search only parent categories */
 412                 ParentCategories: 4
 413         };
 414
 415         // For backwards compatibility. See T161285.
 416         mw.widgets.CategorySelector = mw.widgets.CategoryMultiselectWidget;
 417 }( jQuery, mediaWiki ) );