Merge pull request #3 from RVenkatesh/likert-scale-support

Likert scale support

Author: RVenkatesh

README.md

@@ -1,4 +1,4 @@
-# ember-slider
+# ember-slider [![GitHub version](https://badge.fury.io/gh/RVenkatesh%2Fember-slider.svg)](https://badge.fury.io/gh/RVenkatesh%2Fember-slider) [![npm version](https://badge.fury.io/js/%40love-open-source%2Fember-slider.svg)](https://badge.fury.io/js/%40love-open-source%2Fember-slider)
 
 This slider is built as an addon for ember applications. Follow the instructions in the [demo](https://github.com/RVenkatesh/Ember-slider#demo) section to see it in action.
 
@@ -26,9 +26,7 @@ Include the ember slider component in the template like any other normal ember c
 Add configuration options if necessary in the corresponding route's controller or component's object
 ```
 {
-    type: {
-        closed: true
-    },
+    type: 'closed',
     range: {
         min: 0,
         max: 100
@@ -44,7 +42,7 @@ The component provides different parameters as mentioned below.
 | Params | Default value | Description |
 | --- | --- | --- |
 | initialValue | ```0``` | To load the slider with value other than min value. |
-| config | ```null``` | General settings for the slider. Refer [Configurations options](https://github.com/RVenkatesh/Ember-slider#configuration-options) section for details about the different options available. |
+| config | ```null``` | General settings for the slider liker min & max, likert and more. Refer [Configurations options](https://github.com/RVenkatesh/Ember-slider#configuration-options) section for details about the different options available. |
 
 ##### Callback parameters
 
@@ -58,6 +56,29 @@ Apart the above parameters, the following are the callback function available fo
 
 | Option | Default | Description |
 | --- | --- | --- |
-| type | 'sleek' | Changes the look and feel of the slider. Currently it supports only 'sleek' and 'closed' |
+| type | 'sleek' | Changes the look and feel of the slider. Currently it supports only 'sleek' and 'closed'. |
 | range | { min: 0, max: 100 } | This object can be used to change the min and max of the slider. This can be of following format. ```{ min: `min_value`, max: `max_value` }``` |
-| noValue | false | Boolean to show or hide the display of value in the slider. ```true``` hides the value. |
+| hideValue | false | Boolean to show or hide the display of value in the slider. ```true``` hides the value. |
+| likert | {} | To enable slider as likert scale. Refer section [Likert scale options](https://github.com/RVenkatesh/Ember-Slider/tree/likert-scale-support#likert-scale-options) to know more about likert configuration. |
+
+##### Likert scale options
+The 'likert' configuration option allows the slider to function as likert scale. It can be enabled by passing the following to 'config' option 
+```
+{
+    likert: {
+        enabled: true
+    }
+}
+```
+
+Just enabling likert option would provide a 3-point likert scale slider with values ranging from 0 to 2. Likert scale can be customised by adding more settings inside likert. Following are the different likert config options available.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| enabled | false | Enable or disable likert scale |
+| points | 3 | Number of likert points to be shown. As of now ```ember-slider``` supports 3, 5 and 7 points. |
+| labels | [] | Label text to be displayed under each likert point of the slider. If nothing has to be displayed, pass ```null``` |
+
+
+## Updating ember-slider
+If you are updating one version of ember slider to other, please check out the [Release notes](https://github.com/RVenkatesh/Ember-Slider/wiki/Release-notes) page for any breaking changes (which are usually rare). 

addon/components/ember-slider.js

@@ -1,22 +1,41 @@
 import Component from '@ember/component';
 import layout from '../templates/components/ember-slider';
 import RecognizerMixin from 'ember-gestures/mixins/recognizers';
+import { next } from '@ember/runloop';
+
+const LIKERT_DEFAULT = 3;
 
 export default Component.extend(RecognizerMixin, {
   layout,
   classNames: 'ember-slider',
   recognizers: 'pan tap',
-  classNameBindings: ['config.type.closed', 'config.noValue', 'sliding', 'leftClosing', 'rightClosing', 'animate'],
+  classNameBindings: [
+    'config.type', 
+    'config.type.closed', 
+    'config.noValue', 
+    'config.hideValue', 
+    'sliding', 
+    'leftClosing', 
+    'rightClosing', 
+    'animate', 
+    'likertEnabled'
+  ],
+  likertPoints: null,
   config: null,
   initialValue: null,
   value: null,
   onChange() {},
   init() {
     this._super(...arguments);
 
-    // Copy config for easier use
-    this.set('min', this.get('config.range.min') || 0);
-    this.set('max', this.get('config.range.max') || 100);
+    if (this.get('config.likert.enabled')) {
+      this.set('likertEnabled', true);
+      this.generateLikertPoints();
+    } else {
+      // Copy config for easier use
+      this.set('min', this.get('config.range.min') || 0);
+      this.set('max', this.get('config.range.max') || 100);
+    }
   },
   didInsertElement() {
     this._super(...arguments);
@@ -28,60 +47,122 @@ export default Component.extend(RecognizerMixin, {
     this.set('SLIDER_COLOR_FILLER_CLOSED', this.$('.slider-color-filler-closed'));
     this.moveToInitialValue();
   },
+  // Saves the handle position at present to the component variable
+  // and then reuse it to during the events like sliding to easily
+  // work with the state of the slider before the event started
   lockHandlePosition() {
     let handle_left = parseInt(this.get('SLIDER_HANDLE').position().left);
     this.set('_LOCKED_HANDLE_POSITION', handle_left);
   },
 
-  moveHandle(positionInPX, animate) {
+  // WARNING: DO NOT TOUCH THIS UNLESS NECESSARY
+  // This is the core function of this component which takes care of moving the handle
+  // and updating the value based on the required movement percentage
+  moveToPercentage(percentage, animate) {
     if (animate) {
       this.set('animate', true);
     } else {
       this.set('animate', false);
     }
-    let {min, 
-      max, 
-      SLIDER_PATH, 
-      SLIDER_HANDLE,
+
+    let { min, 
+      max, SLIDER_HANDLE,
       SLIDER_COLOR_FILLER,
       SLIDER_COLOR_FILLER_CLOSED
-    } = this.getProperties('min', 'max', 'SLIDER_PATH', 'SLIDER_HANDLE', 'SLIDER_COLOR_FILLER', 'SLIDER_COLOR_FILLER_CLOSED');
+    } = this.getProperties('min', 'max','SLIDER_HANDLE', 'SLIDER_COLOR_FILLER', 'SLIDER_COLOR_FILLER_CLOSED');
 
     let difference  = max - min;
-    let pathWidth = SLIDER_PATH.width();
-
-    let movedPercentage = (positionInPX / pathWidth) * 100;
-
-    // Make sure the percentage value stays within its boundaries
-    if (movedPercentage <= 0) {
-      movedPercentage = 0;
-    } else if (movedPercentage >= 100) {
-      movedPercentage = 100;
+     // Make sure the percentage value stays within its boundaries
+    if (percentage <= 0) {
+      percentage = 0;
+    } else if (percentage >= 100) {
+      percentage = 100;
     }
 
-    let newValue = Math.round(min + (movedPercentage * difference) / 100);
-    
-    this.get('onChange')(this.get('value'), newValue);
+    // Update the value based on the percentage
+    let newValue = Math.round(min + (percentage * difference) / 100);
     this.set('value', newValue);
-    let percentageString = movedPercentage + '%';
+
+    // Store percentage for easy usage
+    this.set('_percentage', percentage);
+    // Move the handle to the corresponding percentage
+    let percentageString = percentage + '%';
     SLIDER_HANDLE.css('left', percentageString);
     SLIDER_COLOR_FILLER.css('width', percentageString);
     SLIDER_COLOR_FILLER_CLOSED.css('width', percentageString);
-    // this.addClosenessClass(positionInPX, pathWidth);
   },
 
-  moveToInitialValue() {
-    // Right now this whole function looks ridiculous, 
-    // because value to percentage and percentage to value conversion happens
-    // Change this when the time comes
-    let {initialValue, min, max, SLIDER_PATH} = this.getProperties('initialValue', 'min', 'max', 'SLIDER_PATH');
-    let difference = max - min;
+  // Move the handle to a given px value
+  // Assumption: The pixel value is relative to the slider div
+  // which means it is the distance in px from the left most point of the slider
+  moveToPX(positionInPX, animate) {
+    let SLIDER_PATH = this.get( 'SLIDER_PATH');
     let pathWidth = SLIDER_PATH.width();
-    initialValue = initialValue === null ? min : initialValue;
-    let percentage = (initialValue - min) * 100 / difference;
-    let positionInPX = percentage * pathWidth / 100;
+    // Calculate the percentage corresponding to the position in px
+    let movedPercentage = (positionInPX / pathWidth) * 100;
+
+    this.moveToPercentage(movedPercentage, animate);
+  },
 
-    this.moveHandle(positionInPX);
+  // Move the handle based on the given slider value
+  // If the slider is likert, then the automatically move to nearest likert point
+  moveToValue(value, animate) {
+    let {min, max} = this.getProperties('min', 'max');
+    let difference = max - min;
+    // Calculate the percentage corresponding to the value of the slider
+    let percentage = (value - min) * 100 / difference;
+
+    if (this.get('likertEnabled')) {
+      this.moveToLikertByPercentage(percentage, animate);
+    } else {
+      this.moveToPercentage(percentage, animate);
+    }
+  },
+
+  // Move the slider to the initialValue passed to the component
+  moveToInitialValue(animate) {
+    let {initialValue, min} = this.getProperties('initialValue', 'min');
+    // Make sure the initial value is properly set otherwise move to the min
+    let value = typeof initialValue !== 'number' ? min : initialValue;
+    this.moveToValue(value, animate);
+  },
+
+  moveToLikertPointFromPX(positionInPX, animate) {
+    let SLIDER_PATH = this.get('SLIDER_PATH');
+    let pathWidth = SLIDER_PATH.width(),
+      // Calculate the percentage corresponding to the position in px
+      movedPercentage = (positionInPX / pathWidth) * 100;
+    
+    this.moveToLikertByPercentage(movedPercentage, animate);
+  },
+
+  moveToLikertByPercentage(percentage, animate) {
+    let distance = this.get('likertDistance'),
+      percentageToMove = Math.round(percentage / distance) * distance;
+
+      // Get only the percentage in multiples of distance to make sure
+      // the handle always lands in one of the likert points
+      // Move always to the nearest likert point
+      this.moveToPercentage(percentageToMove, animate);
+  },
+
+  generateLikertPoints() {
+    let totalPoints = this.get('config.likert.points') || LIKERT_DEFAULT,
+      labels = this.get('config.likert.labels'),
+      points = [],
+      distance = 100 / (totalPoints - 1);
+    this.set('likertDistance', distance);
+    this.set('min', 0);
+    this.set('max', totalPoints - 1);
+    for(let counter = 0; counter < totalPoints; counter++) {
+      // Based on the distance between likert points, generate data for likert points
+      // with amount of 'left' value to given to each of them
+      points.push({
+        left: counter * distance,
+        label: labels ? labels[counter] || '': ''
+      });
+    }
+    this.set('likertPoints', points);
   },
 
   // Add classes to the slider based on whether the handle is closer to left end or right end
@@ -101,8 +182,14 @@ export default Component.extend(RecognizerMixin, {
   tap(event) {
     let tapPosition = event.originalEvent.gesture.srcEvent.pageX;
     let sliderPathLeft = this.get('SLIDER_PATH').offset().left;
-
-    this.moveHandle(tapPosition - sliderPathLeft, true);
+    // Get old value to be passed to onchange event
+    let oldValue = this.get('value');
+    if (this.get('likertEnabled')) {
+      this.moveToLikertPointFromPX(tapPosition - sliderPathLeft, true);
+    } else {
+      this.moveToPX(tapPosition - sliderPathLeft, true);
+    }
+    this.get('onChange')(oldValue, this.get('value'));
   },
 
   panStart() {
@@ -113,15 +200,32 @@ export default Component.extend(RecognizerMixin, {
       return;
     }
     let gesture = event.originalEvent.gesture;
+    // Since hammer through ember-gestures is only giving us the total movement 
+    // for the current event, we need to take only the handle position before the 
+    // event started.
     let _LOCKED_HANDLE_POSITION = this.get('_LOCKED_HANDLE_POSITION');
-    this.moveHandle(_LOCKED_HANDLE_POSITION + gesture.deltaX);
+    // Get old value to be passed to onchange event
+    let oldValue = this.get('value');
+
+    this.moveToPX(_LOCKED_HANDLE_POSITION + gesture.deltaX);
+    this.get('onChange')(oldValue, this.get('value'));
   },
   panEnd() {
-    this.lockHandlePosition();
+    let sliding = this.get('sliding');
     this.set('sliding', false);
+    // Do this to get 'sliding' class properly removed before adding animate class
+    // since both these are not designed in a way to work together
+    next(this, function() {
+      if (this.get('likertEnabled') && sliding) {
+        this.moveToValue(this.get('value'), true);
+      }
+    });
+    this.lockHandlePosition();
   },
   actions: {
     handleMoveStart() {
+      // Make this boolean 'true', in order to make sure we are capturing pan event
+      // which originated from the handle
       this.set('sliding', true);
     }
   }