jssource/src_files/include/javascript/yui3/build/slider/slider.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('slider-base', function(Y) {
   9
  10 /**
  11  * Create a sliding value range input visualized as a draggable thumb on a
  12  * background element.
  13  *
  14  * @module slider
  15  * @submodule slider-base
  16  */
  17
  18 var INVALID_VALUE = Y.Attribute.INVALID_VALUE;
  19
  20 /**
  21  * Create a slider to represent an input control capable of representing a
  22  * series of intermediate states based on the position of the slider's thumb.
  23  * These states are typically aligned to a value algorithm whereby the thumb
  24  * position corresponds to a given value. Sliders may be oriented vertically or
  25  * horizontally, based on the <code>axis</code> configuration.
  26  *
  27  * @class SliderBase
  28  * @extends Widget
  29  * @param config {Object} Configuration object
  30  * @constructor
  31  */
  32 function SliderBase() {
  33     SliderBase.superclass.constructor.apply( this, arguments );
  34 }
  35
  36 Y.SliderBase = Y.extend( SliderBase, Y.Widget, {
  37
  38     // Y.Slider prototype
  39
  40     /**
  41      * Construction logic executed during Slider instantiation.
  42      *
  43      * @method initializer
  44      * @protected
  45      */
  46     initializer : function () {
  47         /**
  48          * The configured axis, stored for fast lookup since it's a writeOnce
  49          * attribute.  This is for use by extension classes.  For
  50          * implementation code, use <code>get( &quot;axis&quot; )</code> for
  51          * authoritative source.  Never write to this property.
  52          *
  53          * @property axis
  54          * @type {String}
  55          * @protected
  56          */
  57         this.axis = this.get( 'axis' );
  58
  59         /**
  60          * Cached fast access map for DOM properties and attributes that
  61          * pertain to accessing dimensional or positioning information
  62          * according to the Slider's axis (e.g. &quot;height&quot; vs.
  63          * &quot;width&quot;).  Extension classes should add to this collection
  64          * for axis related strings if necessary.
  65          *
  66          * @property _key
  67          * @type {Object}
  68          * @protected
  69          */
  70         this._key = {
  71             dim    : ( this.axis === 'y' ) ? 'height' : 'width',
  72             minEdge: ( this.axis === 'y' ) ? 'top'    : 'left',
  73             maxEdge: ( this.axis === 'y' ) ? 'bottom' : 'right',
  74             xyIndex: ( this.axis === 'y' ) ? 1 : 0
  75         };
  76
  77         /**
  78          * Signals that the thumb has moved.  Payload includes the thumb's
  79          * pixel offset from the top/left edge of the rail, and if triggered by
  80          * dragging the thumb, the <code>drag:drag</code> event.
  81          *
  82          * @event thumbMove
  83          * @param event {Event} The event object for the thumbMove with the
  84          *                      following extra properties:
  85          *  <dl>
  86          *      <dt>offset</dt>
  87          *          <dd>Pixel offset from top/left of the slider to the new
  88          *          thumb position</dd>
  89          *      <dt>ddEvent</dt>
  90          *          <dd><code>drag:drag</code> event from the thumb</dd>
  91          *  </dl>
  92          */
  93         this.publish( 'thumbMove', {
  94             defaultFn: this._defThumbMoveFn,
  95             queuable : true
  96         } );
  97     },
  98
  99     /**
 100      * Create the DOM structure for the Slider.
 101      *
 102      * @method renderUI
 103      * @protected
 104      */
 105     renderUI : function () {
 106         var contentBox = this.get( 'contentBox' );
 107
 108         /**
 109          * The Node instance of the Slider's rail element.  Do not write to
 110          * this property.
 111          *
 112          * @property rail
 113          * @type {Node}
 114          */
 115         this.rail = this.renderRail();
 116
 117         this._uiSetRailLength( this.get( 'length' ) );
 118
 119         /**
 120          * The Node instance of the Slider's thumb element.  Do not write to
 121          * this property.
 122          *
 123          * @property thumb
 124          * @type {Node}
 125          */
 126         this.thumb = this.renderThumb();
 127
 128         this.rail.appendChild( this.thumb );
 129         // @TODO: insert( contentBox, 'replace' ) or setContent?
 130         contentBox.appendChild( this.rail );
 131
 132         // <span class="yui3-slider-x">
 133         contentBox.addClass( this.getClassName( this.axis ) );
 134     },
 135
 136     /**
 137      * Creates the Slider rail DOM subtree for insertion into the Slider's
 138      * <code>contentBox</code>.  Override this method if you want to provide
 139      * the rail element (presumably from existing markup).
 140      *
 141      * @method renderRail
 142      * @return {Node} the rail node subtree
 143      */
 144     renderRail: function () {
 145         var minCapClass = this.getClassName( 'rail', 'cap', this._key.minEdge ),
 146             maxCapClass = this.getClassName( 'rail', 'cap', this._key.maxEdge );
 147
 148         return Y.Node.create(
 149             Y.substitute( this.RAIL_TEMPLATE, {
 150                 railClass      : this.getClassName( 'rail' ),
 151                 railMinCapClass: minCapClass,
 152                 railMaxCapClass: maxCapClass
 153             } ) );
 154     },
 155
 156     /**
 157      * Sets the rail length according to the <code>length</code> attribute.
 158      *
 159      * @method _uiSetRailLength
 160      * @param length {String} the length to apply to the rail style
 161      * @protected
 162      */
 163     _uiSetRailLength: function ( length ) {
 164         this.rail.setStyle( this._key.dim, length );
 165     },
 166
 167     /**
 168      * Creates the Slider thumb DOM subtree for insertion into the Slider's
 169      * rail.  Override this method if you want to provide the thumb element
 170      * (presumably from existing markup).
 171      *
 172      * @method renderThumb
 173      * @return {Node} the thumb node subtree
 174      */
 175     renderThumb: function () {
 176         this._initThumbUrl();
 177
 178         var imageUrl = this.get( 'thumbUrl' );
 179
 180         return Y.Node.create(
 181             Y.substitute( this.THUMB_TEMPLATE, {
 182                 thumbClass      : this.getClassName( 'thumb' ),
 183                 thumbShadowClass: this.getClassName( 'thumb', 'shadow' ),
 184                 thumbImageClass : this.getClassName( 'thumb', 'image' ),
 185                 thumbShadowUrl  : imageUrl,
 186                 thumbImageUrl   : imageUrl
 187             } ) );
 188     },
 189
 190     /**
 191      * Creates the Y.DD.Drag instance used to handle the thumb movement and
 192      * binds Slider interaction to the configured value model.
 193      *
 194      * @method bindUI
 195      * @protected
 196      */
 197     bindUI : function () {
 198         this._bindThumbDD();
 199
 200         this._bindValueLogic();
 201
 202         this.after( 'disabledChange', this._afterDisabledChange );
 203         this.after( 'lengthChange',   this._afterLengthChange );
 204     },
 205
 206     /**
 207      * Makes the thumb draggable and constrains it to the rail.
 208      *
 209      * @method _bindThumbDD
 210      * @protected
 211      */
 212     _bindThumbDD: function () {
 213         var config = { constrain: this.rail };
 214
 215         // { constrain: rail, stickX: true }
 216         config[ 'stick' + this.axis.toUpperCase() ] = true;
 217
 218         /**
 219          * The DD.Drag instance linked to the thumb node.
 220          *
 221          * @property _dd
 222          * @type {DD.Drag}
 223          * @protected
 224          */
 225         this._dd = new Y.DD.Drag( {
 226             node   : this.thumb,
 227             bubble : false,
 228             on     : {
 229                 'drag:start': Y.bind( this._onDragStart, this )
 230             },
 231             after  : {
 232                 'drag:drag': Y.bind( this._afterDrag,    this ),
 233                 'drag:end' : Y.bind( this._afterDragEnd, this )
 234             }
 235         } );
 236
 237         // Constrain the thumb to the rail
 238         this._dd.plug( Y.Plugin.DDConstrained, config );
 239     },
 240
 241     /**
 242      * Stub implementation.  Override this (presumably in a class extension) to
 243      * initialize any value logic that depends on the presence of the Drag
 244      * instance.
 245      *
 246      * @method _bindValueLogic
 247      * @protected
 248      */
 249     _bindValueLogic: function () {},
 250
 251     /**
 252      * Moves the thumb to pixel offset position along the rail.
 253      *
 254      * @method _uiMoveThumb
 255      * @param offset {Number} the pixel offset to set as left or top style
 256      * @protected
 257      */
 258     _uiMoveThumb: function ( offset ) {
 259         if ( this.thumb ) {
 260             this.thumb.setStyle( this._key.minEdge, offset + 'px' );
 261
 262
 263             this.fire( 'thumbMove', { offset: offset } );
 264         }
 265     },
 266
 267     /**
 268      * Dispatches the <code>slideStart</code> event.
 269      *
 270      * @method _onDragStart
 271      * @param e {Event} the <code>drag:start</code> event from the thumb
 272      * @protected
 273      */
 274     _onDragStart: function ( e ) {
 275         /**
 276          * Signals the beginning of a thumb drag operation.  Payload includes
 277          * the thumb's drag:start event.
 278          *
 279          * @event slideStart
 280          * @param event {Event} The event object for the slideStart with the
 281          *                      following extra properties:
 282          *  <dl>
 283          *      <dt>ddEvent</dt>
 284          *          <dd><code>drag:start</code> event from the thumb</dd>
 285          *  </dl>
 286          */
 287         this.fire( 'slideStart', { ddEvent: e } );
 288     },
 289
 290     /**
 291      * Dispatches the <code>thumbMove</code> event.
 292      *
 293      * @method _afterDrag
 294      * @param e {Event} the <code>drag:drag</code> event from the thumb
 295      * @protected
 296      */
 297     _afterDrag: function ( e ) {
 298         var thumbXY = e.info.xy[ this._key.xyIndex ],
 299             railXY  = e.target.con._regionCache[ this._key.minEdge ];
 300
 301         this.fire( 'thumbMove', {
 302             offset : (thumbXY - railXY),
 303             ddEvent: e
 304         } );
 305     },
 306
 307     /**
 308      * Dispatches the <code>slideEnd</code> event.
 309      *
 310      * @method _onDragEnd
 311      * @param e {Event} the <code>drag:end</code> event from the thumb
 312      * @protected
 313      */
 314     _afterDragEnd: function ( e ) {
 315         /**
 316          * Signals the end of a thumb drag operation.  Payload includes
 317          * the thumb's drag:end event.
 318          *
 319          * @event slideEnd
 320          * @param event {Event} The event object for the slideEnd with the
 321          *                      following extra properties:
 322          *  <dl>
 323          *      <dt>ddEvent</dt>
 324          *          <dd><code>drag:end</code> event from the thumb</dd>
 325          *  </dl>
 326          */
 327         this.fire( 'slideEnd', { ddEvent: e } );
 328     },
 329
 330     /**
 331      * Locks or unlocks the thumb.
 332      *
 333      * @method _afterDisabledChange
 334      * @param e {Event} The disabledChange event object
 335      * @protected
 336      */
 337     _afterDisabledChange: function ( e ) {
 338         this._dd.set( 'lock', e.newVal );
 339     },
 340
 341     /**
 342      * Handles changes to the <code>length</code> attribute.  By default, it
 343      * triggers an update to the UI.
 344      *
 345      * @method _afterLengthChange
 346      * @param e {Event} The lengthChange event object
 347      * @protected
 348      */
 349     _afterLengthChange: function ( e ) {
 350         if ( this.get( 'rendered' ) ) {
 351             this._uiSetRailLength( e.newVal );
 352
 353             this.syncUI();
 354         }
 355     },
 356
 357     /**
 358      * Synchronizes the DOM state with the attribute settings.
 359      *
 360      * @method syncUI
 361      */
 362     syncUI : function () {
 363         this._dd.con.resetCache();
 364
 365         this._syncThumbPosition();
 366
 367         // Forces a reflow of the bounding box to address IE8 inline-block
 368         // container not expanding correctly. bug 2527905
 369         //this.get('boundingBox').toggleClass('');
 370     },
 371
 372     /**
 373      * Stub implementation.  Override this (presumably in a class extension) to
 374      * ensure the thumb is in the correct position according to the value
 375      * alogorithm.
 376      * instance.
 377      *
 378      * @method _syncThumbPosition
 379      * @protected
 380      */
 381     _syncThumbPosition: function () {},
 382
 383     /**
 384      * Validates the axis is &quot;x&quot; or &quot;y&quot; (case insensitive).
 385      * Converts to lower case for storage.
 386      *
 387      * @method _setAxis
 388      * @param v {String} proposed value for the axis attribute
 389      * @return {String} lowercased first character of the input string
 390      * @protected
 391      */
 392     _setAxis : function (v) {
 393         v = ( v + '' ).toLowerCase();
 394
 395         return ( v === 'x' || v === 'y' ) ? v : INVALID_VALUE;
 396     },
 397
 398     /**
 399      * <p>Ensures the stored length value is a string with a quantity and unit.
 400      * Unit will be defaulted to &quot;px&quot; if not included.  Rejects
 401      * values less than or equal to 0 and those that don't at least start with
 402      * a number.</p>
 403      *
 404      * <p>Currently only pixel lengths are supported.</p>
 405      *
 406      * @method _setLength
 407      * @param v {String} proposed value for the length attribute
 408      * @return {String} the sanitized value
 409      * @protected
 410      */
 411     _setLength: function ( v ) {
 412         v = ( v + '' ).toLowerCase();
 413
 414         var length = parseFloat( v, 10 ),
 415             units  = v.replace( /[\d\.\-]/g, '' ) || this.DEF_UNIT;
 416
 417         return length > 0 ? ( length + units ) : INVALID_VALUE;
 418     },
 419
 420     /**
 421      * <p>Defaults the thumbURL attribute according to the current skin, or
 422      * &quot;sam&quot; if none can be determined.  Horizontal Sliders will have
 423      * their <code>thumbUrl</code> attribute set to</p>
 424      * <p><code>&quot;/<em>configured</em>/<em>yu</em>i/<em>builddi</em>r/slider/assets/skins/sam/thumb-x.png&quot;</code></p>
 425      * <p>And vertical thumbs will get</p>
 426      * <p><code>&quot;/<em>configured</em>/<em>yui</em>/<em>builddir</em>/slider/assets/skins/sam/thumb-y.png&quot;</code></p>
 427      *
 428      * @method _initThumbUrl
 429      * @protected
 430      */
 431     _initThumbUrl: function () {
 432         if (!this.get('thumbUrl')) {
 433             var skin = this.getSkinName() || 'sam',
 434                 base = Y.config.base;
 435
 436             // Unfortunate hack to avoid requesting image resources from the
 437             // combo service.  The combo service does not serve images.
 438             if (base.indexOf('http://yui.yahooapis.com/combo') === 0) {
 439                 base = 'http://yui.yahooapis.com/' + Y.version + '/build/';
 440             }
 441
 442             // <img src="/path/to/build/slider/assets/skins/sam/thumb-x.png">
 443             this.set('thumbUrl', base + 'slider/assets/skins/' +
 444                                  skin + '/thumb-' + this.axis + '.png');
 445
 446         }
 447     },
 448
 449     /**
 450      * Bounding box template that will contain the Slider's DOM subtree.  &lt;span&gt;s are used to support inline-block styling.
 451      *
 452      * @property BOUNDING_TEMPLATE
 453      * @type {String}
 454      * @default &lt;span>&lt;/span>
 455      */
 456     BOUNDING_TEMPLATE : '<span></span>',
 457
 458     /**
 459      * Content box template that will contain the Slider's rail and thumb.
 460      *
 461      * @property CONTENT_TEMPLATE
 462      * @type {String}
 463      * @default &lt;span>&lt;/span>
 464      */
 465     CONTENT_TEMPLATE  : '<span></span>',
 466
 467     /**
 468      * Rail template that will contain the end caps and the thumb.
 469      * {placeholder}s are used for template substitution at render time.
 470      *
 471      * @property RAIL_TEMPLATE
 472      * @type {String}
 473      * @default &lt;span class="{railClass}">&lt;span class="{railMinCapClass}">&lt;/span>&lt;span class="{railMaxCapClass}">&lt;/span>&lt;/span>
 474      */
 475     RAIL_TEMPLATE     : '<span class="{railClass}">' +
 476                             '<span class="{railMinCapClass}"></span>' +
 477                             '<span class="{railMaxCapClass}"></span>' +
 478                         '</span>',
 479
 480     /**
 481      * Thumb template that will contain the thumb image and shadow. &lt;img>
 482      * tags are used instead of background images to avoid a flicker bug in IE.
 483      * {placeholder}s are used for template substitution at render time.
 484      *
 485      * @property THUMB_TEMPLATE
 486      * @type {String}
 487      * @default &lt;span class="{thumbClass}" tabindex="-1">&lt;img src="{thumbShadowUrl}" alt="Slider thumb shadow" class="{thumbShadowClass}">&lt;img src="{thumbImageUrl}" alt="Slider thumb" class="{thumbImageClass}">&lt;/span>
 488      */
 489     THUMB_TEMPLATE    : '<span class="{thumbClass}" tabindex="-1">' +
 490                             '<img src="{thumbShadowUrl}" ' +
 491                                 'alt="Slider thumb shadow" ' +
 492                                 'class="{thumbShadowClass}">' +
 493                             '<img src="{thumbImageUrl}" ' +
 494                                 'alt="Slider thumb" ' +
 495                                 'class="{thumbImageClass}">' +
 496                         '</span>'
 497
 498 }, {
 499
 500     // Y.SliderBase static properties
 501
 502     /**
 503      * The identity of the widget.
 504      *
 505      * @property SliderBase.NAME
 506      * @type String
 507      * @default 'sliderBase'
 508      * @readOnly
 509      * @protected
 510      * @static
 511      */
 512     NAME : 'sliderBase',
 513
 514     /**
 515      * Static property used to define the default attribute configuration of
 516      * the Widget.
 517      *
 518      * @property SliderBase.ATTRS
 519      * @type {Object}
 520      * @protected
 521      * @static
 522      */
 523     ATTRS : {
 524
 525         /**
 526          * Axis upon which the Slider's thumb moves.  &quot;x&quot; for
 527          * horizontal, &quot;y&quot; for vertical.
 528          *
 529          * @attribute axis
 530          * @type {String}
 531          * @default &quot;x&quot;
 532          * @writeOnce
 533          */
 534         axis : {
 535             value     : 'x',
 536             writeOnce : true,
 537             setter    : '_setAxis',
 538             lazyAdd   : false
 539         },
 540
 541         /**
 542          * The length of the rail (exclusive of the end caps if positioned by
 543          * CSS).  This corresponds to the movable range of the thumb.
 544          *
 545          * @attribute length
 546          * @type {String | Number} e.g. "200px" or 200
 547          * @default 150px
 548          */
 549         length: {
 550             value: '150px',
 551             setter: '_setLength'
 552         },
 553
 554         /**
 555          * Path to the thumb image.  This will be used as both the thumb and
 556          * shadow as a sprite.  Defaults at render() to thumb-x.png or
 557          * thumb-y.png in the skin directory of the current skin.
 558          *
 559          * @attribute thumbUrl
 560          * @type {String}
 561          * @default thumb-x.png or thumb-y.png in the sam skin directory of the
 562          *          current build path for Slider
 563          */
 564         thumbUrl: {
 565             value: null,
 566             validator: Y.Lang.isString
 567         }
 568     }
 569 });
 570
 571
 572 }, '3.3.0' ,{requires:['widget', 'substitute', 'dd-constrain']});
 573 YUI.add('slider-value-range', function(Y) {
 574
 575 /**
 576  * Adds value support for Slider as a range of integers between a configured
 577  * minimum and maximum value.  For use with <code>Y.Base.build(..)</code> to
 578  * add the plumbing to <code>Y.SliderBase</code>.
 579  *
 580  * @module slider
 581  * @submodule slider-value-range
 582  */
 583
 584 // Constants for compression or performance
 585 var MIN       = 'min',
 586     MAX       = 'max',
 587     VALUE     = 'value',
 588
 589     round = Math.round;
 590
 591 /**
 592  * One class of value algorithm that can be built onto SliderBase.  By default,
 593  * values range between 0 and 100, but you can configure these on the
 594  * built Slider class by setting the <code>min</code> and <code>max</code>
 595  * configurations.  Set the initial value (will cause the thumb to move to the
 596  * appropriate location on the rail) in configuration as well if appropriate.
 597  *
 598  * @class SliderValueRange
 599  */
 600 function SliderValueRange() {
 601     this._initSliderValueRange();
 602 }
 603
 604 Y.SliderValueRange = Y.mix( SliderValueRange, {
 605
 606     // Prototype properties and methods that will be added onto host class
 607     prototype: {
 608
 609         /**
 610          * Factor used to translate value -&gt; position -&gt; value.
 611          *
 612          * @property _factor
 613          * @type {Number}
 614          * @protected
 615          */
 616         _factor: 1,
 617
 618         /**
 619          * Stub for construction logic.  Override if extending this class and
 620          * you need to set something up during the initializer phase.
 621          *
 622          * @method _initSliderValueRange
 623          * @protected
 624          */
 625         _initSliderValueRange: function () {},
 626
 627         /**
 628          * Override of stub method in SliderBase that is called at the end of
 629          * its bindUI stage of render().  Subscribes to internal events to
 630          * trigger UI and related state updates.
 631          *
 632          * @method _bindValueLogic
 633          * @protected
 634          */
 635         _bindValueLogic: function () {
 636             this.after( {
 637                 minChange  : this._afterMinChange,
 638                 maxChange  : this._afterMaxChange,
 639                 valueChange: this._afterValueChange
 640             } );
 641         },
 642
 643         /**
 644          * Move the thumb to appropriate position if necessary.  Also resets
 645          * the cached offsets and recalculates the conversion factor to
 646          * translate position to value.
 647          *
 648          * @method _syncThumbPosition
 649          * @protected
 650          */
 651         _syncThumbPosition: function () {
 652             this._calculateFactor();
 653
 654             this._setPosition( this.get( VALUE ) );
 655         },
 656
 657         /**
 658          * Calculates and caches
 659          * (range between max and min) / (rail length)
 660          * for fast runtime calculation of position -&gt; value.
 661          *
 662          * @method _calculateFactor
 663          * @protected
 664          */
 665         _calculateFactor: function () {
 666             var length    = this.get( 'length' ),
 667                 thumbSize = this.thumb.getStyle( this._key.dim ),
 668                 min       = this.get( MIN ),
 669                 max       = this.get( MAX );
 670
 671             // The default thumb width is based on Sam skin's thumb dimension.
 672             // This attempts to allow for rendering off-DOM, then attaching
 673             // without the need to call syncUI().  It is still recommended
 674             // to call syncUI() in these cases though, just to be sure.
 675             length = parseFloat( length, 10 ) || 150;
 676             thumbSize = parseFloat( thumbSize, 10 ) || 15;
 677
 678             this._factor = ( max - min ) / ( length - thumbSize );
 679
 680         },
 681
 682         /**
 683          * Dispatch the new position of the thumb into the value setting
 684          * operations.
 685          *
 686          * @method _defThumbMoveFn
 687          * @param e { EventFacade } The host's thumbMove event
 688          * @protected
 689          */
 690         _defThumbMoveFn: function ( e ) {
 691             var previous = this.get( VALUE ),
 692                 value    = this._offsetToValue( e.offset );
 693
 694             // This test avoids duplication of this.set(..) if the origin
 695             // of this thumbMove is from slider.set('value',x);
 696             // slider.set() -> afterValueChange -> uiMoveThumb ->
 697             // fire(thumbMove) -> _defThumbMoveFn -> this.set()
 698             if ( previous !== value ) {
 699                 this.set( VALUE, value, { positioned: true } );
 700             }
 701         },
 702
 703         /**
 704          * <p>Converts a pixel position into a value.  Calculates current
 705          * thumb offset from the leading edge of the rail multiplied by the
 706          * ratio of <code>(max - min) / (constraining dim)</code>.</p>
 707          *
 708          * <p>Override this if you want to use a different value mapping
 709          * algorithm.</p>
 710          *
 711          * @method _offsetToValue
 712          * @param offset { Number } X or Y pixel offset
 713          * @return { mixed } Value corresponding to the provided pixel offset
 714          * @protected
 715          */
 716         _offsetToValue: function ( offset ) {
 717
 718             var value = round( offset * this._factor ) + this.get( MIN );
 719
 720             return round( this._nearestValue( value ) );
 721         },
 722
 723         /**
 724          * Converts a value into a pixel offset for use in positioning
 725          * the thumb according to the reverse of the
 726          * <code>_offsetToValue( xy )</code> operation.
 727          *
 728          * @method _valueToOffset
 729          * @param val { Number } The value to map to pixel X or Y position
 730          * @return { Number } The pixel offset
 731          * @protected
 732          */
 733         _valueToOffset: function ( value ) {
 734             var offset = round( ( value - this.get( MIN ) ) / this._factor );
 735
 736             return offset;
 737         },
 738
 739         /**
 740          * Returns the current value.  Override this if you want to introduce
 741          * output formatting. Otherwise equivalent to slider.get( "value" );
 742          *
 743          * @method getValue
 744          * @return {Number}
 745          */
 746         getValue: function () {
 747             return this.get( VALUE );
 748         },
 749
 750         /**
 751          * Updates the current value.  Override this if you want to introduce
 752          * input value parsing or preprocessing.  Otherwise equivalent to
 753          * slider.set( "value", v );
 754          *
 755          * @method setValue
 756          * @param val {Number} The new value
 757          * @return {Slider}
 758          * @chainable
 759          */
 760         setValue: function ( val ) {
 761             return this.set( VALUE, val );
 762         },
 763
 764         /**
 765          * Update position according to new min value.  If the new min results
 766          * in the current value being out of range, the value is set to the
 767          * closer of min or max.
 768          *
 769          * @method _afterMinChange
 770          * @param e { EventFacade } The <code>min</code> attribute change event.
 771          * @protected
 772          */
 773         _afterMinChange: function ( e ) {
 774             this._verifyValue();
 775
 776             this._syncThumbPosition();
 777         },
 778
 779         /**
 780          * Update position according to new max value.  If the new max results
 781          * in the current value being out of range, the value is set to the
 782          * closer of min or max.
 783          *
 784          * @method _afterMaxChange
 785          * @param e { EventFacade } The <code>max</code> attribute change event.
 786          * @protected
 787          */
 788         _afterMaxChange: function ( e ) {
 789             this._verifyValue();
 790
 791             this._syncThumbPosition();
 792         },
 793
 794         /**
 795          * Verifies that the current value is within the min - max range.  If
 796          * not, value is set to either min or max, depending on which is
 797          * closer.
 798          *
 799          * @method _verifyValue
 800          * @protected
 801          */
 802         _verifyValue: function () {
 803             var value   = this.get( VALUE ),
 804                 nearest = this._nearestValue( value );
 805
 806             if ( value !== nearest ) {
 807                 // @TODO Can/should valueChange, minChange, etc be queued
 808                 // events? To make dd.set( 'min', n ); execute after minChange
 809                 // subscribers before on/after valueChange subscribers.
 810                 this.set( VALUE, nearest );
 811             }
 812         },
 813
 814         /**
 815          * Propagate change to the thumb position unless the change originated
 816          * from the thumbMove event.
 817          *
 818          * @method _afterValueChange
 819          * @param e { EventFacade } The <code>valueChange</code> event.
 820          * @protected
 821          */
 822         _afterValueChange: function ( e ) {
 823             if ( !e.positioned ) {
 824                 this._setPosition( e.newVal );
 825             }
 826         },
 827
 828         /**
 829          * Positions the thumb in accordance with the translated value.
 830          *
 831          * @method _setPosition
 832          * @protected
 833          */
 834         _setPosition: function ( value ) {
 835             this._uiMoveThumb( this._valueToOffset( value ) );
 836         },
 837
 838         /**
 839          * Validates new values assigned to <code>min</code> attribute.  Numbers
 840          * are acceptable.  Override this to enforce different rules.
 841          *
 842          * @method _validateNewMin
 843          * @param value { mixed } Value assigned to <code>min</code> attribute.
 844          * @return { Boolean } True for numbers.  False otherwise.
 845          * @protected
 846          */
 847         _validateNewMin: function ( value ) {
 848             return Y.Lang.isNumber( value );
 849         },
 850
 851         /**
 852          * Validates new values assigned to <code>max</code> attribute.  Numbers
 853          * are acceptable.  Override this to enforce different rules.
 854          *
 855          * @method _validateNewMax
 856          * @param value { mixed } Value assigned to <code>max</code> attribute.
 857          * @return { Boolean } True for numbers.  False otherwise.
 858          * @protected
 859          */
 860         _validateNewMax: function ( value ) {
 861             return Y.Lang.isNumber( value );
 862         },
 863
 864         /**
 865          * Restricts new values assigned to <code>value</code> attribute to be
 866          * between the configured <code>min</code> and <code>max</code>.
 867          * Rounds to nearest integer value.
 868          *
 869          * @method _setNewValue
 870          * @param value { Number } Value assigned to <code>value</code> attribute
 871          * @return { Number } Normalized and constrained value
 872          * @protected
 873          */
 874         _setNewValue: function ( value ) {
 875             return round( this._nearestValue( value ) );
 876         },
 877
 878         /**
 879          * Returns the nearest valid value to the value input.  If the provided
 880          * value is outside the min - max range, accounting for min > max
 881          * scenarios, the nearest of either min or max is returned.  Otherwise,
 882          * the provided value is returned.
 883          *
 884          * @method _nearestValue
 885          * @param value { mixed } Value to test against current min - max range
 886          * @return { Number } Current min, max, or value if within range
 887          * @protected
 888          */
 889         _nearestValue: function ( value ) {
 890             var min = this.get( MIN ),
 891                 max = this.get( MAX ),
 892                 tmp;
 893
 894             // Account for reverse value range (min > max)
 895             tmp = ( max > min ) ? max : min;
 896             min = ( max > min ) ? min : max;
 897             max = tmp;
 898
 899             return ( value < min ) ?
 900                     min :
 901                     ( value > max ) ?
 902                         max :
 903                         value;
 904         }
 905
 906     },
 907
 908     /**
 909      * Attributes that will be added onto host class.
 910      *
 911      * @property ATTRS
 912      * @type {Object}
 913      * @static
 914      * @protected
 915      */
 916     ATTRS: {
 917         /**
 918          * The value associated with the farthest top, left position of the
 919          * rail.  Can be greater than the configured <code>max</code> if you
 920          * want values to increase from right-to-left or bottom-to-top.
 921          *
 922          * @attribute min
 923          * @type { Number }
 924          * @default 0
 925          */
 926         min: {
 927             value    : 0,
 928             validator: '_validateNewMin'
 929         },
 930
 931         /**
 932          * The value associated with the farthest bottom, right position of
 933          * the rail.  Can be less than the configured <code>min</code> if
 934          * you want values to increase from right-to-left or bottom-to-top.
 935          *
 936          * @attribute max
 937          * @type { Number }
 938          * @default 100
 939          */
 940         max: {
 941             value    : 100,
 942             validator: '_validateNewMax'
 943         },
 944
 945         /**
 946          * The value associated with the thumb's current position on the
 947          * rail. Defaults to the value inferred from the thumb's current
 948          * position. Specifying value in the constructor will move the
 949          * thumb to the position that corresponds to the supplied value.
 950          *
 951          * @attribute value
 952          * @type { Number }
 953          * @default (inferred from current thumb position)
 954          */
 955         value: {
 956             value : 0,
 957             setter: '_setNewValue'
 958         }
 959     }
 960 }, true );
 961
 962
 963 }, '3.3.0' ,{requires:['slider-base']});
 964 YUI.add('clickable-rail', function(Y) {
 965
 966 /**
 967  * Adds support for mouse interaction with the Slider rail triggering thumb
 968  * movement.
 969  *
 970  * @module slider
 971  * @submodule clickable-rail
 972  */
 973
 974 /**
 975  * Slider extension that allows clicking on the Slider's rail element,
 976  * triggering the thumb to align with the location of the click.
 977  *
 978  * @class ClickableRail
 979  */
 980 function ClickableRail() {
 981     this._initClickableRail();
 982 }
 983
 984 Y.ClickableRail = Y.mix(ClickableRail, {
 985
 986     // Prototype methods added to host class
 987     prototype: {
 988
 989         /**
 990          * Initializes the internal state and sets up events.
 991          *
 992          * @method _initClickableRail
 993          * @protected
 994          */
 995         _initClickableRail: function () {
 996             this._evtGuid = this._evtGuid || (Y.guid() + '|');
 997
 998             /**
 999              * Broadcasts when the rail has received a mousedown event and
1000              * triggers the thumb positioning.  Use
1001              * <code>e.preventDefault()</code> or
1002              * <code>set(&quot;clickableRail&quot;, false)</code> to prevent
1003              * the thumb positioning.
1004              *
1005              * @event railMouseDown
1006              * @preventable _defRailMouseDownFn
1007              */
1008             this.publish('railMouseDown', {
1009                 defaultFn: this._defRailMouseDownFn
1010             });
1011
1012             this.after('render', this._bindClickableRail);
1013             this.on('destroy', this._unbindClickableRail);
1014         },
1015
1016         /**
1017          * Attaches DOM event subscribers to support rail interaction.
1018          *
1019          * @method _bindClickableRail
1020          * @protected
1021          */
1022         _bindClickableRail: function () {
1023             this._dd.addHandle(this.rail);
1024
1025             this.rail.on(this._evtGuid + Y.DD.Drag.START_EVENT,
1026                 Y.bind(this._onRailMouseDown, this));
1027         },
1028
1029         /**
1030          * Detaches DOM event subscribers for cleanup/destruction cycle.
1031          *
1032          * @method _unbindClickableRail
1033          * @protected
1034          */
1035         _unbindClickableRail: function () {
1036             if (this.get('rendered')) {
1037                 var contentBox = this.get('contentBox'),
1038                     rail = contentBox.one('.' + this.getClassName('rail'));
1039
1040                 rail.detach(this.evtGuid + '*');
1041             }
1042         },
1043
1044         /**
1045          * Dispatches the railMouseDown event.
1046          *
1047          * @method _onRailMouseDown
1048          * @param e {DOMEvent} the mousedown event object
1049          * @protected
1050          */
1051         _onRailMouseDown: function (e) {
1052             if (this.get('clickableRail') && !this.get('disabled')) {
1053                 this.fire('railMouseDown', { ev: e });
1054             }
1055         },
1056
1057         /**
1058          * Default behavior for the railMouseDown event.  Centers the thumb at
1059          * the click location and passes control to the DDM to behave as though
1060          * the thumb itself were clicked in preparation for a drag operation.
1061          *
1062          * @method _defRailMouseDownFn
1063          * @param e {Event} the EventFacade for the railMouseDown custom event
1064          * @protected
1065          */
1066         _defRailMouseDownFn: function (e) {
1067             e = e.ev;
1068
1069             // Logic that determines which thumb should be used is abstracted
1070             // to someday support multi-thumb sliders
1071             var dd     = this._resolveThumb(e),
1072                 i      = this._key.xyIndex,
1073                 length = parseFloat(this.get('length'), 10),
1074                 thumb,
1075                 thumbSize,
1076                 xy;
1077
1078             if (dd) {
1079                 thumb = dd.get('dragNode');
1080                 thumbSize = parseFloat(thumb.getStyle(this._key.dim), 10);
1081
1082                 // Step 1. Allow for aligning to thumb center or edge, etc
1083                 xy = this._getThumbDestination(e, thumb);
1084
1085                 // Step 2. Remove page offsets to give just top/left style val
1086                 xy = xy[ i ] - this.rail.getXY()[i];
1087
1088                 // Step 3. Constrain within the rail in case of attempt to
1089                 // center the thumb when clicking on the end of the rail
1090                 xy = Math.min(
1091                         Math.max(xy, 0),
1092                         (length - thumbSize));
1093
1094                 this._uiMoveThumb(xy);
1095
1096                 // Set e.target for DD's IE9 patch which calls
1097                 // e.target._node.setCapture() to allow imgs to be dragged.
1098                 // Without this, setCapture is called from the rail and rail
1099                 // clicks on other Sliders may have their thumb movements
1100                 // overridden by a different Slider (the thumb on the wrong
1101                 // Slider moves).
1102                 e.target = this.thumb.one('img') || this.thumb;
1103
1104                 // Delegate to DD's natural behavior
1105                 dd._handleMouseDownEvent(e);
1106
1107                 // TODO: this won't trigger a slideEnd if the rail is clicked
1108                 // check if dd._move(e); dd._dragThreshMet = true; dd.start();
1109                 // will do the trick.  Is that even a good idea?
1110             }
1111         },
1112
1113         /**
1114          * Resolves which thumb to actuate if any.  Override this if you want to
1115          * support multiple thumbs.  By default, returns the Drag instance for
1116          * the thumb stored by the Slider.
1117          *
1118          * @method _resolveThumb
1119          * @param e {DOMEvent} the mousedown event object
1120          * @return {Y.DD.Drag} the Drag instance that should be moved
1121          * @protected
1122          */
1123         _resolveThumb: function (e) {
1124             /* Temporary workaround
1125             var primaryOnly = this._dd.get('primaryButtonOnly'),
1126                 validClick  = !primaryOnly || e.button <= 1;
1127
1128             return (validClick) ? this._dd : null;
1129              */
1130             return this._dd;
1131         },
1132
1133         /**
1134          * Calculates the top left position the thumb should be moved to to
1135          * align the click XY with the center of the specified node.
1136          *
1137          * @method _getThumbDestination
1138          * @param e {DOMEvent} The mousedown event object
1139          * @param node {Node} The node to position
1140          * @return {Array} the [top, left] pixel position of the destination
1141          * @protected
1142          */
1143         _getThumbDestination: function (e, node) {
1144             var offsetWidth  = node.get('offsetWidth'),
1145                 offsetHeight = node.get('offsetHeight');
1146
1147             // center
1148             return [
1149                 (e.pageX - Math.round((offsetWidth  / 2))),
1150                 (e.pageY - Math.round((offsetHeight / 2)))
1151             ];
1152         }
1153
1154     },
1155
1156     // Static properties added onto host class
1157     ATTRS: {
1158         /**
1159          * Enable or disable clickable rail support.
1160          *
1161          * @attribute clickableRail
1162          * @type {Boolean}
1163          * @default true
1164          */
1165         clickableRail: {
1166             value: true,
1167             validator: Y.Lang.isBoolean
1168         }
1169     }
1170
1171 }, true);
1172
1173
1174 }, '3.3.0' ,{requires:['slider-base']});
1175 YUI.add('range-slider', function(Y) {
1176
1177 /**
1178  * Create a sliding value range input visualized as a draggable thumb on a
1179  * background rail element.
1180  *
1181  * @module slider
1182  * @submodule range-slider
1183  */
1184
1185 /**
1186  * Create a slider to represent an integer value between a given minimum and
1187  * maximum.  Sliders may be aligned vertically or horizontally, based on the
1188  * <code>axis</code> configuration.
1189  *
1190  * @class Slider
1191  * @constructor
1192  * @extends SliderBase
1193  * @uses SliderValueRange
1194  * @uses ClickableRail
1195  * @param config {Object} Configuration object
1196  */
1197 Y.Slider = Y.Base.build( 'slider', Y.SliderBase,
1198     [ Y.SliderValueRange, Y.ClickableRail ] );
1199
1200
1201 }, '3.3.0' ,{requires:['slider-base', 'clickable-rail', 'slider-value-range']});
1202
1203
1204 YUI.add('slider', function(Y){}, '3.3.0' ,{use:['slider-base', 'slider-value-range', 'clickable-rail', 'range-slider']});
1205