h2. Overview
_Since 2.0_
The _ace:sliderEntry_ component enables the user to adjust values in a finite range along a horizontal or vertical axis via dragging the slider control along the slider bar, or pressing the arrow-keys.
It can be used as a visual replacement for an input box that takes a number as input.
!hSlider.jpg!
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=slider] of this component, complete with source code.{tip}
h2. Getting Started
To use the slider component, first the ace component name-space has to be added in your page.
{code:xml}<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
{code}
Now you ready to use slider component, here is the basic example:
{code:xml}<ace:sliderEntry/>
{code}
By now page should look like this:
{code:xml}<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
<h:head></h:head>
<h:body>
<h:form>
<ace:sliderEntry />
</h:form>
</h:body>
</html>
{code}
h2. Attributes
{tip:title=TagLib Documentation}This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available [here|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/sliderEntry.html].{tip}
{panel}
*Define the value of slider:*
The *value* attribute of slider represents the current value. The default is 0.
{code:xml|borderStyle=dashed} <ace:sliderEntry value="60"/>
//using managed bean
<ace:sliderEntry value="#{bean.value}"/>
{code}
{panel}
{panel}
*Minimum value of slider:*
The *min* attribute specify value at the far left ot top of the rail. Default is 0.
{code:xml|borderStyle=dashed} <ace:sliderEntry min="10"/>
{code}
{panel}
{panel}
*Maximum value of slider:*
The *max* attribute specify value at the far right or bottom of the rail. Default is 100.
{code:xml|borderStyle=dashed} <ace:sliderEntry max="60"/>
{code}
{panel}
{panel}
*Changing the axis:*
!vSlider.jpg!
The *axis* attribute specifies the axis-orientation of the slider bar, "x" for horizontal, and "y" is for vertical. The default value is "x".
{code:xml|borderStyle=dashed} <ace:sliderEntry axis="y"/>
{code}
{panel}
{panel}
* Defining the length of the slider:*
!railSize.jpg!
The *length* attribute defines the height of vertical Slider rail and width of horizontal slider rail. Default value is "150px".
{code:xml|borderStyle=dashed} <ace:sliderEntry length="300px"/>
{code}
{panel}
{panel}
!showLabels.png!
*showLabels* Defines whether or not labels for the min and max values should be rendered at the ends of the rail.
{panel}
h2. Event Listeners
| valueChangeListener | Used to define a server-side valueChangeListener which will be notified each time the slider value is changed. The valueChangeEvent is fired whenever the "slideEnd" client event fires. |
{code:xml|borderStyle=dashed} <ace:sliderEntry valueChangeListener="#{bean.sliderChanged}"/>
{code}
h2. Client Behavior Events
| slideBegin | Fired when a drag operation on the slider control is initiated. |
| slide | Fired each time the the slider control is moved during a drag operation. |
| slideEnd | Fired when a drag operation is completed by releasing the slider control (default event). |
{code:xml|borderStyle=dashed}<ace:sliderEntry value="#{bean.value}" >
<ace:ajax event="slide" execute="@this" render="sliderValueOutput" />
</ace:sliderEntry>
{code}
h2. JavaScript API
h4. ICEfaces 3.x
The client side slider object is exposed through the global variable name specified in the *widgetVar* attribute. You can use the *getValue()* and *setValue()* methods to read and change the value.
{panel}
{code:xml|borderStyle=dashed}
<ace:sliderEntry widgetVar="sampleSlider" value="#{bean.value}" />
<h:commandButton value="Show Value" onclick="alert('Value:' + sampleSlider.getValue());" ... />
<h:commandButton value="Reset" onclick="sampleSlider.setValue(0);" ... />
{code}
{panel}
h4. ICEfaces 4+
The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use. You can use the *getValue()* and *setValue()* methods as described above.
{code}widget = ice.ace.instance('frm:mySlider');{code}
To illustrate this change, see the before and after code example below.
h5. Before (ICEfaces 3 API)
{panel}
{code:xml|borderStyle=dashed}
<ace:sliderEntry widgetVar="sampleSlider" value="#{bean.value}" />
<h:commandButton value="Show Value" onclick="alert('Value:' + sampleSlider.getValue());" ... />
<h:commandButton value="Reset" onclick="sampleSlider.setValue(0);" ... />
{code}{panel}
h5. After (ICEfaces 4 API)
{panel}{code:xml|borderStyle=dashed}
<ace:sliderEntry id="mySlider" value="#{bean.value}" />
<h:commandButton value="Show Value" onclick="alert('Value:' + ice.ace.instance('frm:mySlider').getValue());" ... />
<h:commandButton value="Reset" onclick="ice.ace.instance('frm:mySlider').setValue(0);" ... />
{code}{panel}
{tip}The _ice.ace.instance_ function requires the _full_ client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use {{prependId="false"}} in the enclosing form (e.g. _<h:form prependId="false">_).{tip}
h2. Keyboard and ARIA Support
|| Keypress || Result ||
| Left Arrow or Down Arrow | Decrease the value of the slider. |
| Right Arrow or Up Arrow | Increase the value of the slider. |
| Home key | Move to the minimum value of the slider. |
| End key | Move to the maximum value of the slider. |
The following ARIA roles are supported: slider.
h2. CSS Classes
The following markup represents the basic HTML structure of the component and the CSS classes it uses.
{code:xml}
<div class="[user defined classes]" style="[user defined styles]">
<input />
<div></div>
<div class="ui-slider ui-slider-horizontal ui-widget ui-widget-content ui-corner-all">
<a class="ui-slider-handle ui-state-default ui-corner-all"></a>
</div>
<div></div>
</div>
{code}
h2. Known Issues
The following known issues exist for the sliderEntry:
* The 'showLabels' attribute is not functional in ICEfaces 3.0.0. It does work correctly in 2.0.x and again in ICEfaces-3.3.0
h2. Additional Resources
h4. Sample Applications
The sliderEntry component appears in the following ICEfaces sample applications:
*ICEfaces Showcase*
* [Slider Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=slider]
* Located under _/icefaces/samples/showcase_.
h4. Tutorials
The sliderEntry component appears in the following ICEfaces tutorials:
*None*
_Since 2.0_
The _ace:sliderEntry_ component enables the user to adjust values in a finite range along a horizontal or vertical axis via dragging the slider control along the slider bar, or pressing the arrow-keys.
It can be used as a visual replacement for an input box that takes a number as input.
!hSlider.jpg!
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=slider] of this component, complete with source code.{tip}
h2. Getting Started
To use the slider component, first the ace component name-space has to be added in your page.
{code:xml}<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
{code}
Now you ready to use slider component, here is the basic example:
{code:xml}<ace:sliderEntry/>
{code}
By now page should look like this:
{code:xml}<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
<h:head></h:head>
<h:body>
<h:form>
<ace:sliderEntry />
</h:form>
</h:body>
</html>
{code}
h2. Attributes
{tip:title=TagLib Documentation}This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available [here|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/sliderEntry.html].{tip}
{panel}
*Define the value of slider:*
The *value* attribute of slider represents the current value. The default is 0.
{code:xml|borderStyle=dashed} <ace:sliderEntry value="60"/>
//using managed bean
<ace:sliderEntry value="#{bean.value}"/>
{code}
{panel}
{panel}
*Minimum value of slider:*
The *min* attribute specify value at the far left ot top of the rail. Default is 0.
{code:xml|borderStyle=dashed} <ace:sliderEntry min="10"/>
{code}
{panel}
{panel}
*Maximum value of slider:*
The *max* attribute specify value at the far right or bottom of the rail. Default is 100.
{code:xml|borderStyle=dashed} <ace:sliderEntry max="60"/>
{code}
{panel}
{panel}
*Changing the axis:*
!vSlider.jpg!
The *axis* attribute specifies the axis-orientation of the slider bar, "x" for horizontal, and "y" is for vertical. The default value is "x".
{code:xml|borderStyle=dashed} <ace:sliderEntry axis="y"/>
{code}
{panel}
{panel}
* Defining the length of the slider:*
!railSize.jpg!
The *length* attribute defines the height of vertical Slider rail and width of horizontal slider rail. Default value is "150px".
{code:xml|borderStyle=dashed} <ace:sliderEntry length="300px"/>
{code}
{panel}
{panel}
!showLabels.png!
*showLabels* Defines whether or not labels for the min and max values should be rendered at the ends of the rail.
{panel}
h2. Event Listeners
| valueChangeListener | Used to define a server-side valueChangeListener which will be notified each time the slider value is changed. The valueChangeEvent is fired whenever the "slideEnd" client event fires. |
{code:xml|borderStyle=dashed} <ace:sliderEntry valueChangeListener="#{bean.sliderChanged}"/>
{code}
h2. Client Behavior Events
| slideBegin | Fired when a drag operation on the slider control is initiated. |
| slide | Fired each time the the slider control is moved during a drag operation. |
| slideEnd | Fired when a drag operation is completed by releasing the slider control (default event). |
{code:xml|borderStyle=dashed}<ace:sliderEntry value="#{bean.value}" >
<ace:ajax event="slide" execute="@this" render="sliderValueOutput" />
</ace:sliderEntry>
{code}
h2. JavaScript API
h4. ICEfaces 3.x
The client side slider object is exposed through the global variable name specified in the *widgetVar* attribute. You can use the *getValue()* and *setValue()* methods to read and change the value.
{panel}
{code:xml|borderStyle=dashed}
<ace:sliderEntry widgetVar="sampleSlider" value="#{bean.value}" />
<h:commandButton value="Show Value" onclick="alert('Value:' + sampleSlider.getValue());" ... />
<h:commandButton value="Reset" onclick="sampleSlider.setValue(0);" ... />
{code}
{panel}
h4. ICEfaces 4+
The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use. You can use the *getValue()* and *setValue()* methods as described above.
{code}widget = ice.ace.instance('frm:mySlider');{code}
To illustrate this change, see the before and after code example below.
h5. Before (ICEfaces 3 API)
{panel}
{code:xml|borderStyle=dashed}
<ace:sliderEntry widgetVar="sampleSlider" value="#{bean.value}" />
<h:commandButton value="Show Value" onclick="alert('Value:' + sampleSlider.getValue());" ... />
<h:commandButton value="Reset" onclick="sampleSlider.setValue(0);" ... />
{code}{panel}
h5. After (ICEfaces 4 API)
{panel}{code:xml|borderStyle=dashed}
<ace:sliderEntry id="mySlider" value="#{bean.value}" />
<h:commandButton value="Show Value" onclick="alert('Value:' + ice.ace.instance('frm:mySlider').getValue());" ... />
<h:commandButton value="Reset" onclick="ice.ace.instance('frm:mySlider').setValue(0);" ... />
{code}{panel}
{tip}The _ice.ace.instance_ function requires the _full_ client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use {{prependId="false"}} in the enclosing form (e.g. _<h:form prependId="false">_).{tip}
h2. Keyboard and ARIA Support
|| Keypress || Result ||
| Left Arrow or Down Arrow | Decrease the value of the slider. |
| Right Arrow or Up Arrow | Increase the value of the slider. |
| Home key | Move to the minimum value of the slider. |
| End key | Move to the maximum value of the slider. |
The following ARIA roles are supported: slider.
h2. CSS Classes
The following markup represents the basic HTML structure of the component and the CSS classes it uses.
{code:xml}
<div class="[user defined classes]" style="[user defined styles]">
<input />
<div></div>
<div class="ui-slider ui-slider-horizontal ui-widget ui-widget-content ui-corner-all">
<a class="ui-slider-handle ui-state-default ui-corner-all"></a>
</div>
<div></div>
</div>
{code}
h2. Known Issues
The following known issues exist for the sliderEntry:
* The 'showLabels' attribute is not functional in ICEfaces 3.0.0. It does work correctly in 2.0.x and again in ICEfaces-3.3.0
h2. Additional Resources
h4. Sample Applications
The sliderEntry component appears in the following ICEfaces sample applications:
*ICEfaces Showcase*
* [Slider Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=slider]
* Located under _/icefaces/samples/showcase_.
h4. Tutorials
The sliderEntry component appears in the following ICEfaces tutorials:
*None*