[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('slider-value-range', function (Y, NAME) {
   9  
  10  /**
  11   * Adds value support for Slider as a range of integers between a configured
  12   * minimum and maximum value.  For use with <code>Y.Base.build(..)</code> to
  13   * add the plumbing to <code>Y.SliderBase</code>.
  14   *
  15   * @module slider
  16   * @submodule slider-value-range
  17   */
  18  
  19  // Constants for compression or performance
  20  var MIN       = 'min',
  21      MAX       = 'max',
  22      VALUE     = 'value',
  23  //     MINORSTEP = 'minorStep',
  24  //     MAJORSTEP = 'majorStep',
  25  
  26      round = Math.round;
  27  
  28  /**
  29   * One class of value algorithm that can be built onto SliderBase.  By default,
  30   * values range between 0 and 100, but you can configure these on the
  31   * built Slider class by setting the <code>min</code> and <code>max</code>
  32   * configurations.  Set the initial value (will cause the thumb to move to the
  33   * appropriate location on the rail) in configuration as well if appropriate.
  34   *
  35   * @class SliderValueRange
  36   */
  37  function SliderValueRange() {
  38      this._initSliderValueRange();
  39  }
  40  
  41  Y.SliderValueRange = Y.mix( SliderValueRange, {
  42  
  43      // Prototype properties and methods that will be added onto host class
  44      prototype: {
  45  
  46          /**
  47           * Factor used to translate value -&gt; position -&gt; value.
  48           *
  49           * @property _factor
  50           * @type {Number}
  51           * @protected
  52           */
  53          _factor: 1,
  54  
  55          /**
  56           * Stub for construction logic.  Override if extending this class and
  57           * you need to set something up during the initializer phase.
  58           *
  59           * @method _initSliderValueRange
  60           * @protected
  61           */
  62          _initSliderValueRange: function () {},
  63  
  64          /**
  65           * Override of stub method in SliderBase that is called at the end of
  66           * its bindUI stage of render().  Subscribes to internal events to
  67           * trigger UI and related state updates.
  68           *
  69           * @method _bindValueLogic
  70           * @protected
  71           */
  72          _bindValueLogic: function () {
  73              this.after( {
  74                  minChange  : this._afterMinChange,
  75                  maxChange  : this._afterMaxChange,
  76                  valueChange: this._afterValueChange
  77              } );
  78          },
  79  
  80          /**
  81           * Move the thumb to appropriate position if necessary.  Also resets
  82           * the cached offsets and recalculates the conversion factor to
  83           * translate position to value.
  84           *
  85           * @method _syncThumbPosition
  86           * @protected
  87           */
  88          _syncThumbPosition: function () {
  89              this._calculateFactor();
  90  
  91              this._setPosition( this.get( VALUE ) );
  92          },
  93  
  94          /**
  95           * Calculates and caches
  96           * (range between max and min) / (rail length)
  97           * for fast runtime calculation of position -&gt; value.
  98           *
  99           * @method _calculateFactor
 100           * @protected
 101           */
 102          _calculateFactor: function () {
 103              var length    = this.get( 'length' ),
 104                  thumbSize = this.thumb.getStyle( this._key.dim ),
 105                  min       = this.get( MIN ),
 106                  max       = this.get( MAX );
 107  
 108              // The default thumb width is based on Sam skin's thumb dimension.
 109              // This attempts to allow for rendering off-DOM, then attaching
 110              // without the need to call syncUI().  It is still recommended
 111              // to call syncUI() in these cases though, just to be sure.
 112              length = parseFloat( length ) || 150;
 113              thumbSize = parseFloat( thumbSize ) || 15;
 114  
 115              this._factor = ( max - min ) / ( length - thumbSize );
 116  
 117          },
 118  
 119          /**
 120           * Dispatch the new position of the thumb into the value setting
 121           * operations.
 122           *
 123           * @method _defThumbMoveFn
 124           * @param e { EventFacade } The host's thumbMove event
 125           * @protected
 126           */
 127          _defThumbMoveFn: function ( e ) {
 128              // To prevent set('value', x) from looping back around
 129              if (e.source !== 'set') {
 130                  this.set(VALUE, this._offsetToValue(e.offset));
 131              }
 132          },
 133  
 134          /**
 135           * <p>Converts a pixel position into a value.  Calculates current
 136           * thumb offset from the leading edge of the rail multiplied by the
 137           * ratio of <code>(max - min) / (constraining dim)</code>.</p>
 138           *
 139           * <p>Override this if you want to use a different value mapping
 140           * algorithm.</p>
 141           *
 142           * @method _offsetToValue
 143           * @param offset { Number } X or Y pixel offset
 144           * @return { mixed } Value corresponding to the provided pixel offset
 145           * @protected
 146           */
 147          _offsetToValue: function ( offset ) {
 148  
 149              var value = round( offset * this._factor ) + this.get( MIN );
 150  
 151              return round( this._nearestValue( value ) );
 152          },
 153  
 154          /**
 155           * Converts a value into a pixel offset for use in positioning
 156           * the thumb according to the reverse of the
 157           * <code>_offsetToValue( xy )</code> operation.
 158           *
 159           * @method _valueToOffset
 160           * @param val { Number } The value to map to pixel X or Y position
 161           * @return { Number } The pixel offset
 162           * @protected
 163           */
 164          _valueToOffset: function ( value ) {
 165              var offset = round( ( value - this.get( MIN ) ) / this._factor );
 166  
 167              return offset;
 168          },
 169  
 170          /**
 171           * Returns the current value.  Override this if you want to introduce
 172           * output formatting. Otherwise equivalent to slider.get( "value" );
 173           *
 174           * @method getValue
 175           * @return {Number}
 176           */
 177          getValue: function () {
 178              return this.get( VALUE );
 179          },
 180  
 181          /**
 182           * Updates the current value.  Override this if you want to introduce
 183           * input value parsing or preprocessing.  Otherwise equivalent to
 184           * slider.set( "value", v );
 185           *
 186           * @method setValue
 187           * @param val {Number} The new value
 188           * @return {Slider}
 189           * @chainable
 190           */
 191          setValue: function ( val ) {
 192              return this.set( VALUE, val );
 193          },
 194  
 195          /**
 196           * Update position according to new min value.  If the new min results
 197           * in the current value being out of range, the value is set to the
 198           * closer of min or max.
 199           *
 200           * @method _afterMinChange
 201           * @param e { EventFacade } The <code>min</code> attribute change event.
 202           * @protected
 203           */
 204          _afterMinChange: function ( e ) {
 205              this._verifyValue();
 206  
 207              this._syncThumbPosition();
 208          },
 209  
 210          /**
 211           * Update position according to new max value.  If the new max results
 212           * in the current value being out of range, the value is set to the
 213           * closer of min or max.
 214           *
 215           * @method _afterMaxChange
 216           * @param e { EventFacade } The <code>max</code> attribute change event.
 217           * @protected
 218           */
 219          _afterMaxChange: function ( e ) {
 220              this._verifyValue();
 221  
 222              this._syncThumbPosition();
 223          },
 224  
 225          /**
 226           * Verifies that the current value is within the min - max range.  If
 227           * not, value is set to either min or max, depending on which is
 228           * closer.
 229           *
 230           * @method _verifyValue
 231           * @protected
 232           */
 233          _verifyValue: function () {
 234              var value   = this.get( VALUE ),
 235                  nearest = this._nearestValue( value );
 236  
 237              if ( value !== nearest ) {
 238                  // @TODO Can/should valueChange, minChange, etc be queued
 239                  // events? To make dd.set( 'min', n ); execute after minChange
 240                  // subscribers before on/after valueChange subscribers.
 241                  this.set( VALUE, nearest );
 242              }
 243          },
 244  
 245          /**
 246           * Propagate change to the thumb position unless the change originated
 247           * from the thumbMove event.
 248           *
 249           * @method _afterValueChange
 250           * @param e { EventFacade } The <code>valueChange</code> event.
 251           * @protected
 252           */
 253          _afterValueChange: function ( e ) {
 254              var val = e.newVal;
 255              this._setPosition( val, { source: 'set' } );
 256          },
 257  
 258          /**
 259           * Positions the thumb and its ARIA attributes in accordance with the
 260           * translated value.
 261           *
 262           * @method _setPosition
 263           * @param value {Number} Value to translate to a pixel position
 264           * @param [options] {Object} Details object to pass to `_uiMoveThumb`
 265           * @protected
 266           */
 267          _setPosition: function ( value, options ) {
 268              this._uiMoveThumb( this._valueToOffset( value ), options );
 269              this.thumb.set('aria-valuenow', value);
 270              this.thumb.set('aria-valuetext', value);
 271          },
 272  
 273          /**
 274           * Validates new values assigned to <code>min</code> attribute.  Numbers
 275           * are acceptable.  Override this to enforce different rules.
 276           *
 277           * @method _validateNewMin
 278           * @param value {Any} Value assigned to <code>min</code> attribute.
 279           * @return {Boolean} True for numbers.  False otherwise.
 280           * @protected
 281           */
 282          _validateNewMin: function ( value ) {
 283              return Y.Lang.isNumber( value );
 284          },
 285  
 286          /**
 287           * Validates new values assigned to <code>max</code> attribute.  Numbers
 288           * are acceptable.  Override this to enforce different rules.
 289           *
 290           * @method _validateNewMax
 291           * @param value { mixed } Value assigned to <code>max</code> attribute.
 292           * @return { Boolean } True for numbers.  False otherwise.
 293           * @protected
 294           */
 295          _validateNewMax: function ( value ) {
 296              return Y.Lang.isNumber( value );
 297          },
 298  
 299          /**
 300           * Restricts new values assigned to <code>value</code> attribute to be
 301           * between the configured <code>min</code> and <code>max</code>.
 302           * Rounds to nearest integer value.
 303           *
 304           * @method _setNewValue
 305           * @param value { Number } Value assigned to <code>value</code> attribute
 306           * @return { Number } Normalized and constrained value
 307           * @protected
 308           */
 309          _setNewValue: function ( value ) {
 310              if ( Y.Lang.isNumber( value ) ) {
 311                  return round( this._nearestValue( value ) );
 312              }
 313              return Y.Attribute.INVALID_VALUE;
 314          },
 315  
 316          /**
 317           * Returns the nearest valid value to the value input.  If the provided
 318           * value is outside the min - max range, accounting for min > max
 319           * scenarios, the nearest of either min or max is returned.  Otherwise,
 320           * the provided value is returned.
 321           *
 322           * @method _nearestValue
 323           * @param value { mixed } Value to test against current min - max range
 324           * @return { Number } Current min, max, or value if within range
 325           * @protected
 326           */
 327          _nearestValue: function ( value ) {
 328              var min = this.get( MIN ),
 329                  max = this.get( MAX ),
 330                  tmp;
 331  
 332              // Account for reverse value range (min > max)
 333              tmp = ( max > min ) ? max : min;
 334              min = ( max > min ) ? min : max;
 335              max = tmp;
 336  
 337              return ( value < min ) ?
 338                      min :
 339                      ( value > max ) ?
 340                          max :
 341                          value;
 342          }
 343  
 344      },
 345  
 346      /**
 347       * Attributes that will be added onto host class.
 348       *
 349       * @property ATTRS
 350       * @type {Object}
 351       * @static
 352       * @protected
 353       */
 354      ATTRS: {
 355          /**
 356           * The value associated with the farthest top, left position of the
 357           * rail.  Can be greater than the configured <code>max</code> if you
 358           * want values to increase from right-to-left or bottom-to-top.
 359           *
 360           * @attribute min
 361           * @type { Number }
 362           * @default 0
 363           */
 364          min: {
 365              value    : 0,
 366              validator: '_validateNewMin'
 367          },
 368  
 369          /**
 370           * The value associated with the farthest bottom, right position of
 371           * the rail.  Can be less than the configured <code>min</code> if
 372           * you want values to increase from right-to-left or bottom-to-top.
 373           *
 374           * @attribute max
 375           * @type { Number }
 376           * @default 100
 377           */
 378          max: {
 379              value    : 100,
 380              validator: '_validateNewMax'
 381          },
 382  
 383          /**
 384           * amount to increment/decrement the Slider value
 385           * when the arrow up/down/left/right keys are pressed
 386           *
 387           * @attribute minorStep
 388           * @type {Number}
 389           * @default 1
 390           */
 391          minorStep : {
 392              value: 1
 393          },
 394  
 395          /**
 396           * amount to increment/decrement the Slider value
 397           * when the page up/down keys are pressed
 398           *
 399           * @attribute majorStep
 400           * @type {Number}
 401           * @default 10
 402           */
 403          majorStep : {
 404              value: 10
 405          },
 406  
 407          /**
 408           * The value associated with the thumb's current position on the
 409           * rail. Defaults to the value inferred from the thumb's current
 410           * position. Specifying value in the constructor will move the
 411           * thumb to the position that corresponds to the supplied value.
 412           *
 413           * @attribute value
 414           * @type { Number }
 415           * @default (inferred from current thumb position)
 416           */
 417          value: {
 418              value : 0,
 419              setter: '_setNewValue'
 420          }
 421      }
 422  }, true );
 423  
 424  
 425  }, '3.17.2', {"requires": ["slider-base"]});