SliderEntry

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 40 changes. View first change.

 h1. Getting Started
  h2. Overview
 _Since 2.0_
  
The Slider is a component that enables the user to adjust values in a finite range along a horizontal or vertical axis.
  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.
  
To use the slider component, first the sparkle component name-space has to be added in your page.
 {code:xml}<html ... xmlns:ice="http://www.icefaces.org/icefaces/components">
 {code}
 &nbsp;The second step is to apply a skin name on a parent element of slider component.
 {code:xml}<h:form styleClass="ice-skin-rime">
 {code}
 &nbsp;Now you ready to use slider component, here is the basic example:
 {code:xml}<ice:sliderEntry/>
 {code}
 &nbsp; !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}
 &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:ice="http://www.icefaces.org/icefaces/components">
 <body>
  <h:form styleClass="ice-skin-rime">
  <ice:sliderEntry />
  {code:xml}<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
 <h:head></h:head>
 <h:body>
  <h:form>
  <ace:sliderEntry />
  </h:form>
</body>
  </h:body>
 </html>
 {code}
h1. Attributes
 {info: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/v2_0_0b2/ace/taglibdoc/ice/sliderEntry.html]
  
.{info}{*}Define the value of slider:*
 The value attribute of slider represents the current value. The default is 0.
 {code:xml} <ice:sliderEntry value="60"/>
  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
<ice:sliderEntry value="#{bean.value}"/>
  <ace:sliderEntry value="#{bean.value}"/>
 {code}
{*}Minimum value of slider:*
 The min attribute specify value at the far left ot top of the rail. Default is 0.
  {panel}
  
{code:xml} <ice:sliderEntry min="10"/>
  {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}
{*}Maximum value of slider:*
 The max attribute specify value at the far right or bottom of the rail. Default is 0.
 {code:xml} <ice:sliderEntry max="60"/>
  {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}
{*}Changing the axis:*
 This attribute specifies horizontal or vertical slider, "y" is for vertical. The default value is "x".
 {code:xml} <ice:sliderEntry axis="y"/>
 {code}
  {panel}
 {panel}
 *Changing the axis:*
 &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}
  
 
  {panel}
 *&nbsp; Defining the length of the slider:*
&nbsp; The length attribute defines the height of vertical Slider rail and width of horizontal slider rail. Default value is 150px.
 {code:xml} <ice:sliderEntry length="300px"/>
  !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}
!railSize.jpg!
 *&nbsp; Defining the thumb image:*
 &nbsp; The thumbUrl attribute takes the path to an image to use as the <img> for the thumb. Default is /skins/sam/thumb-x.png
 {code:xml} <ice:sliderEntry thumbUrl="images/slider/myThumb.png" />
  {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}
h1. Additional attributes
  
*&nbsp;Defining style:*
 &nbsp;The is a pass through to the root element of the slider.
  h2. Client Behavior Events
  
*&nbsp;Defining style class:*
 &nbsp;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). |
  
*&nbsp;Defining tabindex:*
 &nbsp;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}
  
*&nbsp;Defining the submission behaviour:*
 &nbsp;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.
  h2. JavaScript API
  
h4. ICEfaces 3.x
  
*&nbsp;When to submit slider:*
 &nbsp;The submitOn attribute, allows you to define when to notify server. 3 possible values are "slideStart", "slideEnd" and "slideInterval". Default is "slideEnd"
  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.
  
{code:xml} <ice:sliderEntry submitOn="slideStart" />
  {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}
*&nbsp;Defining slideInterval, when submitOn is set to "slideInterval":*
 &nbsp;The slideInterval attribute comes into an effect when you use submitOn="slideInterval". The sliderInterval take the value of interval, default is 500 milliseconds.
  {panel}
  
{code:xml} <ice:sliderEntry submitOn="slideInterval" slideInterval="300"/>
 {code}
 *&nbsp;Capture value change event:*
 &nbsp;The slider component fires a valueChange event, which can be captured using a valueChangeListener attribute on slider component.
  h4. ICEfaces 4+
  
{code:xml} <ice:sliderEntry valueChangeListener="#{bean.sliderChanged}"/>
 {code}
 {*}Making the rail clickable:*
 Clicking on the rail moves the thumb to that point. Default is true.
  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}
  
{code:xml} <ice:sliderEntry clickableRail="true" />
 {code}
 h1. Keyboard and ARIA support
  To illustrate this change, see the before and after code example below.
  
&nbsp;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.
  h5. Before (ICEfaces 3 API)
  
&nbsp;To enable/disable ARIA at page level, the [<icecore:config>|Core Tags#icecoreconfig] tag can used:
  {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}<icecore:config ariaEnabled="true"/>
 {code}
 &nbsp;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}
 h3. Keyboard short-cuts supported by SliderEntry
  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}
  
* 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.
  {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}
  
h1. Get the JS Slider object on client
  h2. Keyboard and ARIA Support
  
&nbsp;The javascript representation of slider component can be get on client using the following helper API:
  || 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. |
  
{code:xml} ice.component.slider.getInstance(clientId, callback);
  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}
 &nbsp;For example:
 {code:xml}<h:form id="myform">
  <ice:sliderEntry id="myslider" value="#{bean.value}"/>
  <input type="button" value="get slider value"
  onclick="ice.component.slider.getInstance(
  'myform:myslider', function(slider) { alert(slider.get('value')); })"/>
 </h:form>
 {code}
 Slider Story Board: !StoryBoard.jpg|align=center!
  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*

© Copyright 2018 ICEsoft Technologies Canada Corp.