Class Slider
- extends Widget
Create a slider to represent an integer value between a given minimum and
maximum.
Constructor
Slider
(
config
)
- Parameters:
-
config
<Object>
Configuration object
Properties
_disabled
- protected Boolean
Deferred value for the disabled attribute when stalled (see _stall
property).
_factor
- protected Number
Factor used to translate positional coordinates (e.g. left or top) to
the Slider's value.
_key
- protected Object
Collection of object property names from the appropriate hash set in
Slider.AXIS_KEYS.
_railSize
- protected Number
Pixel dimension of the rail Node's width for X axis Sliders or height
for Y axis Sliders. Used with _factor to calculate positional
coordinates for the thumb.
_stall
- protected Object
Object returned from temporary subscription to disabledChange event to
defer setting the disabled state while Slider is loading the thumb
image.
Pixel offset of the point in the thumb element from its top/left edge
to where the value calculation should take place. By default, this is
calculated to half the width of the thumb, causing the value to be
marked from the center of the thumb.
Pixel dimension of the thumb Node's width for X axis Sliders or height
for Y axis Sliders. Used with _factor to calculate positional
coordinates for the thumb.
Static property used to define the default attribute configuration of
the Widget.
Object property names used for respective X and Y axis Sliders (e.g.
"left" vs. "top" for placing the thumb according to
its representative value).
Static Object hash used to capture existing markup for progressive
enhancement. Keys correspond to config attribute names and values
are selectors used to inspect the contentBox for an existing node
structure.
The identity of the widget.
Properties inherited from Widget:
Properties inherited from Base:
Methods
protected
void
_afterDisabledChange
(
e
)
Locks or unlocks the DD instance in response to a change in the disabled
attribute.
- Parameters:
-
e
<Event>
disabledChange custom event
- Returns:
void
protected
void
_afterMaxChange
(
e
)
Calls syncUI to update the Slider UI in response to change in the max
attribute.
- Parameters:
-
e
<Event>
maxChange custom event
- Returns:
void
protected
void
_afterMinChange
(
e
)
Calls syncUI to update the Slider UI in response to change in the min
attribute.
- Parameters:
-
e
<Event>
minChange custom event
- Returns:
void
protected
void
_afterRailSizeChange
(
e
)
Calls syncUI to update the Slider UI in response to change in the
railSize attribute.
- Parameters:
-
e
<Event>
railSizeChange custom event
- Returns:
void
protected
void
_afterThumbChange
(
e
)
Replaces the thumb Node in response to a change in the thumb attribute.
This only has effect before the Slider is rendered.
- Parameters:
-
e
<Event>
thumbChange custom event
- Returns:
void
protected
void
_afterThumbImageChange
(
e
)
Sets or replaces the thumb's contained img Node with the
new Node in response to a change in the thumbImage attribute. This only
has effect before the Slider is rendered.
- Parameters:
-
e
<Event>
thumbImageChange custom event
- Returns:
void
protected
void
_afterValueChange
(
e
)
Fires the internal valueSet event in response to a change in the value
attribute.
- Parameters:
-
e
<Event>
valueChange custom event
- Returns:
void
protected
void
_bindThumbDD
(
)
Creates the Y.DD instance used to handle the thumb interaction.
protected
void
_defSetThumbPosition
(
e
)
The default behavior for calculating the placement of the thumb in
response to a value attribute update. This is performed in response
to firing the internal valueSet event.
- Parameters:
-
e
<Event>
the valueSet custom event
- Returns:
void
protected
void
_defSyncUI
(
e
)
The default synchronization behavior, updating the Slider's DOM state to
match the current attribute values.
- Parameters:
-
e
<Event>
Internal sync event
- Returns:
void
protected
void
_defUpdateValueFromDD
(
e
)
The default value update behavior in response to Slider thumb
interaction. Calculates the value using stored offsets, the _factor
multiplier and the min value.
- Parameters:
-
e
<Event>
the internal thumbDrag event
- Returns:
void
protected
void
_handleRailMouseDown
(
e
)
Moves the thumb to the mousedown position and hands control over to DD
if the Slider is not disabled and railEnabled is true.
- Parameters:
-
e
<Event>
Mousedown event facade
- Returns:
void
protected
void
_imageLoaded
(
e
,
img
)
Event handler assigned to the thumbImage's load and error event if it
was not loaded prior to instantiation. Calls _ready method and restores
the Slider's disabled attribute.
- Parameters:
-
e
<Event>
load or error event fired by the thumbImage
-
img
<Node>
The thumbImage Node
- Returns:
void
protected
void
_initRail
(
)
Creates the rail element if not provided or discovered via HTML_PARSER.
protected
void
_initRailDD
(
)
Subscribes to the rail Node's mousedown event to actuate the thumb when
backgroundEnabled is true.
protected
void
_initThumb
(
)
Creates the thumb element (not image) if not provided or discovered via
HTML_PARSER. If thumb is present and an img element
and no thumbImage provided, reassigns the thumb element to the
thumbImage and defaults the thumb element as a div.
Makes sure the thumb is a child of the rail element and calls
_initThumbImage if thumbImage is provided.
protected
void
_initThumbImage
(
)
Ensures the thumbImage is a child of the thumb element.
protected
_isImageLoaded
(
img
)
Used to determine if the image resource loaded successfully or there was
an error.
NOTES:
- img load error fired xbrowser for image resources not yet resolved
- img.complete reports false in IE for images not yet loaded as well as images that failed to load
- img.complete true && img.naturalWidth == 0 in FF and Safari indicate image failed to load
- img.complete && img.width == 0 in Opera indicates image failed to load
- Parameters:
-
img
<Node>
img Node
protected
_isImageLoading
(
img
)
Used to determine if there is a current or pending request for the
thumbImage resource.
- Parameters:
-
img
<Node>
img Node
protected
void
_onDDDrag
(
e
)
Fires the thumbDrag event to queue Slider value update.
- Parameters:
-
e
<Event>
the DD instance's drag:drag custom event
- Returns:
void
protected
void
_onDDEndDrag
(
e
)
Fires the slideEnd event.
- Parameters:
-
e
<Event>
the DD instance's drag:end custom event
- Returns:
void
protected
void
_onDDStartDrag
(
e
)
Caches the current page position of the rail element and fires the
slideStart event in response to the DD's drag:start.
- Parameters:
-
e
<Event>
the DD instance's drag:start custom event
- Returns:
void
protected
void
_ready
(
img
,
error
)
Fires the internal sync event, which barring preventDefault should
execute _defSyncUI.
- Parameters:
-
img
<Node>
the thumbImage Node
-
error
<Boolean>
Indicates an error while loading the thumbImage
- Returns:
void
protected
void
_refresh
(
e
)
Common handler to call syncUI in response to change events that occurred
after the Slider is rendered.
- Parameters:
-
e
<Event>
An attribute change event
- Returns:
void
protected
void
_scheduleSync
(
)
Binds to the load and error event on the thumbImage to sync the DOM
state with the attribute settings when the image resource is resolved.
The Slider is disabled while it waits.
protected
String
_setAxisFn
(
v
)
Setter applied to the input when updating the railSize attribute.
- Parameters:
-
v
<String>
proposed value for the axis attribute
- Returns:
String
- lowercased first character of the input string
protected
void
_setDDGutter
(
)
Assigns the gutter attribute to the DD instance to allow the thumb to
overshoot the edges of the rail element up to the _thumbOffset. By
default, this allows the thumb's center point to align with the far left
or top edge of the rail element to represent the min value and the far
right or bottom edge for the max.
protected
void
_setFactor
(
)
Calculates the multiplier used to translate the value into a thumb
position.
protected
Node
_setRailFn
(
v
)
Setter applied to the input when updating the rail attribute. Input can
be a Node, raw HTMLElement, or a selector string to locate it.
- Parameters:
-
v
<Node|String|HTMLElement>
The rail element Node or selector
- Returns:
Node
- The Node if found. Otherwise null.
protected
void
_setRailOffsetXY
(
)
Store the current XY position of the rail Node on the page. For use in calculating thumb position from value.
protected
Node
_setThumbFn
(
v
)
Setter applied to the input when updating the thumb attribute. Input can
be a Node, raw HTMLElement, or a selector string to locate it.
- Parameters:
-
v
<Node|String|HTMLElement>
The thumb element Node or selector
- Returns:
Node
- The Node if found. Otherwise null.
protected
Node
_setThumbImageFn
(
v
)
Setter applied to the input when updating the thumbImage attribute.
Input can be a Node, raw HTMLElement, selector string to locate it, or
the URL for an image resource.
String input will be treated as a selector. If no element is found using
the selector, an img Node will be created with the string
used as the src attribute.
- Parameters:
-
v
<Node|String|HTMLElement>
The thumbImage element Node, selector,
or image URL
- Returns:
Node
- The Node if found or created. Otherwise null.
protected
void
_setThumbOffset
(
)
Sets the _thumbOffset property for use in establishing the point in the
thumb that should align to the rail position representing the calculated
value.
protected
Number
_setValueFn
(
v
)
Setter applied to the input when updating the value attribute.
- Parameters:
-
v
<Number>
proposed new value for the Slider
- Returns:
Number
- rounded value or configured min if non-number input
protected
void
_stallDisabledChange
(
e
)
Method subscribed to the disabledChange event when thumbImage is being
loaded. Prevents manually enabling the Slider until the thumbImage
resource is resolved. Intended value is stored during load and set upon
completion.
- Parameters:
-
e
<Event>
Change event for the disabled attribute
- Returns:
void
protected
void
_uiPositionThumb
(
xy
)
Places the thumb at a particular X or Y location based on the configured
axis.
- Parameters:
-
xy
<Number>
the desired left or top pixel position of the thumb
in relation to the rail Node.
- Returns:
void
protected
void
_uiSetRailSize
(
)
Stores the rail Node's pixel height or width, depending on the Slider's
axis, for use in calculating thumb position from the value.
protected
void
_uiSetThumbSize
(
)
Captures the thumbs pixel height or width, depending on the Slider's
axis, for use in positioning calculations.
protected
_validateNewAxis
(
v
)
Validator applied to new values for the axis attribute. Only
"x" and "y" are permitted.
- Parameters:
-
v
<String>
proposed value for the axis attribute
protected
_validateNewMax
(
v
)
Validator applied to the max attribute. Only numbers are allowed.
- Parameters:
-
v
<String>
proposed value for the max attribute
protected
_validateNewMin
(
v
)
Validator applied to the min attribute. Only numbers are allowed.
- Parameters:
-
v
<String>
proposed value for the min attribute
protected
_validateNewRail
(
v
)
Validator applied to the rail attribute. Only allows values through
before the Slider is rendered.
- Parameters:
-
v
<String>
proposed value for the rail attribute
protected
_validateNewRailSize
(
v
)
Validator applied to the railSize attribute. Only css size values (e.g.
'200px' are allowed.
- Parameters:
-
v
<String>
proposed value for the railSize attribute
protected
_validateNewThumb
(
v
)
Validator applied to the thumb attribute. Only allows values through
before the Slider is rendered.
- Parameters:
-
v
<String>
proposed value for the thumb attribute
protected
_validateNewThumbImage
(
v
)
Validator applied to the thumbImage attribute. Only allows values through
before the Slider is rendered.
- Parameters:
-
v
<String>
proposed value for the thumbImage attribute
protected
_validateNewValue
(
v
)
Validator applied to the value attribute. Only numbers between the min
and max are allowed.
- Parameters:
-
v
<String>
proposed value for the value attribute
protected
void
bindUI
(
)
Calls _bindThumbDD to create the Y.DD instance used to handle the thumb
movement and binds Slider interaction to the configured value model.
Number
getValue
(
)
Convenience method for accessing the current value of the Slider.
Equivalent to slider.get("value").
- Returns:
Number
- the value
protected
void
initializer
(
)
Construction logic executed durint Slider instantiation. Subscribe to
after events for min, max, and railSize. Publish custom events
including slideStart and slideEnd.
protected
void
renderUI
(
)
Create the DOM structure for the Slider. Calls _initRail and _initThumb.
void
setValue
(
val
)
Convenience method for updating the current value of the Slider.
Equivalent to slider.set("value",val).
- Parameters:
-
val
<Number>
the new value
- Returns:
void
void
syncUI
(
)
Synchronizes the DOM state with the attribute settings (most notably
railSize and value). If thumbImage is provided and is still loading,
sync is delayed until it is complete, since the image's dimensions are
taken into consideration for calculations.
Methods inherited from Attribute:
_cloneAttVal,
_defAttSet,
_fireAttChange,
_getSubAttVal,
_initAtts,
_initAttVal,
_set,
_setSubAttVal,
_splitAttrValues,
addAtt,
get,
getAtts,
on,
removeAtt,
reset,
set,
setAtts
Methods inherited from Widget:
_afterDisabledChange,
_afterHasFocusChange,
_afterHeightChange,
_afterVisibleChange,
_afterWidthChange,
_bindDOMListeners,
_bindUI,
_defRenderFn,
_getHtmlParser,
_getStrings,
_moveStyles,
_onBlur,
_onFocus,
_parseHTML,
_renderBox,
_renderBoxClassNames,
_renderUI,
_setBoundingBox,
_setBox,
_setContentBox,
_setStrings,
_syncUI,
_uiSetDisabled,
_uiSetHasFocus,
_uiSetHeight,
_uiSetTabIndex,
_uiSetVisible,
_uiSetWidth,
bindUI,
blur,
destructor,
disabled,
enable,
focus,
getClassName,
getDefaultLocale,
getString,
getStrings,
hide,
initializer,
render,
renderer,
renderUI,
show,
syncUI,
toString
Methods inherited from Base:
_defDestroyFn,
_defInitFn,
_destroyHierarchy,
_getClasses,
_initHierarchy,
_prefixEvtType,
after,
destroy,
fire,
init,
publish,
subscribe,
toString,
unsubscribe,
unsubscribeAll
Events
axisChange
(
event
)
Fires when the value for the configuration attribute 'axis' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
maxChange
(
event
)
Fires when the value for the configuration attribute 'max' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
minChange
(
event
)
Fires when the value for the configuration attribute 'min' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
railChange
(
event
)
Fires when the value for the configuration attribute 'rail' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
railEnabledChange
(
event
)
Fires when the value for the configuration attribute 'railEnabled' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
railSizeChange
(
event
)
Fires when the value for the configuration attribute 'railSize' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
slideEnd
(
event
)
Signals the end of a thumb drag operation. Payload includes
the DD.Drag instance's drag:end event under key ddEvent.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added:
- ddEvent
drag:end event from the managed DD.Drag instance
slideStart
(
event
)
Signals the beginning of a thumb drag operation. Payload includes
the DD.Drag instance's drag:start event under key ddEvent.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added:
- ddEvent
drag:start event from the managed DD.Drag instance
sync
(
event
)
Communicates a request to synchronize the Slider UI with the
attribute state. Links the sync request with the default sync
logic in the default function _defSyncUI.
- Parameters:
-
event
<Event.Facade>
Event Facade object
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defSyncUI.
thumbChange
(
event
)
Fires when the value for the configuration attribute 'thumb' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
thumbDrag
(
event
)
Communicates user interaction with the thumb. Triggers the logic
to update the value via the default function _defUpdateValueFromDD.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added:
- ddEvent
drag:drag event from the managed DD.Drag instance
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defUpdateValueFromDD.
thumbImageChange
(
event
)
Fires when the value for the configuration attribute 'thumbImage' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
valueChange
(
event
)
Fires when the value for the configuration attribute 'value' is changed. You can listen for the event using the
on method if you wish to be notified before the attribute's value has changed, or using the
after method if you wish to be notified after the attribute's value has changed.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added: - prevVal
- The value of the attribute, prior to it being set
- newVal
- The value the attribute is to be set to
- attrName
- The name of the attribute being set
- subAttrName
- If setting a property within the attribute's value, the name of the sub-attribute property being set
valueSet
(
event
)
Signals a value change via API, requiring the thumb position to be
updated. Triggers the thumb placement logic in the default function
_defSetThumbPosition.
- Parameters:
-
event
<Event.Facade>
An Event Facade object with the following attribute specific properties added:
- changeEv
valueChange event fired in response to the change in the value attribute
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defSetThumbPosition.
Events inherited from Widget:
boundingBoxChange,
contentBoxChange,
disabledChange,
hasFocusChange,
heightChange,
localeChange,
moveStylesChange,
renderedChange,
stringsChange,
tabIndexChange,
visibleChange,
widget:contentUpdate,
widget:render,
widthChange,
Events inherited from Base:
Configuration Attributes
axis
- writeonce String
Axis upon which the Slider's thumb moves. "x" for
horizontal, "y" for vertical.
Default Value: "x"
max
- Number
Integer value associated with the right or bottom terminus of the
Slider's rail, depending on the configured axis.
Default Value: 100
min
- Number
Integer value associated with the left or top terminus of the
Slider's rail, depending on the configured axis.
Default Value: 0
The Node representing the Slider's rail, usually visualized as a
bar of some sort using a background image, along which the thumb
moves. This Node contains the thumb Node.
Default Value: null
Boolean indicating whether clicking and dragging on the rail will
trigger thumb movement.
Default Value: true
The width or height of the rail element representing the physical
space along which the thumb can move. CSS size values (e.g. '30em')
accepted but converted to pixels during render.
Alternately, but not recommended, this attribute can be left
unassigned in favor of specifying height or width.
Default Value: '0'
The Node representing the Slider's thumb, usually visualized as a
pointer using a contained image Node (see thumbImage). The current
value of the Slider is calculated from the centerpoint of this
Node in relation to the rail Node. If provided, the thumbImage
Node is contained within this Node.
If no thumbImage is provided and the Node passed as the thumb is an
img element, the assigned Node will be allocated to the
thumbImage and the thumb container defaulted.
Default Value: null
The Node representing the image element to use for the Slider's
thumb.
Alternately, an image URL can be passed and an img
Node will be generated accordingly.
If no thumbImage is provided and the Node passed as the thumb is an
img element, the assigned Node will be allocated to the
thumbImage and the thumb container defaulted.
If thumbImage is provided but its URL resolves to a 404, a default
style will be applied to maintain basic functionality.
Default Value: null
The current value of the Slider. This value is interpretted into a
position for the thumb along the Slider's rail.
Default Value: 0
Configuration attributes inherited from Widget:
boundingBox,
contentBox,
disabled,
hasFocus,
height,
locale,
moveStyles,
rendered,
strings,
tabIndex,
visible,
width,
Configuration attributes inherited from Base: