3 * View model for the filters selection and display
5 * @mixins OO.EventEmitter
6 * @mixins OO.EmitterList
10 mw
.rcfilters
.dm
.FiltersViewModel
= function MwRcfiltersDmFiltersViewModel() {
12 OO
.EventEmitter
.call( this );
13 OO
.EmitterList
.call( this );
16 this.defaultParams
= {};
17 this.defaultFiltersEmpty
= null;
18 this.highlightEnabled
= false;
19 this.parameterMap
= {};
22 this.aggregate( { update
: 'filterItemUpdate' } );
23 this.connect( this, { filterItemUpdate
: [ 'emit', 'itemUpdate' ] } );
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
);
36 * Filter list is initialized
41 * @param {mw.rcfilters.dm.FilterItem} item Filter item updated
43 * Filter item has changed
47 * @event highlightChange
48 * @param {boolean} Highlight feature is enabled
50 * Highlight feature has been toggled enabled or disabled
56 * Re-assess the states of filter items based on the interactions between them
58 * @param {mw.rcfilters.dm.FilterItem} [item] Changed item. If not given, the
59 * method will go over the state of all items
61 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.reassessFilterInteractions = function ( item
) {
64 iterationItems
= item
!== undefined ? [ item
] : this.getItems();
66 iterationItems
.forEach( function ( checkedItem
) {
67 var allCheckedItems
= checkedItem
.getSubset().concat( [ checkedItem
.getName() ] ),
68 groupModel
= checkedItem
.getGroupModel();
70 // Check for subsets (included filters) plus the item itself:
71 allCheckedItems
.forEach( function ( filterItemName
) {
72 var itemInSubset
= model
.getItemByName( filterItemName
);
74 itemInSubset
.toggleIncluded(
75 // If any of itemInSubset's supersets are selected, this item
77 itemInSubset
.getSuperset().some( function ( supersetName
) {
78 return ( model
.getItemByName( supersetName
).isSelected() );
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
);
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();
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
);
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.
113 // For example, see two groups with conflicts:
116 // name: 'experienced',
117 // conflicts: [ 'unregistered' ]
122 // name: 'registered',
125 // name: 'unregistered',
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.
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
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
);
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
154 // Toggle the item state
155 filterItem
.toggleConflicted( inConflict
);
160 * Get whether the model has any conflict in its items
162 * @return {boolean} There is a conflict
164 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.hasConflict = function () {
165 return this.getItems().some( function ( filterItem
) {
166 return filterItem
.isSelected() && filterItem
.isConflicted();
171 * Get the first item with a current conflict
173 * @return {mw.rcfilters.dm.FilterItem} Conflicted item
175 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getFirstConflictedItem = function () {
178 $.each( this.getItems(), function ( index
, filterItem
) {
179 if ( filterItem
.isSelected() && filterItem
.isConflicted() ) {
180 conflictedItem
= filterItem
;
185 return conflictedItem
;
189 * Set filters and preserve a group relationship based on
190 * the definition given by an object
192 * @param {Array} filters Filter group definition
194 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.initializeFilters = function ( filters
) {
195 var filterItem
, filterConflictResult
, groupConflictResult
,
198 groupConflictMap
= {},
199 filterConflictMap
= {},
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.
207 * @param {Object} obj Conflict definition
208 * @return {Object} Expanded conflict definition
210 expandConflictDefinitions = function ( obj
) {
213 $.each( obj
, function ( key
, conflicts
) {
215 adjustedConflicts
= {};
217 conflicts
.forEach( function ( conflict
) {
220 if ( conflict
.filter
) {
221 filterName
= model
.groups
[ conflict
.group
].getPrefixedName( conflict
.filter
);
222 filter
= model
.getItemByName( filterName
);
225 adjustedConflicts
[ filterName
] = $.extend(
234 // This conflict is for an entire group. Split it up to
235 // represent each filter
237 // Get the relevant group items
238 model
.groups
[ conflict
.group
].getItems().forEach( function ( groupItem
) {
239 // Rebuild the conflict
240 adjustedConflicts
[ groupItem
.getName() ] = $.extend(
244 filter
: groupItem
.getName(),
252 result
[ key
] = adjustedConflicts
;
262 filters
.forEach( function ( data
) {
266 if ( !model
.groups
[ group
] ) {
267 model
.groups
[ group
] = new mw
.rcfilters
.dm
.FilterGroup( group
, {
269 title
: mw
.msg( data
.title
),
270 separator
: data
.separator
,
271 fullCoverage
: !!data
.fullCoverage
,
273 body
: data
.whatsThisBody
,
274 header
: data
.whatsThisHeader
,
275 linkText
: data
.whatsThisLinkText
,
276 url
: data
.whatsThisUrl
280 model
.groups
[ group
].initializeFilters( data
.filters
, data
.default );
281 items
= items
.concat( model
.groups
[ group
].getItems() );
284 if ( data
.conflicts
) {
286 groupConflictMap
[ group
] = data
.conflicts
;
289 for ( i
= 0; i
< data
.filters
.length
; i
++ ) {
291 if ( data
.filters
[ i
].conflicts
) {
292 filterItem
= model
.groups
[ group
].getItemByParamName( data
.filters
[ i
].name
);
293 filterConflictMap
[ filterItem
.getName() ] = data
.filters
[ i
].conflicts
;
298 // Add item references to the model, for lookup
299 this.addItems( items
);
302 groupConflictResult
= expandConflictDefinitions( groupConflictMap
);
303 filterConflictResult
= expandConflictDefinitions( filterConflictMap
);
305 // Set conflicts for groups
306 $.each( groupConflictResult
, function ( group
, conflicts
) {
307 model
.groups
[ group
].setConflicts( conflicts
);
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
);
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
;
324 } else if ( groupModel
.getType() === 'string_options' ) {
326 model
.parameterMap
[ groupModel
.getName() ] = groupModel
;
330 // Finish initialization
331 this.emit( 'initialize' );
335 * Get the names of all available filters
337 * @return {string[]} An array of filter names
339 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getFilterNames = function () {
340 return this.getItems().map( function ( item
) { return item
.getName(); } );
344 * Get the object that defines groups by their name.
346 * @return {Object} Filter groups
348 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getFilterGroups = function () {
353 * Get the value of a specific parameter
355 * @param {string} name Parameter name
356 * @return {number|string} Parameter value
358 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getParamValue = function ( name
) {
359 return this.parameters
[ name
];
363 * Get the current selected state of the filters
365 * @return {Object} Filters selected state
367 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getSelectedState = function () {
369 items
= this.getItems(),
372 for ( i
= 0; i
< items
.length
; i
++ ) {
373 result
[ items
[ i
].getName() ] = items
[ i
].isSelected();
380 * Get the current full state of the filters
382 * @return {Object} Filters full state
384 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getFullState = function () {
386 items
= this.getItems(),
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()
401 * Get an object representing default parameters state
403 * @return {Object} Default parameter values
405 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getDefaultParams = function () {
408 // Get default filter state
409 $.each( this.groups
, function ( name
, model
) {
410 result
= $.extend( true, {}, result
, model
.getDefaultParams() );
413 // Get default highlight state
414 result
= $.extend( true, {}, result
, this.getHighlightParameters() );
420 * Analyze the groups and their filters and output an object representing
421 * the state of the parameters they represent.
423 * @param {Object} [filterDefinition] An object defining the filter values,
424 * keyed by filter names.
425 * @return {Object} Parameter state object
427 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getParametersFromFilters = function ( filterDefinition
) {
428 var groupItemDefinition
,
430 groupItems
= this.getFilterGroups();
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() ];
446 $.each( groupItems
, function ( group
, model
) {
449 model
.getParamRepresentation(
450 groupItemDefinition
?
451 groupItemDefinition
[ group
] : null
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.
463 * @param {Object} params Parameters query object
464 * @return {Object} Filter state object
466 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getFiltersFromParameters = function ( params
) {
471 // Go over the given parameters, break apart to groupings
472 // The resulting object represents the group with its parameter
473 // values. For example:
480 // group2: "param4|param5"
482 $.each( params
, function ( paramName
, paramValue
) {
483 var itemOrGroup
= model
.parameterMap
[ paramName
];
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
;
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
] ) );
506 * Get the highlight parameters based on current filter configuration
508 * @return {Object} Object where keys are "<filter name>_color" and values
509 * are the selected highlight colors.
511 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getHighlightParameters = function () {
514 this.getItems().forEach( function ( filterItem
) {
515 result
[ filterItem
.getName() + '_color' ] = filterItem
.getHighlightColor() || null;
517 result
.highlight
= String( Number( this.isHighlightEnabled() ) );
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.
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
535 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.extractHighlightValues = function ( representation
) {
538 this.getItems().forEach( function ( filterItem
) {
539 var highlightName
= filterItem
.getName() + '_color';
540 result
[ highlightName
] = representation
[ highlightName
] || null;
547 * Sanitize value group of a string_option groups type
548 * Remove duplicates and make sure to only use valid
552 * @param {string} groupName Group name
553 * @param {string[]} valueArray Array of values
554 * @return {string[]} Array of valid values
556 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.sanitizeStringOptionGroup = function ( groupName
, valueArray
) {
557 var validNames
= this.getGroupFilters( groupName
).map( function ( filterItem
) {
558 return filterItem
.getParamName();
561 return mw
.rcfilters
.utils
.normalizeParamOptions( valueArray
, validNames
);
565 * Check whether the current filter state is set to all false.
567 * @return {boolean} Current filters are all empty
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();
578 * Check whether the default values of the filters are all false.
580 * @return {boolean} Default filters are all false
582 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.areDefaultFiltersEmpty = function () {
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
];
594 return this.defaultFiltersEmpty
;
598 * Get the item that matches the given name
600 * @param {string} name Filter name
601 * @return {mw.rcfilters.dm.FilterItem} Filter item
603 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getItemByName = function ( name
) {
604 return this.getItems().filter( function ( item
) {
605 return name
=== item
.getName();
610 * Set all filters to false or empty/all
611 * This is equivalent to display all.
613 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.emptyAllFilters = function () {
614 this.getItems().forEach( function ( filterItem
) {
615 this.toggleFilterSelected( filterItem
.getName(), false );
620 * Toggle selected state of one item
622 * @param {string} name Name of the filter item
623 * @param {boolean} [isSelected] Filter selected state
625 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.toggleFilterSelected = function ( name
, isSelected
) {
626 var item
= this.getItemByName( name
);
629 item
.toggleSelected( isSelected
);
634 * Toggle selected state of items by their names
636 * @param {Object} filterDef Filter definitions
638 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.toggleFiltersSelected = function ( filterDef
) {
639 Object
.keys( filterDef
).forEach( function ( name
) {
640 this.toggleFilterSelected( name
, filterDef
[ name
] );
645 * Get a group model from its name
647 * @param {string} groupName Group name
648 * @return {mw.rcfilters.dm.FilterGroup} Group model
650 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getGroup = function ( groupName
) {
651 return this.groups
[ groupName
];
655 * Get all filters within a specified group by its name
657 * @param {string} groupName Group name
658 * @return {mw.rcfilters.dm.FilterItem[]} Filters belonging to this group
660 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getGroupFilters = function ( groupName
) {
661 return ( this.getGroup( groupName
) && this.getGroup( groupName
).getItems() ) || [];
665 * Find items whose labels match the given string
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
672 * @return {Object} An object of items to show
673 * arranged by their group names
675 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.findMatches = function ( query
, returnFlat
) {
680 items
= this.getItems();
682 // Normalize so we can search strings regardless of case
683 query
= query
.toLowerCase();
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
] );
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();
699 items
[ i
].getLabel().toLowerCase().indexOf( query
) > -1 ||
700 items
[ i
].getDescription().toLowerCase().indexOf( query
) > -1 ||
701 groupTitle
.toLowerCase().indexOf( query
) > -1
703 result
[ items
[ i
].getGroupName() ] = result
[ items
[ i
].getGroupName() ] || [];
704 result
[ items
[ i
].getGroupName() ].push( items
[ i
] );
705 flatResult
.push( items
[ i
] );
710 return returnFlat
? flatResult
: result
;
714 * Get items that are highlighted
716 * @return {mw.rcfilters.dm.FilterItem[]} Highlighted items
718 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getHighlightedItems = function () {
719 return this.getItems().filter( function ( filterItem
) {
720 return filterItem
.isHighlightSupported() &&
721 filterItem
.getHighlightColor();
726 * Get items that allow highlights even if they're not currently highlighted
728 * @return {mw.rcfilters.dm.FilterItem[]} Items supporting highlights
730 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.getItemsSupportingHighlights = function () {
731 return this.getItems().filter( function ( filterItem
) {
732 return filterItem
.isHighlightSupported();
737 * Toggle the highlight feature on and off.
738 * Propagate the change to filter items.
740 * @param {boolean} enable Highlight should be enabled
741 * @fires highlightChange
743 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.toggleHighlight = function ( enable
) {
744 enable
= enable
=== undefined ? !this.highlightEnabled
: enable
;
746 if ( this.highlightEnabled
!== enable
) {
747 this.highlightEnabled
= enable
;
749 this.getItems().forEach( function ( filterItem
) {
750 filterItem
.toggleHighlight( this.highlightEnabled
);
753 this.emit( 'highlightChange', this.highlightEnabled
);
758 * Check if the highlight feature is enabled
761 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.isHighlightEnabled = function () {
762 return !!this.highlightEnabled
;
766 * Set highlight color for a specific filter item
768 * @param {string} filterName Name of the filter item
769 * @param {string} color Selected color
771 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.setHighlightColor = function ( filterName
, color
) {
772 this.getItemByName( filterName
).setHighlightColor( color
);
776 * Clear highlight for a specific filter item
778 * @param {string} filterName Name of the filter item
780 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.clearHighlightColor = function ( filterName
) {
781 this.getItemByName( filterName
).clearHighlightColor();
785 * Clear highlight for all filter items
787 mw
.rcfilters
.dm
.FiltersViewModel
.prototype.clearAllHighlightColors = function () {
788 this.getItems().forEach( function ( filterItem
) {
789 filterItem
.clearHighlightColor();
792 }( mediaWiki
, jQuery
) );