Tweaks and improvements

README.md

@@ -1,26 +1,170 @@
 # Zepto Range
 
-http://jcemer.com/zepto-range
+Input range slider to work with touch using Zepto
 
-Input range implementation to works with touch using Zepto
+http://stormtek.github.io/zepto-range/
+
+----------------------------------------------------------
+### File imports to add to header of html
+
+``` html
+<link rel="stylesheet" href="zepto-range.css"/>
+<script src="zepto.js"></script>
+<script src="zepto-range.js"></script>
+```
+
+**Tip:** For quicker load times use ```zepto.min.js``` rather than ```zepto.js``` as it is the minified version of the javascript for the main zepto library. Both files are included in this repository for your convenience. If you are building ```zepto.js``` and ```zepto.min.js``` from the source make sure to include the touch module if you are planning on supporting mobile / tablets.
+
+**Note:** If performance (loading time) is a big issue then feel free to place the ```<script>``` tags for the javascript at the end of the body, rather than in the header. Just make sure that they are above the javascript that sets up the sliders.
+
+----------------------------------------------------------
+### Input fields that the slider is built around
 
 ``` html
-<input type="range" min="0" max="4" value="0">
+<input type="range" min="0" max="4">
 <input type="range" class="inside" min="-5" max="5" value="0">
+<input type="range" min="0" max="2" width="300">
+```
+
+#### Required Parameters
+
+- type="range"
+ - Identifies this as a range slider
+- min="some_integer"
+ - The minimum value this slider has
+- max="some_integer_greater_than_min"
+ - The maximum value this slider has
+
+**Note:** The number of integers between min and max determine the number of options that the slider has.
+
+#### Optional Parameters
+
+- value="some_integer_between_min_and_max"
+ - The initial value that is set for the slider
+ - This will default to min if it is not set
+ - **Note:** This is not an index point but one of the values that lies between max and min
+- width="some_integer"
+ - The width that you want the slider to be
+- class="inside" or class="normal"
+ - This determines whether the outside option lines sit inside the slider or even with the visible ends of the slider
+ - If nothing is specified then this defaults to class="normal"
+- showEmptyLabels="true" or showEmptyLabels="false"
+ - By setting this to false you can choose to show nothing for those empty labels, hiding them from the user
+ - If nothing is specified then this defaults to showEmptyLabels="true"
+- fillColor="desired_colour"
+ - The color that you want the fill bar to be
+ - If nothing is specified then this defaults to the predefined color
+ - This takes a css color property (either a hex value or an acceptable color name)
+- showFill="true" or showFill="false"
+ - By setting this to false you can choose to hide the coloured fill element of the slider
+ - If nothing is specified then this defaults to showing the coloured fill element
+- rtl="true" or rtl="false"
+ - By setting this to true you can choose to use an RTL layout for the slider. This reverses the order of the labels that have been specified (or auto-generated) and fills from right to left rather than left to right. This is useful when using the slider with an RTL language such as Arabic or Hebrew.
+
+**Note:** If a width is not specified then the width of an ancestor object will be grabbed. If no ancestor has it's width specified then this will end up being the width of the page. To guarantee that width and layout work correctly it is recommended to specify a width for the input field. One thing to note is that if the width you specify for the slider is greater than the width of a wrapping container then the slider is likely to have issues displaying correctly - the options will probably wrap in strange ways.
+
+**Tip:** If you use a large number of values (e.g. min="0", max="200") and hide the labels (using showEmptyLabels="false") then it is possible to simulate a smooth continuous slider.
+
+**Note:** The combination of width of the slider and number of options that the slider has is used to calculate the width that each label should be. The slider does it's best to make sure that the labels are evenly spaced between min and max, but this gets difficult with high numbers of values - particularly with a smaller width. This is because we are needing to handle the case where the width of an individual label is less than 1 pixel. If the labels are not quite lining up, try fiddling with the width of the slider and the min / max values to alleviate the problem. The layout should work well in most scenarios, but there are unfortunately no guarantees for extreme cases (100's of options with a width of only a few hundred pixels is likely to look a little weird).
+
+----------------------------------------------------------
+### Gaining access to the input field
+
+``` javascript
+$('#wrapper_id input[type="range"]')
+$('#input_field_id')
+$('input[type="range"]')
 ```
 
