Permalink
Browse files

README and LICENSE.

  • Loading branch information...
1 parent c3fb005 commit e08762eaadc1edb17a91a02cb87a7a31729927f1 @cheeaun committed May 22, 2011
Showing with 90 additions and 0 deletions.
  1. +21 −0 LICENSE
  2. +69 −0 README.md
View
21 LICENSE
@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Lim Chee Aun, <http://cheeaun.com/>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
View
@@ -0,0 +1,69 @@
+Tappable
+========
+
+Tappable is a simple, standalone library to invoke the **tap** event for touch-friendly web browsers. Currently it's only tested on iOS Mobile Safari as I don't have any other smartphones to test with. The codebase is heavily inspired by Matteo Spinelli's [Remove onClick delay on webkit for iPhone](http://cubiq.org/remove-onclick-delay-on-webkit-for-iphone) and Ryan Fioravanti's [Creating Fast Buttons for Mobile Web Applications](http://code.google.com/mobile/articles/fast_buttons.html).
+
+Here's how you implement the code:
+
+ tappable('elementID', function(){
+ alert('tap');
+ });
+
+Simple.
+
+Why 'tap'?
+----------
+
+First, it would be wise to read the articles linked above to understand the purpose of this script. But if you're lazy, take a look at this diagram:
+
+![Diagram 1](https://github.com/cheeaun/tappable/raw/master/diagrams/diagram-1.png)
+
+So, that's the **tap** event. But wait the minute, I can just use the `touchend` event to *simulate* a tap, right? Wrong, because:
+
+![Diagram 2](https://github.com/cheeaun/tappable/raw/master/diagrams/diagram-2.png)
+
+This means that once the finger moves, it will not fire the tap event. However, Tappable works in two special cases. First is the *normal* case:
+
+![Diagram 3](https://github.com/cheeaun/tappable/raw/master/diagrams/diagram-3.png)
+
+The second case is the `noScroll` mode, where moving your finger on the element will no make the page scroll. This is useful for mobile web apps which might implement their own *fixed* headers or sections on the page.
+
+![Diagram 4](https://github.com/cheeaun/tappable/raw/master/diagrams/diagram-4.png)
+
+Documentation
+-------------
+
+###Syntax
+
+ tappable(el, opts);
+
+### Arguments
+
+1. `el` - The element to be tapped.
+ * (*element*) The DOM element.
+ * (*string*) A string containing the id of the DOM element.
+2. `opt` - The options object or a function.
+ * (*objects*) The options to be passed.
+ * (*function*) The function to execute when tapped.
+
+### Options
+
+* noScroll - (*boolean*: defaults to false) Whether or not to scroll when *moving* on the element.
+* activeClass - (*string*: defaults to `tappable-active`) A string indicating the *active* class applied to the element.
+* onTap - (*function*) The function to execute when tapped.
+* onStart - (*function*) The function to execute when `touchstart` event is fired.
+* onMove - (*function*) The function to execute when `touchmove` event is fired.
+* onMoveOut - (*function*) The function to execute when touch moves *out* of the element, if `noScroll` is true.
+* onMoveIn - (*function*) The function to execute when touch moves back in the element, if `noScroll` is true.
+* onEnd - (*function*) The function to execute when `touchend` event is fired.
+* onCancel - (*function*) The function to execute when `touchcancel` event is fired or when touch moves, if `noScroll` is false.
+
+Contributing
+------------
+
+Feel free to fork this project! Help would be appreciated if this could be tested on Android, WebOS or any other touch-friendly browsers, not just mobile ones.
+
+License
+-------
+
+Tappable is licensed under the MIT license.

0 comments on commit e08762e

Please sign in to comment.