resources/src/mediawiki.rcfilters/dm/mw.rcfilters.dm.FiltersViewModel.js

   1 ( function ( mw, $ ) {
   2         /**
   3          * View model for the filters selection and display
   4          *
   5          * @mixins OO.EventEmitter
   6          * @mixins OO.EmitterList
   7          *
   8          * @constructor
   9          */
  10         mw.rcfilters.dm.FiltersViewModel = function MwRcfiltersDmFiltersViewModel() {
  11                 // Mixin constructor
  12                 OO.EventEmitter.call( this );
  13                 OO.EmitterList.call( this );
  14
  15                 this.groups = {};
  16                 this.defaultParams = {};
  17                 this.defaultFiltersEmpty = null;
  18                 this.highlightEnabled = false;
  19                 this.parameterMap = {};
  20
  21                 // Events
  22                 this.aggregate( { update: 'filterItemUpdate' } );
  23                 this.connect( this, { filterItemUpdate: [ 'emit', 'itemUpdate' ] } );
  24         };
  25
  26         /* Initialization */
  27         OO.initClass( mw.rcfilters.dm.FiltersViewModel );
  28         OO.mixinClass( mw.rcfilters.dm.FiltersViewModel, OO.EventEmitter );
  29         OO.mixinClass( mw.rcfilters.dm.FiltersViewModel, OO.EmitterList );
  30
  31         /* Events */
  32
  33         /**
  34          * @event initialize
  35          *
  36          * Filter list is initialized
  37          */
  38
  39         /**
  40          * @event itemUpdate
  41          * @param {mw.rcfilters.dm.FilterItem} item Filter item updated
  42          *
  43          * Filter item has changed
  44          */
  45
  46         /**
  47          * @event highlightChange
  48          * @param {boolean} Highlight feature is enabled
  49          *
  50          * Highlight feature has been toggled enabled or disabled
  51          */
  52
  53         /* Methods */
  54
  55         /**
  56          * Re-assess the states of filter items based on the interactions between them
  57          *
  58          * @param {mw.rcfilters.dm.FilterItem} [item] Changed item. If not given, the
  59          *  method will go over the state of all items
  60          */
  61         mw.rcfilters.dm.FiltersViewModel.prototype.reassessFilterInteractions = function ( item ) {
  62                 var allSelected,
  63                         model = this,
  64                         iterationItems = item !== undefined ? [ item ] : this.getItems();
  65
  66                 iterationItems.forEach( function ( checkedItem ) {
  67                         var allCheckedItems = checkedItem.getSubset().concat( [ checkedItem.getName() ] ),
  68                                 groupModel = checkedItem.getGroupModel();
  69
  70                         // Check for subsets (included filters) plus the item itself:
  71                         allCheckedItems.forEach( function ( filterItemName ) {
  72                                 var itemInSubset = model.getItemByName( filterItemName );
  73
  74                                 itemInSubset.toggleIncluded(
  75                                         // If any of itemInSubset's supersets are selected, this item
  76                                         // is included
  77                                         itemInSubset.getSuperset().some( function ( supersetName ) {
  78                                                 return ( model.getItemByName( supersetName ).isSelected() );
  79                                         } )
  80                                 );
  81                         } );
  82
  83                         // Update coverage for the changed group
  84                         if ( groupModel.isFullCoverage() ) {
  85                                 allSelected = groupModel.areAllSelected();
  86                                 groupModel.getItems().forEach( function ( filterItem ) {
  87                                         filterItem.toggleFullyCovered( allSelected );
  88                                 } );
  89                         }
  90                 } );
  91
  92                 // Check for conflicts
  93                 // In this case, we must go over all items, since
  94                 // conflicts are bidirectional and depend not only on
  95                 // individual items, but also on the selected states of
  96                 // the groups they're in.
  97                 this.getItems().forEach( function ( filterItem ) {
  98                         var inConflict = false,
  99                                 filterItemGroup = filterItem.getGroupModel();
 100
 101                         // For each item, see if that item is still conflicting
 102                         $.each( model.groups, function ( groupName, groupModel ) {
 103                                 if ( filterItem.getGroupName() === groupName ) {
 104                                         // Check inside the group
 105                                         inConflict = groupModel.areAnySelectedInConflictWith( filterItem );
 106                                 } else {
 107                                         // According to the spec, if two items conflict from two different
 108                                         // groups, the conflict only lasts if the groups **only have selected
 109                                         // items that are conflicting**. If a group has selected items that
 110                                         // are conflicting and non-conflicting, the scope of the result has
 111                                         // expanded enough to completely remove the conflict.
 112
 113                                         // For example, see two groups with conflicts:
 114                                         // userExpLevel: [
 115                                         //   {
 116                                         //     name: 'experienced',
 117                                         //     conflicts: [ 'unregistered' ]
 118                                         //   }
 119                                         // ],
 120                                         // registration: [
 121                                         //   {
 122                                         //     name: 'registered',
 123                                         //   },
 124                                         //   {
 125                                         //     name: 'unregistered',
 126                                         //   }
 127                                         // ]
 128                                         // If we select 'experienced', then 'unregistered' is in conflict (and vice versa),
 129                                         // because, inherently, 'experienced' filter only includes registered users, and so
 130                                         // both filters are in conflict with one another.
 131                                         // However, the minute we select 'registered', the scope of our results
 132                                         // has expanded to no longer have a conflict with 'experienced' filter, and
 133                                         // so the conflict is removed.
 134
 135                                         // In our case, we need to check if the entire group conflicts with
 136                                         // the entire item's group, so we follow the above spec
 137                                         inConflict = (
 138                                                 // The foreign group is in conflict with this item
 139                                                 groupModel.areAllSelectedInConflictWith( filterItem ) &&
 140                                                 // Every selected member of the item's own group is also
 141                                                 // in conflict with the other group
 142                                                 filterItemGroup.getSelectedItems().every( function ( otherGroupItem ) {
 143                                                         return groupModel.areAllSelectedInConflictWith( otherGroupItem );
 144                                                 } )
 145                                         );
 146                                 }
 147
 148                                 // If we're in conflict, this will return 'false' which
 149                                 // will break the loop. Otherwise, we're not in conflict
 150                                 // and the loop continues
 151                                 return !inConflict;
 152                         } );
 153
 154                         // Toggle the item state
 155                         filterItem.toggleConflicted( inConflict );
 156                 } );
 157         };
 158
 159         /**
 160          * Get whether the model has any conflict in its items
 161          *
 162          * @return {boolean} There is a conflict
 163          */
 164         mw.rcfilters.dm.FiltersViewModel.prototype.hasConflict = function () {
 165                 return this.getItems().some( function ( filterItem ) {
 166                         return filterItem.isSelected() && filterItem.isConflicted();
 167                 } );
 168         };
 169
 170         /**
 171          * Get the first item with a current conflict
 172          *
 173          * @return {mw.rcfilters.dm.FilterItem} Conflicted item
 174          */
 175         mw.rcfilters.dm.FiltersViewModel.prototype.getFirstConflictedItem = function () {
 176                 var conflictedItem;
 177
 178                 $.each( this.getItems(), function ( index, filterItem ) {
 179                         if ( filterItem.isSelected() && filterItem.isConflicted() ) {
 180                                 conflictedItem = filterItem;
 181                                 return false;
 182                         }
 183                 } );
 184
 185                 return conflictedItem;
 186         };
 187
 188         /**
 189          * Set filters and preserve a group relationship based on
 190          * the definition given by an object
 191          *
 192          * @param {Array} filters Filter group definition
 193          */
 194         mw.rcfilters.dm.FiltersViewModel.prototype.initializeFilters = function ( filters ) {
 195                 var filterItem, filterConflictResult, groupConflictResult,
 196                         model = this,
 197                         items = [],
 198                         groupConflictMap = {},
 199                         filterConflictMap = {},
 200                         /*!
 201                          * Expand a conflict definition from group name to
 202                          * the list of all included filters in that group.
 203                          * We do this so that the direct relationship in the
 204                          * models are consistently item->items rather than
 205                          * mixing item->group with item->item.
 206                          *
 207                          * @param {Object} obj Conflict definition
 208                          * @return {Object} Expanded conflict definition
 209                          */
 210                         expandConflictDefinitions = function ( obj ) {
 211                                 var result = {};
 212
 213                                 $.each( obj, function ( key, conflicts ) {
 214                                         var filterName,
 215                                                 adjustedConflicts = {};
 216
 217                                         conflicts.forEach( function ( conflict ) {
 218                                                 var filter;
 219
 220                                                 if ( conflict.filter ) {
 221                                                         filterName = model.groups[ conflict.group ].getPrefixedName( conflict.filter );
 222                                                         filter = model.getItemByName( filterName );
 223
 224                                                         // Rename
 225                                                         adjustedConflicts[ filterName ] = $.extend(
 226                                                                 {},
 227                                                                 conflict,
 228                                                                 {
 229                                                                         filter: filterName,
 230                                                                         item: filter
 231                                                                 }
 232                                                         );
 233                                                 } else {
 234                                                         // This conflict is for an entire group. Split it up to
 235                                                         // represent each filter
 236
 237                                                         // Get the relevant group items
 238                                                         model.groups[ conflict.group ].getItems().forEach( function ( groupItem ) {
 239                                                                 // Rebuild the conflict
 240                                                                 adjustedConflicts[ groupItem.getName() ] = $.extend(
 241                                                                         {},
 242                                                                         conflict,
 243                                                                         {
 244                                                                                 filter: groupItem.getName(),
 245                                                                                 item: groupItem
 246                                                                         }
 247                                                                 );
 248                                                         } );
 249                                                 }
 250                                         } );
 251
 252                                         result[ key ] = adjustedConflicts;
 253                                 } );
 254
 255                                 return result;
 256                         };
 257
 258                 // Reset
 259                 this.clearItems();
 260                 this.groups = {};
 261
 262                 filters.forEach( function ( data ) {
 263                         var i,
 264                                 group = data.name;
 265
 266                         if ( !model.groups[ group ] ) {
 267                                 model.groups[ group ] = new mw.rcfilters.dm.FilterGroup( group, {
 268                                         type: data.type,
 269                                         title: mw.msg( data.title ),
 270                                         separator: data.separator,
 271                                         fullCoverage: !!data.fullCoverage,
 272                                         whatsThis: {
 273                                                 body: data.whatsThisBody,
 274                                                 header: data.whatsThisHeader,
 275                                                 linkText: data.whatsThisLinkText,
 276                                                 url: data.whatsThisUrl
 277                                         }
 278                                 } );
 279                         }
 280                         model.groups[ group ].initializeFilters( data.filters, data.default );
 281                         items = items.concat( model.groups[ group ].getItems() );
 282
 283                         // Prepare conflicts
 284                         if ( data.conflicts ) {
 285                                 // Group conflicts
 286                                 groupConflictMap[ group ] = data.conflicts;
 287                         }
 288
 289                         for ( i = 0; i < data.filters.length; i++ ) {
 290                                 // Filter conflicts
 291                                 if ( data.filters[ i ].conflicts ) {
 292                                         filterItem = model.groups[ group ].getItemByParamName( data.filters[ i ].name );
 293                                         filterConflictMap[ filterItem.getName() ] = data.filters[ i ].conflicts;
 294                                 }
 295                         }
 296                 } );
 297
 298                 // Add item references to the model, for lookup
 299                 this.addItems( items );
 300
 301                 // Expand conflicts
 302                 groupConflictResult = expandConflictDefinitions( groupConflictMap );
 303                 filterConflictResult = expandConflictDefinitions( filterConflictMap );
 304
 305                 // Set conflicts for groups
 306                 $.each( groupConflictResult, function ( group, conflicts ) {
 307                         model.groups[ group ].setConflicts( conflicts );
 308                 } );
 309
 310                 // Set conflicts for items
 311                 $.each( filterConflictResult, function ( filterName, conflicts ) {
 312                         var filterItem = model.getItemByName( filterName );
 313                         // set conflicts for items in the group
 314                         filterItem.setConflicts( conflicts );
 315                 } );
 316
 317                 // Create a map between known parameters and their models
 318                 $.each( this.groups, function ( group, groupModel ) {
 319                         if ( groupModel.getType() === 'send_unselected_if_any' ) {
 320                                 // Individual filters
 321                                 groupModel.getItems().forEach( function ( filterItem ) {
 322                                         model.parameterMap[ filterItem.getParamName() ] = filterItem;
 323                                 } );
 324                         } else if ( groupModel.getType() === 'string_options' ) {
 325                                 // Group
 326                                 model.parameterMap[ groupModel.getName() ] = groupModel;
 327                         }
 328                 } );
 329
 330                 // Finish initialization
 331                 this.emit( 'initialize' );
 332         };
 333
 334         /**
 335          * Get the names of all available filters
 336          *
 337          * @return {string[]} An array of filter names
 338          */
 339         mw.rcfilters.dm.FiltersViewModel.prototype.getFilterNames = function () {
 340                 return this.getItems().map( function ( item ) { return item.getName(); } );
 341         };
 342
 343         /**
 344          * Get the object that defines groups by their name.
 345          *
 346          * @return {Object} Filter groups
 347          */
 348         mw.rcfilters.dm.FiltersViewModel.prototype.getFilterGroups = function () {
 349                 return this.groups;
 350         };
 351
 352         /**
 353          * Get the value of a specific parameter
 354          *
 355          * @param {string} name Parameter name
 356          * @return {number|string} Parameter value
 357          */
 358         mw.rcfilters.dm.FiltersViewModel.prototype.getParamValue = function ( name ) {
 359                 return this.parameters[ name ];
 360         };
 361
 362         /**
 363          * Get the current selected state of the filters
 364          *
 365          * @return {Object} Filters selected state
 366          */
 367         mw.rcfilters.dm.FiltersViewModel.prototype.getSelectedState = function () {
 368                 var i,
 369                         items = this.getItems(),
 370                         result = {};
 371
 372                 for ( i = 0; i < items.length; i++ ) {
 373                         result[ items[ i ].getName() ] = items[ i ].isSelected();
 374                 }
 375
 376                 return result;
 377         };
 378
 379         /**
 380          * Get the current full state of the filters
 381          *
 382          * @return {Object} Filters full state
 383          */
 384         mw.rcfilters.dm.FiltersViewModel.prototype.getFullState = function () {
 385                 var i,
 386                         items = this.getItems(),
 387                         result = {};
 388
 389                 for ( i = 0; i < items.length; i++ ) {
 390                         result[ items[ i ].getName() ] = {
 391                                 selected: items[ i ].isSelected(),
 392                                 conflicted: items[ i ].isConflicted(),
 393                                 included: items[ i ].isIncluded()
 394                         };
 395                 }
 396
 397                 return result;
 398         };
 399
 400         /**
 401          * Get an object representing default parameters state
 402          *
 403          * @return {Object} Default parameter values
 404          */
 405         mw.rcfilters.dm.FiltersViewModel.prototype.getDefaultParams = function () {
 406                 var result = {};
 407
 408                 // Get default filter state
 409                 $.each( this.groups, function ( name, model ) {
 410                         result = $.extend( true, {}, result, model.getDefaultParams() );
 411                 } );
 412
 413                 // Get default highlight state
 414                 result = $.extend( true, {}, result, this.getHighlightParameters() );
 415
 416                 return result;
 417         };
 418
 419         /**
 420          * Analyze the groups and their filters and output an object representing
 421          * the state of the parameters they represent.
 422          *
 423          * @param {Object} [filterDefinition] An object defining the filter values,
 424          *  keyed by filter names.
 425          * @return {Object} Parameter state object
 426          */
 427         mw.rcfilters.dm.FiltersViewModel.prototype.getParametersFromFilters = function ( filterDefinition ) {
 428                 var groupItemDefinition,
 429                         result = {},
 430                         groupItems = this.getFilterGroups();
 431
 432                 if ( filterDefinition ) {
 433                         groupItemDefinition = {};
 434                         // Filter definition is "flat", but in effect
 435                         // each group needs to tell us its result based
 436                         // on the values in it. We need to split this list
 437                         // back into groupings so we can "feed" it to the
 438                         // loop below, and we need to expand it so it includes
 439                         // all filters (set to false)
 440                         this.getItems().forEach( function ( filterItem ) {
 441                                 groupItemDefinition[ filterItem.getGroupName() ] = groupItemDefinition[ filterItem.getGroupName() ] || {};
 442                                 groupItemDefinition[ filterItem.getGroupName() ][ filterItem.getName() ] = !!filterDefinition[ filterItem.getName() ];
 443                         } );
 444                 }
 445
 446                 $.each( groupItems, function ( group, model ) {
 447                         $.extend(
 448                                 result,
 449                                 model.getParamRepresentation(
 450                                         groupItemDefinition ?
 451                                                 groupItemDefinition[ group ] : null
 452                                 )
 453                         );
 454                 } );
 455
 456                 return result;
 457         };
 458
 459         /**
 460          * This is the opposite of the #getParametersFromFilters method; this goes over
 461          * the given parameters and translates into a selected/unselected value in the filters.
 462          *
 463          * @param {Object} params Parameters query object
 464          * @return {Object} Filter state object
 465          */
 466         mw.rcfilters.dm.FiltersViewModel.prototype.getFiltersFromParameters = function ( params ) {
 467                 var groupMap = {},
 468                         model = this,
 469                         result = {};
 470
 471                 // Go over the given parameters, break apart to groupings
 472                 // The resulting object represents the group with its parameter
 473                 // values. For example:
 474                 // {
 475                 //    group1: {
 476                 //       param1: "1",
 477                 //       param2: "0",
 478                 //       param3: "1"
 479                 //    },
 480                 //    group2: "param4|param5"
 481                 // }
 482                 $.each( params, function ( paramName, paramValue ) {
 483                         var itemOrGroup = model.parameterMap[ paramName ];
 484
 485                         if ( itemOrGroup instanceof mw.rcfilters.dm.FilterItem ) {
 486                                 groupMap[ itemOrGroup.getGroupName() ] = groupMap[ itemOrGroup.getGroupName() ] || {};
 487                                 groupMap[ itemOrGroup.getGroupName() ][ itemOrGroup.getParamName() ] = paramValue;
 488                         } else if ( itemOrGroup instanceof mw.rcfilters.dm.FilterGroup ) {
 489                                 // This parameter represents a group (values are the filters)
 490                                 // this is equivalent to checking if the group is 'string_options'
 491                                 groupMap[ itemOrGroup.getName() ] = groupMap[ itemOrGroup.getName() ] || {};
 492                                 groupMap[ itemOrGroup.getName() ] = paramValue;
 493                         }
 494                 } );
 495
 496                 // Go over all groups, so we make sure we get the complete output
 497                 // even if the parameters don't include a certain group
 498                 $.each( this.groups, function ( groupName, groupModel ) {
 499                         result = $.extend( true, {}, result, groupModel.getFilterRepresentation( groupMap[ groupName ] ) );
 500                 } );
 501
 502                 return result;
 503         };
 504
 505         /**
 506          * Get the highlight parameters based on current filter configuration
 507          *
 508          * @return {Object} Object where keys are "<filter name>_color" and values
 509          *                  are the selected highlight colors.
 510          */
 511         mw.rcfilters.dm.FiltersViewModel.prototype.getHighlightParameters = function () {
 512                 var result = {};
 513
 514                 this.getItems().forEach( function ( filterItem ) {
 515                         result[ filterItem.getName() + '_color' ] = filterItem.getHighlightColor() || null;
 516                 } );
 517                 result.highlight = String( Number( this.isHighlightEnabled() ) );
 518
 519                 return result;
 520         };
 521
 522         /**
 523          * Extract the highlight values from given object. Since highlights are
 524          * the same for filter and parameters, it doesn't matter which one is
 525          * given; values will be returned with a full list of the highlights
 526          * with colors or null values.
 527          *
 528          * @param {Object} representation Object containing representation of
 529          *  some or all highlight values
 530          * @return {Object} Object where keys are "<filter name>_color" and values
 531          *                  are the selected highlight colors. The returned object
 532          *                  contains all available filters either with a color value
 533          *                  or with null.
 534          */
 535         mw.rcfilters.dm.FiltersViewModel.prototype.extractHighlightValues = function ( representation ) {
 536                 var result = {};
 537
 538                 this.getItems().forEach( function ( filterItem ) {
 539                         var highlightName = filterItem.getName() + '_color';
 540                         result[ highlightName ] = representation[ highlightName ] || null;
 541                 } );
 542
 543                 return result;
 544         };
 545
 546         /**
 547          * Sanitize value group of a string_option groups type
 548          * Remove duplicates and make sure to only use valid
 549          * values.
 550          *
 551          * @private
 552          * @param {string} groupName Group name
 553          * @param {string[]} valueArray Array of values
 554          * @return {string[]} Array of valid values
 555          */
 556         mw.rcfilters.dm.FiltersViewModel.prototype.sanitizeStringOptionGroup = function ( groupName, valueArray ) {
 557                 var validNames = this.getGroupFilters( groupName ).map( function ( filterItem ) {
 558                         return filterItem.getParamName();
 559                 } );
 560
 561                 return mw.rcfilters.utils.normalizeParamOptions( valueArray, validNames );
 562         };
 563
 564         /**
 565          * Check whether the current filter state is set to all false.
 566          *
 567          * @return {boolean} Current filters are all empty
 568          */
 569         mw.rcfilters.dm.FiltersViewModel.prototype.areCurrentFiltersEmpty = function () {
 570                 // Check if there are either any selected items or any items
 571                 // that have highlight enabled
 572                 return !this.getItems().some( function ( filterItem ) {
 573                         return filterItem.isSelected() || filterItem.isHighlighted();
 574                 } );
 575         };
 576
 577         /**
 578          * Check whether the default values of the filters are all false.
 579          *
 580          * @return {boolean} Default filters are all false
 581          */
 582         mw.rcfilters.dm.FiltersViewModel.prototype.areDefaultFiltersEmpty = function () {
 583                 var defaultFilters;
 584
 585                 if ( this.defaultFiltersEmpty !== null ) {
 586                         // We only need to do this test once,
 587                         // because defaults are set once per session
 588                         defaultFilters = this.getFiltersFromParameters( this.getDefaultParams() );
 589                         this.defaultFiltersEmpty = Object.keys( defaultFilters ).every( function ( filterName ) {
 590                                 return !defaultFilters[ filterName ];
 591                         } );
 592                 }
 593
 594                 return this.defaultFiltersEmpty;
 595         };
 596
 597         /**
 598          * Get the item that matches the given name
 599          *
 600          * @param {string} name Filter name
 601          * @return {mw.rcfilters.dm.FilterItem} Filter item
 602          */
 603         mw.rcfilters.dm.FiltersViewModel.prototype.getItemByName = function ( name ) {
 604                 return this.getItems().filter( function ( item ) {
 605                         return name === item.getName();
 606                 } )[ 0 ];
 607         };
 608
 609         /**
 610          * Set all filters to false or empty/all
 611          * This is equivalent to display all.
 612          */
 613         mw.rcfilters.dm.FiltersViewModel.prototype.emptyAllFilters = function () {
 614                 this.getItems().forEach( function ( filterItem ) {
 615                         this.toggleFilterSelected( filterItem.getName(), false );
 616                 }.bind( this ) );
 617         };
 618
 619         /**
 620          * Toggle selected state of one item
 621          *
 622          * @param {string} name Name of the filter item
 623          * @param {boolean} [isSelected] Filter selected state
 624          */
 625         mw.rcfilters.dm.FiltersViewModel.prototype.toggleFilterSelected = function ( name, isSelected ) {
 626                 var item = this.getItemByName( name );
 627
 628                 if ( item ) {
 629                         item.toggleSelected( isSelected );
 630                 }
 631         };
 632
 633         /**
 634          * Toggle selected state of items by their names
 635          *
 636          * @param {Object} filterDef Filter definitions
 637          */
 638         mw.rcfilters.dm.FiltersViewModel.prototype.toggleFiltersSelected = function ( filterDef ) {
 639                 Object.keys( filterDef ).forEach( function ( name ) {
 640                         this.toggleFilterSelected( name, filterDef[ name ] );
 641                 }.bind( this ) );
 642         };
 643
 644         /**
 645          * Get a group model from its name
 646          *
 647          * @param {string} groupName Group name
 648          * @return {mw.rcfilters.dm.FilterGroup} Group model
 649          */
 650         mw.rcfilters.dm.FiltersViewModel.prototype.getGroup = function ( groupName ) {
 651                 return this.groups[ groupName ];
 652         };
 653
 654         /**
 655          * Get all filters within a specified group by its name
 656          *
 657          * @param {string} groupName Group name
 658          * @return {mw.rcfilters.dm.FilterItem[]} Filters belonging to this group
 659          */
 660         mw.rcfilters.dm.FiltersViewModel.prototype.getGroupFilters = function ( groupName ) {
 661                 return ( this.getGroup( groupName ) && this.getGroup( groupName ).getItems() ) || [];
 662         };
 663
 664         /**
 665          * Find items whose labels match the given string
 666          *
 667          * @param {string} query Search string
 668          * @param {boolean} [returnFlat] Return a flat array. If false, the result
 669          *  is an object whose keys are the group names and values are an array of
 670          *  filters per group. If set to true, returns an array of filters regardless
 671          *  of their groups.
 672          * @return {Object} An object of items to show
 673          *  arranged by their group names
 674          */
 675         mw.rcfilters.dm.FiltersViewModel.prototype.findMatches = function ( query, returnFlat ) {
 676                 var i,
 677                         groupTitle,
 678                         result = {},
 679                         flatResult = [],
 680                         items = this.getItems();
 681
 682                 // Normalize so we can search strings regardless of case
 683                 query = query.toLowerCase();
 684
 685                 // item label starting with the query string
 686                 for ( i = 0; i < items.length; i++ ) {
 687                         if ( items[ i ].getLabel().toLowerCase().indexOf( query ) === 0 ) {
 688                                 result[ items[ i ].getGroupName() ] = result[ items[ i ].getGroupName() ] || [];
 689                                 result[ items[ i ].getGroupName() ].push( items[ i ] );
 690                                 flatResult.push( items[ i ] );
 691                         }
 692                 }
 693
 694                 if ( $.isEmptyObject( result ) ) {
 695                         // item containing the query string in their label, description, or group title
 696                         for ( i = 0; i < items.length; i++ ) {
 697                                 groupTitle = items[ i ].getGroupModel().getTitle();
 698                                 if (
 699                                         items[ i ].getLabel().toLowerCase().indexOf( query ) > -1 ||
 700                                         items[ i ].getDescription().toLowerCase().indexOf( query ) > -1 ||
 701                                         groupTitle.toLowerCase().indexOf( query ) > -1
 702                                 ) {
 703                                         result[ items[ i ].getGroupName() ] = result[ items[ i ].getGroupName() ] || [];
 704                                         result[ items[ i ].getGroupName() ].push( items[ i ] );
 705                                         flatResult.push( items[ i ] );
 706                                 }
 707                         }
 708                 }
 709
 710                 return returnFlat ? flatResult : result;
 711         };
 712
 713         /**
 714          * Get items that are highlighted
 715          *
 716          * @return {mw.rcfilters.dm.FilterItem[]} Highlighted items
 717          */
 718         mw.rcfilters.dm.FiltersViewModel.prototype.getHighlightedItems = function () {
 719                 return this.getItems().filter( function ( filterItem ) {
 720                         return filterItem.isHighlightSupported() &&
 721                                 filterItem.getHighlightColor();
 722                 } );
 723         };
 724
 725         /**
 726          * Get items that allow highlights even if they're not currently highlighted
 727          *
 728          * @return {mw.rcfilters.dm.FilterItem[]} Items supporting highlights
 729          */
 730         mw.rcfilters.dm.FiltersViewModel.prototype.getItemsSupportingHighlights = function () {
 731                 return this.getItems().filter( function ( filterItem ) {
 732                         return filterItem.isHighlightSupported();
 733                 } );
 734         };
 735
 736         /**
 737          * Toggle the highlight feature on and off.
 738          * Propagate the change to filter items.
 739          *
 740          * @param {boolean} enable Highlight should be enabled
 741          * @fires highlightChange
 742          */
 743         mw.rcfilters.dm.FiltersViewModel.prototype.toggleHighlight = function ( enable ) {
 744                 enable = enable === undefined ? !this.highlightEnabled : enable;
 745
 746                 if ( this.highlightEnabled !== enable ) {
 747                         this.highlightEnabled = enable;
 748
 749                         this.getItems().forEach( function ( filterItem ) {
 750                                 filterItem.toggleHighlight( this.highlightEnabled );
 751                         }.bind( this ) );
 752
 753                         this.emit( 'highlightChange', this.highlightEnabled );
 754                 }
 755         };
 756
 757         /**
 758          * Check if the highlight feature is enabled
 759          * @return {boolean}
 760          */
 761         mw.rcfilters.dm.FiltersViewModel.prototype.isHighlightEnabled = function () {
 762                 return !!this.highlightEnabled;
 763         };
 764
 765         /**
 766          * Set highlight color for a specific filter item
 767          *
 768          * @param {string} filterName Name of the filter item
 769          * @param {string} color Selected color
 770          */
 771         mw.rcfilters.dm.FiltersViewModel.prototype.setHighlightColor = function ( filterName, color ) {
 772                 this.getItemByName( filterName ).setHighlightColor( color );
 773         };
 774
 775         /**
 776          * Clear highlight for a specific filter item
 777          *
 778          * @param {string} filterName Name of the filter item
 779          */
 780         mw.rcfilters.dm.FiltersViewModel.prototype.clearHighlightColor = function ( filterName ) {
 781                 this.getItemByName( filterName ).clearHighlightColor();
 782         };
 783
 784         /**
 785          * Clear highlight for all filter items
 786          */
 787         mw.rcfilters.dm.FiltersViewModel.prototype.clearAllHighlightColors = function () {
 788                 this.getItems().forEach( function ( filterItem ) {
 789                         filterItem.clearHighlightColor();
 790                 } );
 791         };
 792 }( mediaWiki, jQuery ) );