/*
Copyright (c) 2010, Yahoo! Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.com/yui/license.html
version: 3.2.0
build: 2676
*/
YUI.add('slider-base', function(Y) {
/**
* Create a sliding value range input visualized as a draggable thumb on a
* background element.
*
* @module slider
* @submodule slider-base
*/
var INVALID_VALUE = Y.Attribute.INVALID_VALUE;
/**
* Create a slider to represent an input control capable of representing a
* series of intermediate states based on the position of the slider's thumb.
* These states are typically aligned to a value algorithm whereby the thumb
* position corresponds to a given value. Sliders may be oriented vertically or
* horizontally, based on the axis
configuration.
*
* @class SliderBase
* @extends Widget
* @param config {Object} Configuration object
* @constructor
*/
function SliderBase() {
SliderBase.superclass.constructor.apply( this, arguments );
}
Y.SliderBase = Y.extend( SliderBase, Y.Widget, {
// Y.Slider prototype
/**
* Construction logic executed during Slider instantiation.
*
* @method initializer
* @protected
*/
initializer : function () {
/**
* The configured axis, stored for fast lookup since it's a writeOnce
* attribute. This is for use by extension classes. For
* implementation code, use get( "axis" )
for
* authoritative source. Never write to this property.
*
* @property axis
* @type {String}
* @protected
*/
this.axis = this.get( 'axis' );
/**
* Cached fast access map for DOM properties and attributes that
* pertain to accessing dimensional or positioning information
* according to the Slider's axis (e.g. "height" vs.
* "width"). Extension classes should add to this collection
* for axis related strings if necessary.
*
* @property _key
* @type {Object}
* @protected
*/
this._key = {
dim : ( this.axis === 'y' ) ? 'height' : 'width',
minEdge: ( this.axis === 'y' ) ? 'top' : 'left',
maxEdge: ( this.axis === 'y' ) ? 'bottom' : 'right',
xyIndex: ( this.axis === 'y' ) ? 1 : 0
};
/**
* Signals that the thumb has moved. Payload includes the thumb's
* pixel offset from the top/left edge of the rail, and if triggered by
* dragging the thumb, the drag:drag
event.
*
* @event thumbMove
* @param event {Event} The event object for the thumbMove with the
* following extra properties:
*
drag:drag
event from the thumbcontentBox
. Override this method if you want to provide
* the rail element (presumably from existing markup).
*
* @method renderRail
* @return {Node} the rail node subtree
*/
renderRail: function () {
var minCapClass = this.getClassName( 'rail', 'cap', this._key.minEdge ),
maxCapClass = this.getClassName( 'rail', 'cap', this._key.maxEdge );
return Y.Node.create(
Y.substitute( this.RAIL_TEMPLATE, {
railClass : this.getClassName( 'rail' ),
railMinCapClass: minCapClass,
railMaxCapClass: maxCapClass
} ) );
},
/**
* Sets the rail length according to the length
attribute.
*
* @method _uiSetRailLength
* @param length {String} the length to apply to the rail style
* @protected
*/
_uiSetRailLength: function ( length ) {
this.rail.setStyle( this._key.dim, length );
},
/**
* Creates the Slider thumb DOM subtree for insertion into the Slider's
* rail. Override this method if you want to provide the thumb element
* (presumably from existing markup).
*
* @method renderThumb
* @return {Node} the thumb node subtree
*/
renderThumb: function () {
this._initThumbUrl();
var imageUrl = this.get( 'thumbUrl' );
return Y.Node.create(
Y.substitute( this.THUMB_TEMPLATE, {
thumbClass : this.getClassName( 'thumb' ),
thumbShadowClass: this.getClassName( 'thumb', 'shadow' ),
thumbImageClass : this.getClassName( 'thumb', 'image' ),
thumbShadowUrl : imageUrl,
thumbImageUrl : imageUrl
} ) );
},
/**
* Creates the Y.DD.Drag instance used to handle the thumb movement and
* binds Slider interaction to the configured value model.
*
* @method bindUI
* @protected
*/
bindUI : function () {
this._bindThumbDD();
this._bindValueLogic();
this.after( 'disabledChange', this._afterDisabledChange );
this.after( 'lengthChange', this._afterLengthChange );
},
/**
* Makes the thumb draggable and constrains it to the rail.
*
* @method _bindThumbDD
* @protected
*/
_bindThumbDD: function () {
var config = { constrain: this.rail };
// { constrain: rail, stickX: true }
config[ 'stick' + this.axis.toUpperCase() ] = true;
/**
* The DD.Drag instance linked to the thumb node.
*
* @property _dd
* @type {DD.Drag}
* @protected
*/
this._dd = new Y.DD.Drag( {
node : this.thumb,
bubble : false,
on : {
'drag:start': Y.bind( this._onDragStart, this )
},
after : {
'drag:drag': Y.bind( this._afterDrag, this ),
'drag:end' : Y.bind( this._afterDragEnd, this )
}
} );
// Constrain the thumb to the rail
this._dd.plug( Y.Plugin.DDConstrained, config );
},
/**
* Stub implementation. Override this (presumably in a class extension) to
* initialize any value logic that depends on the presence of the Drag
* instance.
*
* @method _bindValueLogic
* @protected
*/
_bindValueLogic: function () {},
/**
* Moves the thumb to pixel offset position along the rail.
*
* @method _uiMoveThumb
* @param offset {Number} the pixel offset to set as left or top style
* @protected
*/
_uiMoveThumb: function ( offset ) {
if ( this.thumb ) {
this.thumb.setStyle( this._key.minEdge, offset + 'px' );
Y.log("Setting thumb " + this._key.minEdge + " to " + offset + "px","info","slider");
this.fire( 'thumbMove', { offset: offset } );
}
},
/**
* Dispatches the slideStart
event.
*
* @method _onDragStart
* @param e {Event} the drag:start
event from the thumb
* @protected
*/
_onDragStart: function ( e ) {
/**
* Signals the beginning of a thumb drag operation. Payload includes
* the thumb's drag:start event.
*
* @event slideStart
* @param event {Event} The event object for the slideStart with the
* following extra properties:
* drag:start
event from the thumbthumbMove
event.
*
* @method _afterDrag
* @param e {Event} the drag:drag
event from the thumb
* @protected
*/
_afterDrag: function ( e ) {
var thumbXY = e.info.xy[ this._key.xyIndex ],
railXY = e.target.con._regionCache[ this._key.minEdge ];
Y.log("Thumb position: " + thumbXY + ", Rail position: " + railXY, "info", "slider");
this.fire( 'thumbMove', {
offset : (thumbXY - railXY),
ddEvent: e
} );
},
/**
* Dispatches the slideEnd
event.
*
* @method _onDragEnd
* @param e {Event} the drag:end
event from the thumb
* @protected
*/
_afterDragEnd: function ( e ) {
/**
* Signals the end of a thumb drag operation. Payload includes
* the thumb's drag:end event.
*
* @event slideEnd
* @param event {Event} The event object for the slideEnd with the
* following extra properties:
* drag:end
event from the thumblength
attribute. By default, it
* triggers an update to the UI.
*
* @method _afterLengthChange
* @param e {Event} The lengthChange event object
* @protected
*/
_afterLengthChange: function ( e ) {
if ( this.get( 'rendered' ) ) {
this._uiSetRailLength( e.newVal );
this.syncUI();
}
},
/**
* Synchronizes the DOM state with the attribute settings.
*
* @method syncUI
*/
syncUI : function () {
this._dd.con.resetCache();
this._syncThumbPosition();
// Forces a reflow of the bounding box to address IE8 inline-block
// container not expanding correctly. bug 2527905
//this.get('boundingBox').toggleClass('');
},
/**
* Stub implementation. Override this (presumably in a class extension) to
* ensure the thumb is in the correct position according to the value
* alogorithm.
* instance.
*
* @method _syncThumbPosition
* @protected
*/
_syncThumbPosition: function () {},
/**
* Validates the axis is "x" or "y" (case insensitive).
* Converts to lower case for storage.
*
* @method _setAxis
* @param v {String} proposed value for the axis attribute
* @return {String} lowercased first character of the input string
* @protected
*/
_setAxis : function (v) {
v = ( v + '' ).toLowerCase();
return ( v === 'x' || v === 'y' ) ? v : INVALID_VALUE;
},
/**
* Ensures the stored length value is a string with a quantity and unit.
* Unit will be defaulted to "px" if not included. Rejects
* values less than or equal to 0 and those that don't at least start with
* a number.
*
* @method _setLength
* @param v {String} proposed value for the length attribute
* @return {String} the sanitized value
* @protected
*/
_setLength: function ( v ) {
v = ( v + '' ).toLowerCase();
var length = parseFloat( v, 10 ),
units = v.replace( /[\d\.\-]/g, '' ) || this.DEF_UNIT;
return length > 0 ? ( length + units ) : INVALID_VALUE;
},
/**
* Defaults the thumbURL attribute according to the current skin, or
* "sam" if none can be determined. Horizontal Sliders will have
* their thumbUrl
attribute set to
"/configured/yui/builddir/slider/assets/skins/sam/thumb-x.png"
And vertical thumbs will get
*"/configured/yui/builddir/slider/assets/skins/sam/thumb-y.png"
Y.Base.build(..)
to
* add the plumbing to Y.SliderBase
.
*
* @module slider
* @submodule slider-value-range
*/
// Constants for compression or performance
var MIN = 'min',
MAX = 'max',
VALUE = 'value',
round = Math.round;
/**
* One class of value algorithm that can be built onto SliderBase. By default,
* values range between 0 and 100, but you can configure these on the
* built Slider class by setting the min
and max
* configurations. Set the initial value (will cause the thumb to move to the
* appropriate location on the rail) in configuration as well if appropriate.
*
* @class SliderValueRange
*/
function SliderValueRange() {
this._initSliderValueRange();
}
Y.SliderValueRange = Y.mix( SliderValueRange, {
// Prototype properties and methods that will be added onto host class
prototype: {
/**
* Factor used to translate value -> position -> value.
*
* @property _factor
* @type {Number}
* @protected
*/
_factor: 1,
/**
* Stub for construction logic. Override if extending this class and
* you need to set something up during the initializer phase.
*
* @method _initSliderValueRange
* @protected
*/
_initSliderValueRange: function () {},
/**
* Override of stub method in SliderBase that is called at the end of
* its bindUI stage of render(). Subscribes to internal events to
* trigger UI and related state updates.
*
* @method _bindValueLogic
* @protected
*/
_bindValueLogic: function () {
this.after( {
minChange : this._afterMinChange,
maxChange : this._afterMaxChange,
valueChange: this._afterValueChange
} );
},
/**
* Move the thumb to appropriate position if necessary. Also resets
* the cached offsets and recalculates the conversion factor to
* translate position to value.
*
* @method _syncThumbPosition
* @protected
*/
_syncThumbPosition: function () {
this._calculateFactor();
this._setPosition( this.get( VALUE ) );
},
/**
* Calculates and caches
* (range between max and min) / (rail length)
* for fast runtime calculation of position -> value.
*
* @method _calculateFactor
* @protected
*/
_calculateFactor: function () {
var length = this.get( 'length' ),
thumbSize = this.thumb.getStyle( this._key.dim ),
min = this.get( MIN ),
max = this.get( MAX );
// The default thumb width is based on Sam skin's thumb dimension.
// This attempts to allow for rendering off-DOM, then attaching
// without the need to call syncUI(). It is still recommended
// to call syncUI() in these cases though, just to be sure.
length = parseFloat( length, 10 ) || 150;
thumbSize = parseFloat( thumbSize, 10 ) || 15;
this._factor = ( max - min ) / ( length - thumbSize );
Y.log("Calculating factor(~" + this._factor.toFixed(3) + " = (max(" + max + ") - min(" + min + ")) / (length(" + length + ") - thumb size(" + thumbSize + "))","info","slider");
},
/**
* Dispatch the new position of the thumb into the value setting
* operations.
*
* @method _defThumbMoveFn
* @param e { EventFacade } The host's thumbMove event
* @protected
*/
_defThumbMoveFn: function ( e ) {
var previous = this.get( VALUE ),
value = this._offsetToValue( e.offset );
// This test avoids duplication of this.set(..) if the origin
// of this thumbMove is from slider.set('value',x);
// slider.set() -> afterValueChange -> uiMoveThumb ->
// fire(thumbMove) -> _defThumbMoveFn -> this.set()
if ( previous !== value ) {
this.set( VALUE, value, { positioned: true } );
}
},
/**
* Converts a pixel position into a value. Calculates current
* thumb offset from the leading edge of the rail multiplied by the
* ratio of (max - min) / (constraining dim)
.
Override this if you want to use a different value mapping * algorithm.
* * @method _offsetToValue * @param offset { Number } X or Y pixel offset * @return { mixed } Value corresponding to the provided pixel offset * @protected */ _offsetToValue: function ( offset ) { var value = round( offset * this._factor ) + this.get( MIN ); Y.log("Offset: " + offset + " => Value: " + value, "info", "slider"); return round( this._nearestValue( value ) ); }, /** * Converts a value into a pixel offset for use in positioning * the thumb according to the reverse of the *_offsetToValue( xy )
operation.
*
* @method _valueToOffset
* @param val { Number } The value to map to pixel X or Y position
* @return { Number } The pixel offset
* @protected
*/
_valueToOffset: function ( value ) {
var offset = round( ( value - this.get( MIN ) ) / this._factor );
Y.log("Value: " + value + " => Offset: " + offset, "info", "slider");
return offset;
},
/**
* Returns the current value. Override this if you want to introduce
* output formatting. Otherwise equivalent to slider.get( "value" );
*
* @method getValue
* @return {Number}
*/
getValue: function () {
return this.get( VALUE );
},
/**
* Updates the current value. Override this if you want to introduce
* input value parsing or preprocessing. Otherwise equivalent to
* slider.set( "value", v );
*
* @method setValue
* @param val {Number} The new value
* @return {Slider}
* @chainable
*/
setValue: function ( val ) {
return this.set( VALUE, val );
},
/**
* Update position according to new min value. If the new min results
* in the current value being out of range, the value is set to the
* closer of min or max.
*
* @method _afterMinChange
* @param e { EventFacade } The min
attribute change event.
* @protected
*/
_afterMinChange: function ( e ) {
this._verifyValue();
this._syncThumbPosition();
},
/**
* Update position according to new max value. If the new max results
* in the current value being out of range, the value is set to the
* closer of min or max.
*
* @method _afterMaxChange
* @param e { EventFacade } The max
attribute change event.
* @protected
*/
_afterMaxChange: function ( e ) {
this._verifyValue();
this._syncThumbPosition();
},
/**
* Verifies that the current value is within the min - max range. If
* not, value is set to either min or max, depending on which is
* closer.
*
* @method _verifyValue
* @protected
*/
_verifyValue: function () {
var value = this.get( VALUE ),
nearest = this._nearestValue( value );
if ( value !== nearest ) {
// @TODO Can/should valueChange, minChange, etc be queued
// events? To make dd.set( 'min', n ); execute after minChange
// subscribers before on/after valueChange subscribers.
this.set( VALUE, nearest );
}
},
/**
* Propagate change to the thumb position unless the change originated
* from the thumbMove event.
*
* @method _afterValueChange
* @param e { EventFacade } The valueChange
event.
* @protected
*/
_afterValueChange: function ( e ) {
if ( !e.positioned ) {
Y.log("Positioning thumb after set('value',x)","info","slider");
this._setPosition( e.newVal );
}
},
/**
* Positions the thumb in accordance with the translated value.
*
* @method _setPosition
* @protected
*/
_setPosition: function ( value ) {
this._uiMoveThumb( this._valueToOffset( value ) );
},
/**
* Validates new values assigned to min
attribute. Numbers
* are acceptable. Override this to enforce different rules.
*
* @method _validateNewMin
* @param value { mixed } Value assigned to min
attribute.
* @return { Boolean } True for numbers. False otherwise.
* @protected
*/
_validateNewMin: function ( value ) {
return Y.Lang.isNumber( value );
},
/**
* Validates new values assigned to max
attribute. Numbers
* are acceptable. Override this to enforce different rules.
*
* @method _validateNewMax
* @param value { mixed } Value assigned to max
attribute.
* @return { Boolean } True for numbers. False otherwise.
* @protected
*/
_validateNewMax: function ( value ) {
return Y.Lang.isNumber( value );
},
/**
* Restricts new values assigned to value
attribute to be
* between the configured min
and max
.
* Rounds to nearest integer value.
*
* @method _setNewValue
* @param value { Number } Value assigned to value
attribute
* @return { Number } Normalized and constrained value
* @protected
*/
_setNewValue: function ( value ) {
return round( this._nearestValue( value ) );
},
/**
* Returns the nearest valid value to the value input. If the provided
* value is outside the min - max range, accounting for min > max
* scenarios, the nearest of either min or max is returned. Otherwise,
* the provided value is returned.
*
* @method _nearestValue
* @param value { mixed } Value to test against current min - max range
* @return { Number } Current min, max, or value if within range
* @protected
*/
_nearestValue: function ( value ) {
var min = this.get( MIN ),
max = this.get( MAX ),
tmp;
// Account for reverse value range (min > max)
tmp = ( max > min ) ? max : min;
min = ( max > min ) ? min : max;
max = tmp;
return ( value < min ) ?
min :
( value > max ) ?
max :
value;
}
},
/**
* Attributes that will be added onto host class.
*
* @property ATTRS
* @type {Object}
* @static
* @protected
*/
ATTRS: {
/**
* The value associated with the farthest top, left position of the
* rail. Can be greater than the configured max
if you
* want values to increase from right-to-left or bottom-to-top.
*
* @attribute min
* @type { Number }
* @default 0
*/
min: {
value : 0,
validator: '_validateNewMin'
},
/**
* The value associated with the farthest bottom, right position of
* the rail. Can be less than the configured min
if
* you want values to increase from right-to-left or bottom-to-top.
*
* @attribute max
* @type { Number }
* @default 100
*/
max: {
value : 100,
validator: '_validateNewMax'
},
/**
* The value associated with the thumb's current position on the
* rail. Defaults to the value inferred from the thumb's current
* position. Specifying value in the constructor will move the
* thumb to the position that corresponds to the supplied value.
*
* @attribute value
* @type { Number }
* @default (inferred from current thumb position)
*/
value: {
value : 0,
setter: '_setNewValue'
}
}
}, true );
}, '3.2.0' ,{requires:['slider-base']});
YUI.add('clickable-rail', function(Y) {
/**
* Adds support for mouse interaction with the Slider rail triggering thumb
* movement.
*
* @module slider
* @submodule clickable-rail
*/
/**
* Slider extension that allows clicking on the Slider's rail element,
* triggering the thumb to align with the location of the click.
*
* @class ClickableRail
*/
function ClickableRail() {
this._initClickableRail();
}
Y.ClickableRail = Y.mix(ClickableRail, {
// Prototype methods added to host class
prototype: {
/**
* Initializes the internal state and sets up events.
*
* @method _initClickableRail
* @protected
*/
_initClickableRail: function () {
this._evtGuid = this._evtGuid || (Y.guid() + '|');
/**
* Broadcasts when the rail has received a mousedown event and
* triggers the thumb positioning. Use
* e.preventDefault()
or
* set("clickableRail", false)
to prevent
* the thumb positioning.
*
* @event railMouseDown
* @preventable _defRailMouseDownFn
*/
this.publish('railMouseDown', {
defaultFn: this._defRailMouseDownFn
});
this.after('render', this._bindClickableRail);
this.on('destroy', this._unbindClickableRail);
},
/**
* Attaches DOM event subscribers to support rail interaction.
*
* @method _bindClickableRail
* @protected
*/
_bindClickableRail: function () {
this._dd.addHandle(this.rail);
this.rail.on(this._evtGuid + Y.DD.Drag.START_EVENT,
Y.bind(this._onRailMouseDown, this));
},
/**
* Detaches DOM event subscribers for cleanup/destruction cycle.
*
* @method _unbindClickableRail
* @protected
*/
_unbindClickableRail: function () {
if (this.get('rendered')) {
var contentBox = this.get('contentBox'),
rail = contentBox.one('.' + this.getClassName('rail'));
rail.detach(this.evtGuid + '*');
}
},
/**
* Dispatches the railMouseDown event.
*
* @method _onRailMouseDown
* @param e {DOMEvent} the mousedown event object
* @protected
*/
_onRailMouseDown: function (e) {
if (this.get('clickableRail') && !this.get('disabled')) {
this.fire('railMouseDown', { ev: e });
}
},
/**
* Default behavior for the railMouseDown event. Centers the thumb at
* the click location and passes control to the DDM to behave as though
* the thumb itself were clicked in preparation for a drag operation.
*
* @method _defRailMouseDownFn
* @param e {Event} the EventFacade for the railMouseDown custom event
* @protected
*/
_defRailMouseDownFn: function (e) {
e = e.ev;
// Logic that determines which thumb should be used is abstracted
// to someday support multi-thumb sliders
var dd = this._resolveThumb(e),
i = this._key.xyIndex,
length = parseFloat(this.get('length'), 10),
thumb,
thumbSize,
xy;
if (dd) {
thumb = dd.get('dragNode');
thumbSize = parseFloat(thumb.getStyle(this._key.dim), 10);
// Step 1. Allow for aligning to thumb center or edge, etc
xy = this._getThumbDestination(e, thumb);
// Step 2. Remove page offsets to give just top/left style val
xy = xy[ i ] - this.rail.getXY()[i];
// Step 3. Constrain within the rail in case of attempt to
// center the thumb when clicking on the end of the rail
xy = Math.min(
Math.max(xy, 0),
(length - thumbSize));
this._uiMoveThumb(xy);
// Delegate to DD's natural behavior
dd._handleMouseDownEvent(e);
}
},
/**
* Resolves which thumb to actuate if any. Override this if you want to
* support multiple thumbs. By default, returns the Drag instance for
* the thumb stored by the Slider.
*
* @method _resolveThumb
* @param e {DOMEvent} the mousedown event object
* @return {Y.DD.Drag} the Drag instance that should be moved
* @protected
*/
_resolveThumb: function (e) {
/* Temporary workaround
var primaryOnly = this._dd.get('primaryButtonOnly'),
validClick = !primaryOnly || e.button <= 1;
return (validClick) ? this._dd : null;
*/
return this._dd;
},
/**
* Calculates the top left position the thumb should be moved to to
* align the click XY with the center of the specified node.
*
* @method _getThumbDestination
* @param e {DOMEvent} The mousedown event object
* @param node {Node} The node to position
* @return {Array} the [top, left] pixel position of the destination
* @protected
*/
_getThumbDestination: function (e, node) {
var offsetWidth = node.get('offsetWidth'),
offsetHeight = node.get('offsetHeight');
// center
return [
(e.pageX - Math.round((offsetWidth / 2))),
(e.pageY - Math.round((offsetHeight / 2)))
];
}
},
// Static properties added onto host class
ATTRS: {
/**
* Enable or disable clickable rail support.
*
* @attribute clickableRail
* @type {Boolean}
* @default true
*/
clickableRail: {
value: true,
validator: Y.Lang.isBoolean
}
}
}, true);
}, '3.2.0' ,{requires:['slider-base']});
YUI.add('range-slider', function(Y) {
/**
* Create a sliding value range input visualized as a draggable thumb on a
* background rail element.
*
* @module slider
* @submodule range-slider
*/
/**
* Create a slider to represent an integer value between a given minimum and
* maximum. Sliders may be aligned vertically or horizontally, based on the
* axis
configuration.
*
* @class Slider
* @constructor
* @extends SliderBase
* @uses SliderValueRange
* @uses ClickableRail
* @param config {Object} Configuration object
*/
Y.Slider = Y.Base.build( 'slider', Y.SliderBase,
[ Y.SliderValueRange, Y.ClickableRail ] );
}, '3.2.0' ,{requires:['slider-base', 'clickable-rail', 'slider-value-range']});
YUI.add('slider', function(Y){}, '3.2.0' ,{use:['slider-base', 'slider-value-range', 'clickable-rail', 'range-slider']});