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

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