Event Management using C-Chip Framework
Events are what brings your app to life. ChocolateChip-UI provides several ways for you to add events. The following are the core events. These work on desktop as well as mobile:
- $.eventStart
- $.eventMove
- $.eventEnd
- $.eventCancel
Because you might be testing your app on the desktop as well as simulators and actual devices, ChocolateChip-UI renders these four event aliases differently depending on what the app is running on.
On desktop:
- $.eventStart: mousedown
- $.eventMove: mousemove
- $.eventEnd: mouseup
- $.eventCancel: mousecancel
On Android:
- $.eventStart: touchstart
- $.eventMove: touchmove
- $.eventEnd: touchend
- $.eventCancel: touchcancel
On iOS:
- $.eventStart: touchstart
- $.eventMove: touchmove
- $.eventEnd: touchend
- $.eventCancel: touchcancel
On Windows Phone 8 (IE10):
- $.eventStart: MSPointerDown
- $.eventMove: MSPointerMove
- $.eventEnd: MSPointerEnd
- $.eventCancel: MSPointerCancel
On Windows Phone 8 (IE11):
- $.eventStart: pointerdown
- $.eventMove: pointermove
- $.eventEnd: pointerup
- $.eventCancel: pointercancel
By using these event aliases you can write code that works across computing platforms:
$('#myButton').on($.eventStart, function() {
alert('You pushed my button!')
});On mobile devices there is a 45O millisecond delay from the time the user clicks to the execution of the click event. This results in interactions that feel sluggish and annoying. Many developers there prefer to use either touchstart or touchend events registered on buttons and other interactive controls. There is one problem with this approach: scrolling. If you have content in a scrollable container and attach a touchstart or touchend event, as soon as you try to scroll your content and touch an element with these, you could immediately cause the touch event to execute. This makes it extremely hard to scroll interactive content. To get around this problem, ChocolateChip-UI has a gestures module.
When using these, think of them as event aliases. As such you need to use them like you would a JavaScript variable–without quotes. If you use quotes on them, jQuery will not resolve their value and nothing will happen.
In contrast to these aliased events, ChocolateChip-UI provides the following gestures which you can use like any other event:
- singletap: 120 milliseconds delay
- longtap: 750 milliseconds
- doubletap: second tap occurs at most 250 milliseconds after first tap
- swipe: must be at least
- swipeup
- swipedown
- swipeleft
- swiperight
Using a swipe gesture:
$('.list li').on('swiperight', function() {
// perform some action when the user
// swipes to the right on a list item:
alert('You just swiped to the right!');
// Output the text of the list item swiped on:
console.log($(this).text());
});Instead of using a $.eventStart or $.eventEnd event for your controls in scrollable containers, we recommend you use the singletap event. Since it has a delay of 150 milliseconds, it gives the user enough time to initiate a scroll event and thus prevent any interaction with items in the scrolling container. Actually, navigation lists specifically use singletaps to register their events. This lets you flick your finger to scroll a list without firing a navigation event. But if you touch a navigation list item and do not scroll, a singletap gets registered and navigation occurs.
Please note that these gestures do require quotes like normal events. If you fail to quote them, you will get an error about an undefined variable.
Look at the gestures demo in the examples to see how to use them.
Scrolling Lists and Events
If you want to have interactive targets in scrolling lists, such as buttons in list items. You need to use the singletap event. You also need to use stopPropagation() to prevent that event from reaching the navigation list. He’s a list item and the code to make it work:
<li class='comp' data-goto="places">
<span>
<button id='touchTest'>Click!</button>
</span>
<div>
<h3>Places</h3>
</div>
<aside>
<span class='nav'></span>
</aside>
</li>With the above markup, we can wireup the button as follows:
$(function() {
$('#touchTest').on('singletap', function(e) {
alert('you clicked me!');
e.stopPropagation();
});
});Notice that we are passing in e as a reference to the event, and then using that to fire e.stopPropagation() after we execute our code. This prevents the singletap event from reaching the navigation event. With this you can grab the button and scroll up or down and then let go, the button’s event will not fire. You can tap the list item content next to the button and a normal navigation will take place. Or you can tap directly on the button and you will get the alert.
So, when you want to have interactive targets in a scrolling list or anywhere where the user needs to scroll, use this combination of singletap and stopPropagation.