+- The parameter to $() is a DOM selector for the input field
+- The first example will return all input fields inside the field with #wrapper_id
+- The second example will return the field with the specified id (it is up to you to make sure that this is actually an input field, not something like a div)
+- The final example will return all input fields on the page (useful if you want to construct all sliders at once with default labels)
+
+**Tip:** The safest option is to wrap each input field in a div which has an id set on it. That way you can use the first example selector and know that you are interacting with a slider.
+
+----------------------------------------------------------
+### Javascript call to construct slider
+
+This needs to be added inside script tags at the end of the html. This guarantees that all the html is added to the DOM correctly before we start modifying it.
+
 ``` javascript
-$('input[type="range"]').range();
-$('input[type="range"]').range('worst', 'best');
+$('dom_selector').range();
+$('dom_selector').range('worst', 'best');
+$('dom_selector').range(['1', '2', '3']);
 ```
 
-## Modes
+- The function range() can take 3 types of parameter (as shown above):
+ 1. No parameters (the min and max values set on the input field will be shown)
+ 2. A list of strings to be shown as options
+ 3. An array of strings to be shown as options
 
-* `normal`
-* `inside`
+- If there is less than a one-to-one mapping of parameters to options then gaps will be added intelligently
+ - 1 parameter will cause things to break
+ - 2 parameters will map to the first and last option
+ - 3 parameters will map to the first, middle, and last option (provided there are an odd number of options ...)
+ - If equal sized gaps cannot be made then it will default back to simply showing lines
+ - Things work best for gaps if there are an odd number of options
 
-## Events
+----------------------------------------------------------
+### Javascript calls to interact with value
+
+``` javascript
+$('dom_selector').setValue(3);
+```
+
+- Make sure that the value passed in is an integer that is between min and max
+ - min <= x <= max
+
+``` javascript
+$('#wrapper_id input[type="range"]').getValue();
+```
+
+- This returns the current value that the slider has set
+
+----------------------------------------------------------
+### Javascript calls to modify fill colour
+
+``` javascript
+$('dom_selector').setFillColor('#332299');
+$('dom_selector').setFillColor('blue');
+```
+
+- This needs to be passed a valid css color
+ - It can be either a hex value or a predefined color
+
+``` javascript
+$('dom_selector').resetFillColor();
+```
+
+- This will reset the fill colour to the default value specified in the css
+
+----------------------------------------------------------
+### Javascript call to adjust width of slider
+
+``` javascript
+$('dom_selector').setWidth(300);
+```
+
+- This function expects an integer value for the width you want
+
+----------------------------------------------------------
+### Events
+
+- `init`
+- `move`
+- `change`
+
+You can set up a listener for any of these events using the javascript below
+
+``` javascript
+$('dom_selector').on('change', function(event, current, range) {
+//handle event here
+});
+```
 
-* `init`
-* `move`
-* `change`
+- 'event' is the name of the event that trigged the handler
+- 'current' is the current **index** the slider has set, rather than the current **value**
+- 'range' is the slider itself
+- To get the current value the slider has set use range.input[0].value
+ - For some reason range.getValue() does not work inside the event handler

index.html

@@ -4,52 +4,122 @@
     <meta charset="UTF-8">
     <title>Zepto Range</title>
     <meta name="viewport" content="width=600">
-    <link rel="stylesheet" href="styles.css">
-    <link href="//fonts.googleapis.com/css?family=Ubuntu:300,700" rel="stylesheet" type="text/css">
+    <link rel="stylesheet" href="styles.css"/>
+    <link rel="stylesheet" href="zepto-range.css"/>
+    <link href="//fonts.googleapis.com/css?family=Ubuntu:300,700" rel="stylesheet" type="text/css"/>
+    <script src="zepto.min.js"></script>
+    <script src="zepto-range.js"></script>
 </head>
 <body>
-    <div id="main">
-        <div class="wrapper">
-            <h1>Zepto Range</h1>
-            <p>Input range implementation to works with touch using Zepto.</p> 
-            <p><a href="//github.com/jcemer/zepto-range">github.com/jcemer/zepto-range</a></p>
-
-            <div id="samples-01">
-                <input type="range" min="0" max="4" value="0">
-                <input type="range" class="inside" min="0" max="4" value="0">
-            </div>
+    <div class="wrapper">
+        <h1>Zepto Range</h1>
+        <p>Input range implementation to works with touch using Zepto.</p> 
+        <p><a href="https://github.com/stormtek/zepto-range">github.com/stormtek/zepto-range</a></p>
+        <br/><br/>
+        <!-- two sliders nested inside the same div -->
+        <!-- one uses 'inside' mode to contrast the two -->
+        <div id="samples">
+        	<h2>Normal mode</h2>
+            <input type="range" min="0" max="600" value="0" showemptylabels="false">
+            <h2>Inside mode</h2>
+            <input type="range" class="inside" min="0" max="4">
+        </div>
 
