// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* This module provides a wrapper to encapsulate a lot of the common combinations of
* user interaction we use in Moodle.
*
* @module core/custom_interaction_events
* @copyright 2016 Ryan Wyllie <ryan@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
* @since 3.2
*/
define(['jquery', 'core/key_codes'], function($, keyCodes) {
// The list of events provided by this module. Namespaced to avoid clashes.
var events = {
activate: 'cie:activate',
keyboardActivate: 'cie:keyboardactivate',
escape: 'cie:escape',
down: 'cie:down',
up: 'cie:up',
home: 'cie:home',
end: 'cie:end',
next: 'cie:next',
previous: 'cie:previous',
asterix: 'cie:asterix',
scrollLock: 'cie:scrollLock',
scrollTop: 'cie:scrollTop',
scrollBottom: 'cie:scrollBottom',
ctrlPageUp: 'cie:ctrlPageUp',
ctrlPageDown: 'cie:ctrlPageDown',
enter: 'cie:enter',
accessibleChange: 'cie:accessibleChange',
};
// Static cache of jQuery events that have been handled. This should
// only be populated by JavaScript generated events (which will keep it
// fairly small).
var triggeredEvents = {};
/**
* Check if the caller has asked for the given event type to be
* registered.
*
* @method shouldAddEvent
* @private
* @param {string} eventType name of the event (see events above)
* @param {array} include the list of events to be added
* @return {bool} true if the event should be added, false otherwise.
*/
var shouldAddEvent = function(eventType, include) {
include = include || [];
if (include.length && include.indexOf(eventType) !== -1) {
return true;
}
return false;
};
/**
* Check if any of the modifier keys have been pressed on the event.
*
* @method isModifierPressed
* @private
* @param {event} e jQuery event
* @return {bool} true if shift, meta (command on Mac), alt or ctrl are pressed
*/
var isModifierPressed = function(e) {
return (e.shiftKey || e.metaKey || e.altKey || e.ctrlKey);
};
/**
* Trigger the custom event for the given jQuery event.
*
* This function will only fire the custom event if one hasn't already been
* fired for the jQuery event.
*
* This is to prevent multiple custom event handlers triggering multiple
* custom events for a single jQuery event as it bubbles up the stack.
*
* @param {string} eventName The name of the custom event
* @param {event} e The jQuery event
* @return {void}
*/
var triggerEvent = function(eventName, e) {
var eventTypeKey = "";
if (!e.hasOwnProperty('originalEvent')) {
// This is a jQuery event generated from JavaScript not a browser event so
// we need to build the cache key for the event.
eventTypeKey = "" + eventName + e.type + e.timeStamp;
if (!triggeredEvents.hasOwnProperty(eventTypeKey)) {
// If we haven't seen this jQuery event before then fire a custom
// event for it and remember the event for later.
triggeredEvents[eventTypeKey] = true;
$(e.target).trigger(eventName, [{originalEvent: e}]);
}
return;
}
eventTypeKey = "triggeredCustom_" + eventName;
if (!e.originalEvent.hasOwnProperty(eventTypeKey)) {
// If this is a jQuery event generated by the browser then set a
// property on the original event to track that we've seen it before.
// The property is set on the original event because it's the only part
// of the jQuery event that is maintained through multiple event handlers.
e.originalEvent[eventTypeKey] = true;
$(e.target).trigger(eventName, [{originalEvent: e}]);
return;
}
};
/**
* Register a keyboard event that ignores modifier keys.
*
* @method addKeyboardEvent
* @private
* @param {object} element A jQuery object of the element to bind events to
* @param {string} event The custom interaction event name
* @param {int} keyCode The key code.
*/
var addKeyboardEvent = function(element, event, keyCode) {
element.off('keydown.' + event).on('keydown.' + event, function(e) {
if (!isModifierPressed(e)) {
if (e.keyCode == keyCode) {
triggerEvent(event, e);
}
}
});
};
/**
* Trigger the activate event on the given element if it is clicked or the enter
* or space key are pressed without a modifier key.
*
* @method addActivateListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addActivateListener = function(element) {
element.off('click.cie.activate').on('click.cie.activate', function(e) {
triggerEvent(events.activate, e);
});
element.off('keydown.cie.activate').on('keydown.cie.activate', function(e) {
if (!isModifierPressed(e)) {
if (e.keyCode == keyCodes.enter || e.keyCode == keyCodes.space) {
triggerEvent(events.activate, e);
}
}
});
};
/**
* Trigger the keyboard activate event on the given element if the enter
* or space key are pressed without a modifier key.
*
* @method addKeyboardActivateListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addKeyboardActivateListener = function(element) {
element.off('keydown.cie.keyboardactivate').on('keydown.cie.keyboardactivate', function(e) {
if (!isModifierPressed(e)) {
if (e.keyCode == keyCodes.enter || e.keyCode == keyCodes.space) {
triggerEvent(events.keyboardActivate, e);
}
}
});
};
/**
* Trigger the escape event on the given element if the escape key is pressed
* without a modifier key.
*
* @method addEscapeListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addEscapeListener = function(element) {
addKeyboardEvent(element, events.escape, keyCodes.escape);
};
/**
* Trigger the down event on the given element if the down arrow key is pressed
* without a modifier key.
*
* @method addDownListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addDownListener = function(element) {
addKeyboardEvent(element, events.down, keyCodes.arrowDown);
};
/**
* Trigger the up event on the given element if the up arrow key is pressed
* without a modifier key.
*
* @method addUpListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addUpListener = function(element) {
addKeyboardEvent(element, events.up, keyCodes.arrowUp);
};
/**
* Trigger the home event on the given element if the home key is pressed
* without a modifier key.
*
* @method addHomeListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addHomeListener = function(element) {
addKeyboardEvent(element, events.home, keyCodes.home);
};
/**
* Trigger the end event on the given element if the end key is pressed
* without a modifier key.
*
* @method addEndListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addEndListener = function(element) {
addKeyboardEvent(element, events.end, keyCodes.end);
};
/**
* Trigger the next event on the given element if the right arrow key is pressed
* without a modifier key in LTR mode or left arrow key in RTL mode.
*
* @method addNextListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addNextListener = function(element) {
// Left and right are flipped in RTL mode.
var keyCode = $('html').attr('dir') == "rtl" ? keyCodes.arrowLeft : keyCodes.arrowRight;
addKeyboardEvent(element, events.next, keyCode);
};
/**
* Trigger the previous event on the given element if the left arrow key is pressed
* without a modifier key in LTR mode or right arrow key in RTL mode.
*
* @method addPreviousListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addPreviousListener = function(element) {
// Left and right are flipped in RTL mode.
var keyCode = $('html').attr('dir') == "rtl" ? keyCodes.arrowRight : keyCodes.arrowLeft;
addKeyboardEvent(element, events.previous, keyCode);
};
/**
* Trigger the asterix event on the given element if the asterix key is pressed
* without a modifier key.
*
* @method addAsterixListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addAsterixListener = function(element) {
addKeyboardEvent(element, events.asterix, keyCodes.asterix);
};
/**
* Trigger the scrollTop event on the given element if the user scrolls to
* the top of the given element.
*
* @method addScrollTopListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addScrollTopListener = function(element) {
element.off('scroll.cie.scrollTop').on('scroll.cie.scrollTop', function(e) {
var scrollTop = element.scrollTop();
if (scrollTop === 0) {
triggerEvent(events.scrollTop, e);
}
});
};
/**
* Trigger the scrollBottom event on the given element if the user scrolls to
* the bottom of the given element.
*
* @method addScrollBottomListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addScrollBottomListener = function(element) {
element.off('scroll.cie.scrollBottom').on('scroll.cie.scrollBottom', function(e) {
var scrollTop = element.scrollTop();
var innerHeight = element.innerHeight();
var scrollHeight = element[0].scrollHeight;
if (scrollTop + innerHeight >= scrollHeight) {
triggerEvent(events.scrollBottom, e);
}
});
};
/**
* Trigger the scrollLock event on the given element if the user scrolls to
* the bottom or top of the given element.
*
* @method addScrollLockListener
* @private
* @param {jQuery} element jQuery object to add event listeners to
*/
var addScrollLockListener = function(element) {
// Lock mousewheel scrolling within the element to stop the annoying window scroll.
element.off('DOMMouseScroll.cie.DOMMouseScrollLock mousewheel.cie.mousewheelLock')
.on('DOMMouseScroll.cie.DOMMouseScrollLock mousewheel.cie.mousewheelLock', function(e) {
var scrollTop = element.scrollTop();
var scrollHeight = element[0].scrollHeight;
var height = element.height();
var delta = (e.type == 'DOMMouseScroll' ?
e.originalEvent.detail * -40 :
e.originalEvent.wheelDelta);
var up = delta > 0;
if (!up && -delta > scrollHeight - height - scrollTop) {
// Scrolling down past the bottom.
element.scrollTop(scrollHeight);
e.stopPropagation();
e.preventDefault();
e.returnValue = false;
// Fire the scroll lock event.
triggerEvent(events.scrollLock, e);
return false;
} else if (up && delta > scrollTop) {
// Scrolling up past the top.
element.scrollTop(0);
e.stopPropagation();
e.preventDefault();
e.returnValue = false;
// Fire the scroll lock event.
triggerEvent(events.scrollLock, e);
return false;
}
return true;
});
};
/**
* Trigger the ctrlPageUp event on the given element if the user presses the
* control and page up key.
*
* @method addCtrlPageUpListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addCtrlPageUpListener = function(element) {
element.off('keydown.cie.ctrlpageup').on('keydown.cie.ctrlpageup', function(e) {
if (e.ctrlKey) {
if (e.keyCode == keyCodes.pageUp) {
triggerEvent(events.ctrlPageUp, e);
}
}
});
};
/**
* Trigger the ctrlPageDown event on the given element if the user presses the
* control and page down key.
*
* @method addCtrlPageDownListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addCtrlPageDownListener = function(element) {
element.off('keydown.cie.ctrlpagedown').on('keydown.cie.ctrlpagedown', function(e) {
if (e.ctrlKey) {
if (e.keyCode == keyCodes.pageDown) {
triggerEvent(events.ctrlPageDown, e);
}
}
});
};
/**
* Trigger the enter event on the given element if the enter key is pressed
* without a modifier key.
*
* @method addEnterListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addEnterListener = function(element) {
addKeyboardEvent(element, events.enter, keyCodes.enter);
};
/**
* Trigger the AccessibleChange event on the given element if the value of the element is changed.
*
* @method addAccessibleChangeListener
* @private
* @param {object} element jQuery object to add event listeners to
*/
var addAccessibleChangeListener = function(element) {
var onMac = navigator.userAgent.indexOf('Macintosh') !== -1;
var touchEnabled = ('ontouchstart' in window) || (('msMaxTouchPoints' in navigator) && (navigator.msMaxTouchPoints > 0));
if (onMac || touchEnabled) {
// On Mac devices, and touch-enabled devices, the change event seems to be handled correctly and
// consistently at this time.
element.on('change', function(e) {
triggerEvent(events.accessibleChange, e);
});
} else {
// Some browsers have non-normalised behaviour for handling the selection of values in a <select> element.
// When using Chrome on Linux (and possibly others), a 'change' event is fired when pressing the Escape key.
// When using Firefox on Linux (and possibly others), a 'change' event is fired when navigating through the
// list with a keyboard.
//
// To normalise these behaviours:
// - the initial value is stored in a data attribute when focusing the element
// - the current value is checked against the stored initial value when and the accessibleChange event fired when:
// --- blurring the element
// --- the 'Enter' key is pressed
// --- the element is clicked
// --- the 'change' event is fired, except where it is from a keyboard interaction
//
// To facilitate the change event keyboard interaction check, the 'keyDown' handler sets a flag to ignore
// the change event handler which is unset on the 'keyUp' event.
//
// Unfortunately we cannot control this entirely as some browsers (Chrome) trigger a change event when
// pressign the Escape key, and this is considered to be the correct behaviour.
// Chrome https://bugs.chromium.org/p/chromium/issues/detail?id=839717
//
// Our longer-term solution to this should be to switch away from using <select> boxes as a single-select,
// and make use of a dropdown of action links like the Bootstrap Dropdown menu.
var setInitialValue = function(target) {
target.dataset.initValue = target.value;
};
var resetToInitialValue = function(target) {
if ('initValue' in target.dataset) {
target.value = target.dataset.initValue;
}
};
var checkAndTriggerAccessibleChange = function(e) {
if (!('initValue' in e.target.dataset)) {
// Some browsers trigger click before focus, therefore it is possible that initValue is undefined.
// In this case it's likely that it's being focused for the first time and we should therefore not submit.
return;
}
if (e.target.value !== e.target.dataset.initValue) {
// Update the initValue when the event is triggered.
// This means that if the click handler fires before the focus handler on a subsequent interaction
// with the element, the currently dispalyed value will be the best guess current value.
e.target.dataset.initValue = e.target.value;
triggerEvent(events.accessibleChange, e);
}
};
var nativeElement = element.get()[0];
// The `focus` and `blur` events do not support bubbling. Use Event Capture instead.
nativeElement.addEventListener('focus', function(e) {
setInitialValue(e.target);
}, true);
nativeElement.addEventListener('blur', function(e) {
checkAndTriggerAccessibleChange(e);
}, true);
element.on('keydown', function(e) {
if ((e.which === keyCodes.enter)) {
checkAndTriggerAccessibleChange(e);
} else if (e.which === keyCodes.escape) {
resetToInitialValue(e.target);
e.target.dataset.ignoreChange = true;
} else {
// Firefox triggers a change event when using the keyboard to scroll through the selection.
// Set a data- attribute that the change listener can use to ignore the change event where it was
// generated from a keyboard change such as typing to complete a value, or using arrow keys.
e.target.dataset.ignoreChange = true;
}
});
element.on('change', function(e) {
if (e.target.dataset.ignoreChange) {
// This change event was triggered from a keyboard change which is not yet complete.
// Do not trigger the accessibleChange event until the selection is completed using the [return]
// key.
return;
}
checkAndTriggerAccessibleChange(e);
});
element.on('keyup', function(e) {
// The key has been lifted. Stop ignoring the change event.
delete e.target.dataset.ignoreChange;
});
element.on('click', function(e) {
checkAndTriggerAccessibleChange(e);
});
}
};
/**
* Get the list of events and their handlers.
*
* @method getHandlers
* @private
* @return {object} object key of event names and value of handler functions
*/
var getHandlers = function() {
var handlers = {};
handlers[events.activate] = addActivateListener;
handlers[events.keyboardActivate] = addKeyboardActivateListener;
handlers[events.escape] = addEscapeListener;
handlers[events.down] = addDownListener;
handlers[events.up] = addUpListener;
handlers[events.home] = addHomeListener;
handlers[events.end] = addEndListener;
handlers[events.next] = addNextListener;
handlers[events.previous] = addPreviousListener;
handlers[events.asterix] = addAsterixListener;
handlers[events.scrollLock] = addScrollLockListener;
handlers[events.scrollTop] = addScrollTopListener;
handlers[events.scrollBottom] = addScrollBottomListener;
handlers[events.ctrlPageUp] = addCtrlPageUpListener;
handlers[events.ctrlPageDown] = addCtrlPageDownListener;
handlers[events.enter] = addEnterListener;
handlers[events.accessibleChange] = addAccessibleChangeListener;
return handlers;
};
/**
* Add all of the listeners on the given element for the requested events.
*
* @method define
* @public
* @param {object} element the DOM element to register event listeners on
* @param {array} include the array of events to be triggered
*/
var define = function(element, include) {
element = $(element);
include = include || [];
if (!element.length || !include.length) {
return;
}
$.each(getHandlers(), function(eventType, handler) {
if (shouldAddEvent(eventType, include)) {
handler(element);
}
});
};
return {
define: define,
events: events,
};
});