SliderEntry

Version 25 by Adnan Durrani
on Apr 13, 2010 13:21.

<< Changes from 24 to 25
compared with
Current by Arturo Zambrano
on Dec 11, 2014 12:39.

 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 47 changes. View first change.

 h1. Getting Started:
  h2. Overview
 _Since 2.0_
  
To use the slider component, first the sparkle component name-space has to be added in your page.
 {code:xml}
 <html xmlns:ann="http://www.icesoft.com/icefaces/component/annotated"
  ..>
 {code}
  
  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.
  
The second step is to apply yui-skin-name on the parent element of slider component.
 {code:xml}
 <h:form styleClass="yui-skin-name">
 {code}
  It can be used as a visual replacement for an input box that takes a number as input.
  
&nbsp; !hSlider.jpg!
  
Now you ready to use slider component, here is the basic example:
 {code:xml}
 <ann:slider />
 {code}
  {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}
  
  
By now page should look like this:
 {code:xml}
 <html xmlns:ann="http://www.icesoft.com/icefaces/component/annotated"
 ..>
 <body>
  <h:form styleClass="yui-skin-name">
  <ann:slider />
  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}
 &nbsp;Now you ready to use slider component, here is the basic example:
 {code:xml}<ace:sliderEntry/>
 {code}
 &nbsp;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>
<body>
 <html>
   <ace:sliderEntry />
  </h:form>
 </h:body>
 </html>
 {code}
  
h2. Attributes
  
h1. YUI 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}
  <ann:slider value="60"/>
  The *value* attribute of slider represents the current value. The default is 0.
 {code:xml|borderStyle=dashed} <ace:sliderEntry value="60"/>
  
//using managed bean
 <ann:slider value="#{bean.value}"/>
  //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.
  The *min* attribute specify value at the far left ot top of the rail. Default is 0.
  
{code:xml}
  <ann:slider min="10"/>
  {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 0.
 {code:xml}
  <ann:slider max="60"/>
  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:*
This attribute specifies horizontal or vertical slider, "y" is for vertical. The default value is "x".
 {code:xml}
 <ann:slider axis="y"/>
  &nbsp; !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}
  
 
 *Defining the rail size of the slider:*
 The railSize attribute defines the height of vertical Slider rail and width of horizontal slider rail. Default value is 150px.
 {code:xml}
  <ann:slider railSize="250px"/>
  {panel}
 *&nbsp; Defining the length of the slider:*
 !railSize.jpg!
 &nbsp; 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}
  
*Defining the thumb image:*
 The thumbImage attribute takes the path to an image to use as the <img> for the thumb. Default is /skins/sam/thumb-classic-x.png
 {code:xml}
  <ann:slider thumbImage="images/slider/myThumb.png" />
  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}
  
 
 h1. Additional attributes:
  h2. Client Behavior Events
  
*Defining style:*
 The is a pass through to the root element of the slider.
  | 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). |
  
*Defining style class:*
 The is a pass through to the root element of the slider.
  {code:xml|borderStyle=dashed}<ace:sliderEntry value="#{bean.value}" >
  <ace:ajax event="slide" execute="@this" render="sliderValueOutput" />
 </ace:sliderEntry>
 {code}
  
*Defining tabindex:*
 The is a pass through to the root element of the slider.
  h2. JavaScript API
  
*Defining the submission behaviour:*
 When singleSubmit attribute is true, the slider value change event request a submit call with execute=@this and render=@all, if false then full submit happens where execute being set to @all. default valid is false.
  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.
  
*When to submit slider:*
 The submitOn attribute, allows you to define when to notify server. 3 possible values are "slideStart", "slideEnd" and "slideInterval". Default is "slideEnd"
  {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}
  
{code:xml}
  <ann:slider submitOn="slideStart" />
 {code}
  
 *Defining slideInterval, when submitOn is set to "slideInterval":*
 The slideInterval attribute comes into an effect when you use submitOn="slideInterval". The sliderInterval take the value of interval, default is 500 milliseconds.
  h4. ICEfaces 4+
  
{code:xml}
  <ann:slider submitOn="slideInterval" slideInterval="300"/>
 {code}
  
  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.
  
*Capture value change event:*
 The slider component fires a valueChange event, which can be captured using a valueChangeListener attribute on slider component.
  {code}widget = ice.ace.instance('frm:mySlider');{code}
  
{code:xml}
  <ann:slider valueChangeListener="#{bean.sliderChanged}"/>
 {code}
  To illustrate this change, see the before and after code example below.
  
h5. Before (ICEfaces 3 API)
  
h1. Keyboard and ARIA support:
 Slider component supports keyboard short-cuts and ARIA. Aria support can be enabled at page level or at application level. By default ARIA is enabled at application level.
  {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}
  
To enable/disable ARIA at page level, the ice:config tag handler can used:
  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}
  
{code:xml}
  <ice:config ariaEnabled="true"/>
 {code}
  {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
  
To enable/disable ARIA at application level, the following param can be set in web.xml.
 {code:xml}
  <context-param>
  <param-name>org.icefaces.aria.enabled</param-name>
  <param-value>false</param-value>
  </context-param>
 {code}
  || 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.
  
h3. Keyboard short-cuts supported by Slider:
 * left arrow and down arrow: decrease the value of the slider.
 * right arrow and 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.
  h2. CSS Classes
  
h1. Get the JS Slider object on client:
 The javascript representation of slider component can be get on client using the following helper API:
  The following markup represents the basic HTML structure of the component and the CSS classes it uses.
  
{code:xml}
  ice.yui.slider.getInstance(clientId, callback);
  {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
  
  
 For example:
 {code:xml}
  <h:form id="myform">
  <ann:slider id="myslider" value="#{bean.value}"/>
  <input type="button" value="get slider value" onclick="ice.yui.slider.getInstance('myform:myslider', function(slider) {
 alert(slider.get('value'));
 })"/>
  </h:form>
 {code}
  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*

© Copyright 2021 ICEsoft Technologies Canada Corp.