-            <div id="samples-02">
-                <input type="range" class="inside" min="0" max="6" value="0">
-            </div>
+        <h2>Some Labels</h2>
+        <div id="some-labels">
+    		<button onclick="changeWidth('some-labels', 300)">Set width to 300px</button>
+    		<button onclick="changeWidth('some-labels', 700)">Set width to 700px</button>
+            <input type="range" class="inside" min="-4" max="4" value="-2" showEmptyLabels="false">
+        </div>
 
-            <div id="samples-03">
-                <input type="range" min="-4" max="4" value="0">
-            </div>
+        <h2>First and Last Label</h2>
+        <div id="first-and-last">
+            <input type="range" min="0" max="14" value="0">
+        </div>
 
-            <div id="samples-04">
-                <h2>Events</h2>
-                <input type="range" class="inside" min="0" max="2" value="1">
-            </div>
-
-            <script src="zepto.js"></script>
-            <script src="zepto-range.js"></script>
-            <script>
-                $('#samples-01 input[type="range"]').range();
-                $('#samples-02 input[type="range"]').range('0', '3', '6');
-                $('#samples-03 input[type="range"]').range('worst', 'best');
-
-                // SAMPLE 04
-                var sample04 = $('#samples-04 input[type="range"]');
-                sample04.on('change init', function (event, current, range) {
-                    var labels = range.legend.children();
-                    labels.removeClass('active');
-                    labels.eq(current).addClass('active');
-                });
-                sample04.range('worst', 'normal', 'best');
-            </script>
+        <div id="user-defined-color">
+            <h2>User Defined Fill Color</h2>
+            <input type="range" class="inside" min="0" max="2" value="1" fillColor="#339922">
+        </div>
+
+        <!-- Free standing input field -->
+        <h2>Free standing</h2>
+        <button onclick="changeFreestandingValue()">Set value to 2</button>
+        <button onclick="getFreestandingValue()">Set Output to Current Value</button>
+        <div>
+        	<p>Current Value: <span id="freestandingValue">Unknown</span></p>
+        	<p>Output: <span id="freestandingOutput">Unknown</span></p>
         </div>
-        <a href="//github.com/jcemer/zepto-range"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" alt="Fork me on GitHub"></a>
+        <button onclick="changeFreestandingColor()">Set colour to blue</button>
+        <button onclick="resetFreestandingColor()">Reset colour</button>
+        <input id="freestanding" class="inside" type="range" min="-5" max="3" value="0" width="300">
+
     </div>
+    <h2>Outside Wrapper div</h2>
+    <div id="outside">
+    	<input class="inside" type="range" min="-2" max="1" value="0">
+	</div>
+
+    <a href="https://github.com/stormtek/zepto-range">
+    	<img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" alt="Fork me on GitHub">
+    </a>
+    <!--
+		This script call needs to happen after the input fields have been added to
+		the html. If not then the addition of the slider divs does not happen.
+	-->
+    <script>
+        // No values to be shown
+        $('#samples input[type="range"]').range();
+        // Show value value for first, middle, last
+        $('#some-labels input[type="range"]').range('10', '3', '26');
+        // Show first and last values, sent through as an array
+        $('#first-and-last input[type="range"]').range(['worst', 'best']);
+
+        // Custom styling on the active label
+        var userDefinedColor = $('#user-defined-color input[type="range"]');
+        userDefinedColor.on('change init', function (event, current, range) {
+            var labels = range.legend.children();
+            labels.removeClass('active');
+            labels.eq(current).addClass('active');
+        });
+        userDefinedColor.range('worst', 'normal', 'best');
+
+        // This entry is outside the wrapper div, it deduces the width it should have
+        $('#outside input[type="range"]').range();
+
+        // This entry is not wrapped by a div
+        // it also has a lot of interactions defined based on button clicks
+        var freestanding = $('#freestanding');
+        freestanding.on('init change', function(event, current, range) {
+        	$('#freestandingValue')[0].innerHTML = range.input[0].value;
+        });
+        freestanding.range();
+
+        function setFreestandingOutput(value) {
+        	$('#freestandingOutput')[0].innerHTML = value;
+        }
+
+        // Methods to interact with sliders
+        function changeFreestandingValue() {
+        	freestanding.setValue(2);
+        }
+
+        function getFreestandingValue() {
+        	var value = freestanding.getValue();
+        	setFreestandingOutput(value);
+        }
+
+        function changeFreestandingColor() {
+        	freestanding.setFillColor('blue');
+        }
+
+        function resetFreestandingColor() {
+        	freestanding.resetFillColor();
+        }
+
+        function changeWidth(id, newWidth) {
+        	$('#' + id + ' input[type="range"]').setWidth(newWidth);
+        }
+    </script>
 </body>
-</html>
+</html>