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