Class Slider
- extends Widget
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.
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.
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).
Slider.ATTRS
- protected static Object
Static property used to define the default attribute configuration of
the Widget.
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
protected
void
_afterMaxChange
(
e
)
Updates the Slider UI in response to change in the max attribute.
- Parameters:
-
e
<Event>
maxChange custom event
protected
void
_afterMinChange
(
e
)
Updates the Slider UI in response to change in the min attribute.
- Parameters:
-
e
<Event>
minChange custom event
protected
void
_afterRailSizeChange
(
e
)
Updates the Slider UI in response to change in the railSize attribute.
- Parameters:
-
e
<Event>
railSizeChange custom event
protected
void
_afterThumbChange
(
e
)
Replaces the thumb Node in response to a change in the thumb attribute.
This only has effect after the Slider is rendered.
- Parameters:
-
e
<Event>
thumbChange custom event
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 after the Slider is rendered.
- Parameters:
-
e
<Event>
thumbImageChange custom event
protected
void
_afterValueChange
(
e
)
Fires the internal positionThumb event in response to a change in the
value attribute.
- Parameters:
-
e
<Event>
valueChange custom event
protected
void
_bindThumbDD
(
)
Creates the Y.DD instance used to handle the thumb interaction.
protected
void
_convertOffsetToValue
(
v
)
Converts a pixel offset of the thumb on the rail to a value.
- Parameters:
-
v
<Number>
pixel offset of the thumb on the rail
protected
void
_convertValueToOffset
(
v
)
Converts a value to a pixel offset for the thumb position on the rail.
- Parameters:
-
v
<Number>
value between the Slider's min and max
protected
void
_defPositionThumbFn
(
e
)
Calls _uiPositionThumb with the value of the custom event's
"offset" property.
- Parameters:
-
e
<Event>
the positionThumb custom event
protected
void
_defSyncFn
(
e
)
The default synchronization behavior, updating the Slider's DOM state to
match the current attribute values.
- Parameters:
-
e
<Event>
Internal sync event
protected
void
_defThumbDragFn
(
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
protected
void
_handleRailMouseDown
(
e
)
If the Slider is not disabled and railEnabled is true, moves the thumb
to the mousedown position and hands control over to DD.
- Parameters:
-
e
<Event>
Mousedown event facade
protected
void
_imageLoaded
(
img
,
e
)
Event handler assigned to the thumbImage's load and error event if it
was not loaded prior to instantiation. Restores the disabled value.
- Parameters:
-
img
<Node>
The thumbImage Node
-
e
<Event>
load or error event fired by the thumbImage
protected
void
_initRail
(
)
Creates the rail element if not provided and not 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 and not
discovered via HTML_PARSER. If the thumb is an img element
but no thumbImage configured or discovered, 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
Boolean
_isDisplayNone
(
el
)
Helper function to search up the ancestor axis looking for a node with
style display: none. This is passed as a function to node.ancestor(..)
to test if a given node is in the displayed DOM and can get accurate
positioning information.
- Parameters:
-
el
<Node>
ancestor node as the function walks up the parent axis
- Returns:
Boolean
- true if the node is styled with display: none
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
- Returns:
- Boolean
protected
_isImageLoading
(
img
)
Used to determine if there is a current or pending request for the
thumbImage resource.
- Parameters:
-
img
<Node>
img Node
- Returns:
- Boolean
protected
void
_onDDDrag
(
e
)
Fires the thumbDrag event to queue Slider value update.
- Parameters:
-
e
<Event>
the DD instance's drag:drag custom event
protected
void
_onDDEndDrag
(
e
)
Fires the slideEnd event.
- Parameters:
-
e
<Event>
the DD instance's drag:end custom event
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
protected
void
_ready
(
img
,
error
)
Applies a class to the content box if the thumbImage failed to resolve,
the fires the internal sync event triggering a sync between UI and
state.
- Parameters:
-
img
<Node>
the thumbImage Node
-
error
<Boolean>
Indicates an error while loading the thumbImage
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
protected
void
_resetDDCacheRegion
(
)
Resets the cached region inside the DD constrain instance to support
repositioning the Slider after instantiation.
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 axis attribute.
- Parameters:
-
v
<String>
proposed value for the axis attribute
- Returns:
String
- lowercased first character of the input string
protected
void
_setDDGutter
(
)
Passes the gutter attribute value to the DDConstrain gutter attribute.
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
(
)
Establishes the point in the thumb that should align to the rail
position representing the calculated value.
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
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.
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 thumb's 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
- Returns:
- Boolean
protected
_validateNewMax
(
v
)
Validator applied to the max attribute.
- Parameters:
-
v
<MIXED>
proposed value for the max attribute
- Returns:
- Boolean
protected
_validateNewMin
(
v
)
Validator applied to the min attribute.
- Parameters:
-
v
<MIXED>
proposed value for the min attribute
- Returns:
- Boolean
protected
_validateNewRail
(
v
)
Validator applied to the rail attribute. Rejects all values after the
Slider has been rendered.
- Parameters:
-
v
<MIXED>
proposed value for the rail attribute
- Returns:
- Boolean
protected
_validateNewRailSize
(
v
)
Validator applied to the railSize attribute. Only strings of css size
values (e.g. '200px') are allowed.
- Parameters:
-
v
<String>
proposed value for the railSize attribute
- Returns:
- Boolean
protected
_validateNewThumb
(
v
)
Validator applied to the thumb attribute. Rejects all values after the
Slider has been rendered.
- Parameters:
-
v
<MIXED>
proposed value for the thumb attribute
- Returns:
- Boolean
protected
_validateNewThumbImage
(
v
)
Validator applied to the thumbImage attribute. Rejects all values after
the Slider has been rendered.
- Parameters:
-
v
<MIXED>
proposed value for the thumbImage attribute
- Returns:
- Boolean
protected
_validateNewValue
(
v
)
Validator applied to the value attribute.
- Parameters:
-
v
<MIXED>
proposed value for the value attribute
- Returns:
- Boolean
protected
void
bindUI
(
)
Creates 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. Subscribes to
after events for min, max, and railSize. Publishes custom events
including slideStart and slideEnd.
protected
void
renderUI
(
)
Create the DOM structure for the Slider.
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
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 EventTarget:
_getType,
_parseType,
addTarget,
after,
before,
bubble,
detach,
detachAll,
fire,
getEvent,
on,
publish,
removeTarget,
subscribe,
unsubscribe,
unsubscribeAll
Methods inherited from Attribute:
_addAttrs,
_addLazyAttr,
_defAttrChangeFn,
_fireAttrChange,
_getAttr,
_getAttrInitVal,
_getAttrs,
_getStateVal,
_isLazyAttr,
_normAttrVals,
_protectAttrs,
_set,
_setAttr,
_setAttrs,
_setAttrVal,
_setStateVal,
addAttr,
addAttrs,
attrAdded,
get,
getAttrs,
modifyAttr,
removeAttr,
reset,
set,
setAttrs
Methods inherited from Widget:
_afterDisabledChange,
_afterFocusedChange,
_afterHeightChange,
_afterVisibleChange,
_afterWidthChange,
_bindDOMListeners,
_bindUI,
_defRenderFn,
_getHtmlParser,
_getStrings,
_moveStyles,
_onDocMouseDown,
_onFocus,
_parseHTML,
_renderBox,
_renderBoxClassNames,
_renderUI,
_setBoundingBox,
_setBox,
_setContentBox,
_setStrings,
_syncUI,
_uiSetDisabled,
_uiSetFocused,
_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:
_aggregateAttrs,
_defDestroyFn,
_defInitFn,
_destroyHierarchy,
_filterAttrCfs,
_getAttrCfgs,
_getClasses,
_initHierarchy,
_initHierarchyData,
destroy,
init,
toString
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
maxGutterChange
(
event
)
Fires when the value for the configuration attribute 'maxGutter' 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
minGutterChange
(
event
)
Fires when the value for the configuration attribute 'minGutter' 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
positionThumb
(
event
)
Signals a request to reposition the thumb in response to API methods.
Triggers the thumb placement logic in _defPositionThumbFn.
- 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 _defPositionThumbFn.
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 _defSyncFn.
- Parameters:
-
event
<Event.Facade>
Event Facade object
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defSyncFn.
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
)
Bridges user interaction with the thumb to the value attribute.
- 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 _defThumbDragFn.
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
Events inherited from Widget:
boundingBoxChange,
contentBoxChange,
disabledChange,
focusedChange,
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
Value associated with the right or bottom most position of the thumb
on the rail.
Default Value: 100
Like CSS padding, the distance in pixels from the inner bottom or
right edge of the rail node within which the thumb can travel.
Negative values allow the edge of the thumb to escape the rail node
boundaries.
Default Value: 0
min
- Number
Value associated with the left or top most position of the thumb on
the rail.
Default Value: 0
Like CSS padding, the distance in pixels from the inner top or left
edge of the rail node within which the thumb can travel. Negative
values allow the edge of the thumb to escape the rail node
boundaries.
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,
focused,
height,
locale,
moveStyles,
rendered,
strings,
tabIndex,
visible,
width,
Configuration attributes inherited from Base: