jssource/src_files/include/javascript/yui3/build/slider/slider-base.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']});