resources/src/mediawiki.rcfilters/dm/ItemModel.js

   1 /**
   2  * RCFilter base item model.
   3  *
   4  * @class mw.rcfilters.dm.ItemModel
   5  * @ignore
   6  * @mixes OO.EventEmitter
   7  *
   8  * @param {string} param Filter param name
   9  * @param {Object} config Configuration object
  10  * @param {string} [config.label] The label for the filter
  11  * @param {string} [config.description] The description of the filter
  12  * @param {string|Object} [config.labelPrefixKey] An i18n key defining the prefix label for this
  13  *  group. If the prefix has 'invert' state, the parameter is expected to be an object
  14  *  with 'default' and 'inverted' as keys.
  15  * @param {boolean} [config.active=true] The filter is active and affecting the result
  16  * @param {boolean} [config.selected] The item is selected
  17  * @param {any} [config.value] The value of this item
  18  * @param {string} [config.namePrefix='item_'] A prefix to add to the param name to act as a unique
  19  *  identifier
  20  * @param {string} [config.cssClass] The class identifying the results that match this filter
  21  * @param {string|null} [config.helpLink] Link to a help page for this filter
  22  * @param {string[]} [config.identifiers] An array of identifiers for this item. They will be
  23  *  added and considered in the view.
  24  * @param {string} [config.defaultHighlightColor=null] If set, highlight this filter by default with this color
  25  */
  26 const ItemModel = function MwRcfiltersDmItemModel( param, config ) {
  27         config = config || {};
  28
  29         // Mixin constructor
  30         OO.EventEmitter.call( this );
  31
  32         this.param = param;
  33         this.namePrefix = config.namePrefix || 'item_';
  34         this.name = this.namePrefix + param;
  35
  36         this.label = config.label || this.name;
  37         this.labelPrefixKey = config.labelPrefixKey;
  38         this.description = config.description || '';
  39         this.setValue( config.value || config.selected );
  40
  41         this.identifiers = config.identifiers || [];
  42
  43         // Highlight
  44         this.cssClass = config.cssClass;
  45         this.helpLink = config.helpLink;
  46         this.highlightColor = config.defaultHighlightColor || null;
  47 };
  48
  49 /* Initialization */
  50
  51 OO.initClass( ItemModel );
  52 OO.mixinClass( ItemModel, OO.EventEmitter );
  53
  54 /* Events */
  55
  56 /**
  57  * The state of this filter has changed.
  58  *
  59  * @event update
  60  * @ignore
  61  */
  62
  63 /* Methods */
  64
  65 /**
  66  * Return the representation of the state of this item.
  67  *
  68  * @return {Object} State of the object
  69  */
  70 ItemModel.prototype.getState = function () {
  71         return {
  72                 selected: this.isSelected()
  73         };
  74 };
  75
  76 /**
  77  * Get the name of this filter
  78  *
  79  * @return {string} Filter name
  80  */
  81 ItemModel.prototype.getName = function () {
  82         return this.name;
  83 };
  84
  85 /**
  86  * Get the message key to use to wrap the label. This message takes the label as a parameter.
  87  *
  88  * @param {boolean} inverted Whether this item should be considered inverted
  89  * @return {string|null} Message key, or null if no message
  90  */
  91 ItemModel.prototype.getLabelMessageKey = function ( inverted ) {
  92         if ( this.labelPrefixKey ) {
  93                 if ( typeof this.labelPrefixKey === 'string' ) {
  94                         return this.labelPrefixKey;
  95                 }
  96                 return this.labelPrefixKey[
  97                         // Only use inverted-prefix if the item is selected
  98                         // Highlight-only an inverted item makes no sense
  99                         inverted && this.isSelected() ?
 100                                 'inverted' : 'default'
 101                 ];
 102         }
 103         return null;
 104 };
 105
 106 /**
 107  * Get the param name or value of this filter
 108  *
 109  * @return {string} Filter param name
 110  */
 111 ItemModel.prototype.getParamName = function () {
 112         return this.param;
 113 };
 114
 115 /**
 116  * Get the message representing the state of this model.
 117  *
 118  * @return {string} State message
 119  */
 120 ItemModel.prototype.getStateMessage = function () {
 121         // Display description
 122         return this.getDescription();
 123 };
 124
 125 /**
 126  * Get the label of this filter
 127  *
 128  * @return {string} Filter label
 129  */
 130 ItemModel.prototype.getLabel = function () {
 131         return this.label;
 132 };
 133
 134 /**
 135  * Get the description of this filter
 136  *
 137  * @return {string} Filter description
 138  */
 139 ItemModel.prototype.getDescription = function () {
 140         return this.description;
 141 };
 142
 143 /**
 144  * Get the default value of this filter
 145  *
 146  * @return {boolean} Filter default
 147  */
 148 ItemModel.prototype.getDefault = function () {
 149         return this.default;
 150 };
 151
 152 /**
 153  * Get the selected state of this filter
 154  *
 155  * @return {boolean} Filter is selected
 156  */
 157 ItemModel.prototype.isSelected = function () {
 158         return !!this.value;
 159 };
 160
 161 /**
 162  * Toggle the selected state of the item
 163  *
 164  * @param {boolean} [isSelected] Filter is selected
 165  * @fires update
 166  */
 167 ItemModel.prototype.toggleSelected = function ( isSelected ) {
 168         isSelected = isSelected === undefined ? !this.isSelected() : isSelected;
 169         this.setValue( isSelected );
 170 };
 171
 172 /**
 173  * Get the value
 174  *
 175  * @return {any}
 176  */
 177 ItemModel.prototype.getValue = function () {
 178         return this.value;
 179 };
 180
 181 /**
 182  * Convert a given value to the appropriate representation based on group type
 183  *
 184  * @param {any} value
 185  * @return {any}
 186  */
 187 ItemModel.prototype.coerceValue = function ( value ) {
 188         return this.getGroupModel().getType() === 'any_value' ? value : !!value;
 189 };
 190
 191 /**
 192  * Set the value
 193  *
 194  * @param {any} newValue
 195  */
 196 ItemModel.prototype.setValue = function ( newValue ) {
 197         newValue = this.coerceValue( newValue );
 198         if ( this.value !== newValue ) {
 199                 this.value = newValue;
 200                 this.emit( 'update' );
 201         }
 202 };
 203
 204 /**
 205  * Set the highlight color
 206  *
 207  * @param {string|null} highlightColor
 208  */
 209 ItemModel.prototype.setHighlightColor = function ( highlightColor ) {
 210         if ( !this.isHighlightSupported() ) {
 211                 return;
 212         }
 213         // If the highlight color on the item and in the parameter is null/undefined, return early.
 214         if ( !this.highlightColor && !highlightColor ) {
 215                 return;
 216         }
 217
 218         if ( this.highlightColor !== highlightColor ) {
 219                 this.highlightColor = highlightColor;
 220                 this.emit( 'update' );
 221         }
 222 };
 223
 224 /**
 225  * Clear the highlight color
 226  */
 227 ItemModel.prototype.clearHighlightColor = function () {
 228         this.setHighlightColor( null );
 229 };
 230
 231 /**
 232  * Get the highlight color, or null if none is configured
 233  *
 234  * @return {string|null}
 235  */
 236 ItemModel.prototype.getHighlightColor = function () {
 237         return this.highlightColor;
 238 };
 239
 240 /**
 241  * Get the CSS class that matches changes that fit this filter
 242  * or null if none is configured
 243  *
 244  * @return {string|null}
 245  */
 246 ItemModel.prototype.getCssClass = function () {
 247         return this.cssClass;
 248 };
 249
 250 /**
 251  * Get a link to a help page for this filter
 252  * or null if none is configured
 253  *
 254  * @return {string|null}
 255  */
 256 ItemModel.prototype.getHelpLink = function () {
 257         return this.helpLink;
 258 };
 259
 260 /**
 261  * Get the item's identifiers
 262  *
 263  * @return {string[]}
 264  */
 265 ItemModel.prototype.getIdentifiers = function () {
 266         return this.identifiers;
 267 };
 268
 269 /**
 270  * Check if the highlight feature is supported for this filter
 271  *
 272  * @return {boolean}
 273  */
 274 ItemModel.prototype.isHighlightSupported = function () {
 275         return !!this.getCssClass() && !OO.ui.isMobile();
 276 };
 277
 278 /**
 279  * Check if the filter is currently highlighted
 280  *
 281  * @return {boolean}
 282  */
 283 ItemModel.prototype.isHighlighted = function () {
 284         return !!this.getHighlightColor();
 285 };
 286
 287 module.exports = ItemModel;