From e6d83226dfbb32f5d5db8c644948b583f30d61d7 Mon Sep 17 00:00:00 2001 From: Justin Meyer Date: Sun, 11 Mar 2018 21:04:05 -0500 Subject: [PATCH] improved docs #46 --- .npmrc | 1 + can-dom-events.js | 127 +++++++++++++++------------------ doc/can-dom-events.md | 84 ++++++++++++++++++++++ doc/dom-event-target.md | 11 +++ doc/event-definition.md | 18 +++++ doc/event-registry.md | 4 ++ helpers/make-event-registry.js | 11 +-- 7 files changed, 183 insertions(+), 73 deletions(-) create mode 100644 .npmrc create mode 100644 doc/can-dom-events.md create mode 100644 doc/dom-event-target.md create mode 100644 doc/event-definition.md create mode 100644 doc/event-registry.md diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..43c97e7 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +package-lock=false diff --git a/can-dom-events.js b/can-dom-events.js index e706edc..383c4ce 100644 --- a/can-dom-events.js +++ b/can-dom-events.js @@ -5,45 +5,23 @@ var util = require('./helpers/util'); var makeEventRegistry = require('./helpers/make-event-registry'); var makeDelegateEventTree = require('./helpers/-make-delegate-event-tree'); -/** - * @module {{}} can-dom-events - * @parent can-dom-utilities - * @collection can-infrastructure - * @package ./package.json - * @description Dispatch and listen to DOM Events. - * @group can-dom-events.static 0 static - * @group can-dom-events.helpers 1 helpers - * @group can-dom-events.types 2 types - * @signature `domEvents` - * - * @body - * - * ```js - * var domEvents = require("can-dom-events"); - * var input = document.createElement('input'); - * - * function onChange(event) { - * console.log('Input value changed to:', event.target.value); - * } - * - * domEvents.addEventListener(input, 'change', onChange); - * - * domEvents.dispatch(input, 'change'); // calls onChange - * - * domEvents.removeEventListener(input, 'change', onChange); - * ``` - */ + var domEvents = { _eventRegistry: makeEventRegistry(), /** * @function can-dom-events.addEvent addEvent + * @parent can-dom-events.static * * Add a custom event to the global event registry. * * @signature `addEvent( event [, eventType ] )` - * @parent can-dom-events.static - * @param {EventDefinition} event The custom event definition. + * + * ```js + * var removeReturnEvent = domEvents.addEvent(enterEvent, "return"); + * ``` + * + * @param {can-dom-events/EventDefinition} event The custom event definition. * @param {String} eventType The event type to associated with the custom event. * @return {function} The callback to remove the custom event from the registry. */ @@ -60,7 +38,8 @@ var domEvents = { * @parent can-dom-events.static * @param {DomEventTarget} target The object to which to add the listener. * @param {String} eventType The event type with which to register. - * @param {*} eventArgs The arguments which configure the associated event's behavior. + * @param {*} eventArgs The arguments which configure the associated event's behavior. This is usually a + * function event handler. */ addEventListener: function(target, eventType) { var hasCustomEvent = domEvents._eventRegistry.has(eventType); @@ -82,7 +61,8 @@ var domEvents = { * @parent can-dom-events.static * @param {DomEventTarget} target The object to which to add the listener. * @param {String} eventType The event type with which to unregister. - * @param {*} eventArgs The arguments which configure the associated event's behavior. + * @param {*} eventArgs The arguments which configure the associated event's behavior. This is usually a + * function event handler. */ removeEventListener: function(target, eventType) { var hasCustomEvent = domEvents._eventRegistry.has(eventType); @@ -95,11 +75,51 @@ var domEvents = { return target.removeEventListener.apply(target, eventArgs); }, - - addDelegateListener: function(target, eventType, selector, handler) { - domEvents._eventTree.add([target, eventType, selector, handler]); + /** + * @function can-dom-events.addDelegateListener addDelegateListener + * + * Attach a handler for an event for all elements that match the selector, + * now or in the future, based on a root element. + * + * @signature `addDelegateListener( target, eventType, selector, handler )` + * + * ```js + * // Prevents all anchor elements from changing the page + * domEvents.addDelegateListener(document.body,"click", "a", function(event){ + * event.preventDefault(); + * }) + * ``` + * @parent can-dom-events.static + * @param {DomEventTarget} root The html element to listen to events that match selector within. + * @param {String} eventType The event name to listen to. + * @param {String} selector A selector to filter the elements that trigger the event. + * @param {function} handler A function to execute at the time the event is triggered. + */ + addDelegateListener: function(root, eventType, selector, handler) { + domEvents._eventTree.add([root, eventType, selector, handler]); }, - + /** + * @function can-dom-events.removeDelegateListener removeDelegateListener + * + * Remove a handler for an event for all elements that match the selector. + * + * @signature `removeDelegateListener( target, eventType, selector, handler )` + * + * ```js + * // Prevents all anchor elements from changing the page + * function handler(event) { + * event.preventDefault(); + * } + * domEvents.addDelegateListener(document.body,"click", "a", handler); + * + * domEvents.removeDelegateListener(document.body,"click", "a", handler); + * ``` + * @parent can-dom-events.static + * @param {DomEventTarget} root The html element to listen to events that match selector within. + * @param {String} eventType The event name to listen to. + * @param {String} selector A selector to filter the elements that trigger the event. + * @param {function} handler A function that was previously passed to `addDelegateListener`. + */ removeDelegateListener: function(target, eventType, selector, handler) { domEvents._eventTree.delete([target, eventType, selector, handler]); }, @@ -135,37 +155,8 @@ var domEvents = { domEvents._eventTree = makeDelegateEventTree(domEvents); -/** - * @typedef {Object} can-dom-events.EventDefinition EventDefinition - * @description Definition of a custom event that may be added to an event registry. - * @parent can-dom-events.types - * @type {Object} - * @option {String} [defaultEventType] - * The default event type of the event. - * - * @option {function} [addEventListener] - * The function to add the listener to the target. - * @param {DomEventTarget} target The target to which to add the listener. - * @param {String} eventType The event type which should be used to register the listener. - * @param {*} eventArgs The arguments should to configure the listener behavior. - * - * @option {function} [removeEventListener] - * The function to remove the listener from the target. - * @param {DomEventTarget} target The target to which to add the listener. - * @param {String} eventType The event type which should be used to register the listener. - * @param {*} eventArgs The arguments should to configure the listener behavior. - */ - - /** - * @typedef {Object} can-dom-events.DomEventTarget DomEventTarget - * @description - * An object which can have DOM Events registered on it. - * This is a Window, Document, or HTMLElement. - * @parent can-dom-events.types - * @signature `Window|Document|HTMLElement` - * @type {Window} - * @type {Document} - * @type {HTMLElement} - */ + + + module.exports = namespace.domEvents = domEvents; diff --git a/doc/can-dom-events.md b/doc/can-dom-events.md new file mode 100644 index 0000000..fcc6a46 --- /dev/null +++ b/doc/can-dom-events.md @@ -0,0 +1,84 @@ +@module {can-dom-events/EventRegistry} can-dom-events +@parent can-dom-utilities +@collection can-infrastructure +@package ../package.json +@group can-dom-events.static 0 static +@group can-dom-events.types 1 types + +@description Listen to DOM events and special events, and register +special events. + +@type {can-dom-events/EventRegistry} + The `can-dom-events` module exports the _global_ event registry. Use + it to listen to DOM events on HTML elements. Any custom event + types added to this registry are available to every other part of CanJS. + + +@body + +## Use + +The following listens to a 'change' event on an element: + +```js +var domEvents = require("can-dom-events"); +var input = document.createElement('input'); + +function onChange(event) { + console.log('Input value changed to:', event.target.value); +} + +domEvents.addEventListener(input, 'change', onChange); +``` + +Use [can-dom-events.dispatch] to fire custom events: +```js +domEvents.dispatch(input, 'change'); +``` + +Use [can-dom-events.addDelegateListener] to listen to an event for all elements that +match a selector within a root element: + +```js +domEvents.addDelegateListener(document.body,"click", "a", function(event){ + event.preventDefault(); +}); +``` + +Finally, you can create your own custom events and add them to +the global event registry. First, create an [can-dom-events/EventDefinition] +object. For example, the following might implement +an "escape" event that listens to when a user presses the `Escape` key: + + +```js +var handlerMap = new WeakMap(); +var escapeEventDefinition = { + defaultEventType: 'escape', + addEventListener: function (target, eventType, handler) { + var keyHandler = function (event) { + if (event.keyCode === 27 || event.key === 'Escape') { + return handler.apply(this, arguments); + } + }; + handlerMap.set(handler, keyHandler) + this.addEventListener(target, baseEventType, keyHandler); + }, + removeEventListener: function (target, eventType, handler) { + this.removeEventListener(target, baseEventType, handlerMap.get(handler)); + } +} +``` + +Then you can add this custom event to the registry and listen to that event: + +```js +import domEvents from "can-dom-events"; + +domEvents.addEvent(escapeEventDefinition); + +var input = document.querySelector("[name=search]"); +domEvents.addEventListener(input, "escape", function(){ + +}); +``` diff --git a/doc/dom-event-target.md b/doc/dom-event-target.md new file mode 100644 index 0000000..74fa33b --- /dev/null +++ b/doc/dom-event-target.md @@ -0,0 +1,11 @@ +@typedef {Object} can-dom-events.DomEventTarget DomEventTarget +@parent can-dom-events.types + +@description An object which can have DOM Events registered on it. +This is a Window, Document, or HTMLElement. + +@signature `Window|Document|HTMLElement` + +@type {Window} +@type {Document} +@type {HTMLElement} diff --git a/doc/event-definition.md b/doc/event-definition.md new file mode 100644 index 0000000..164301d --- /dev/null +++ b/doc/event-definition.md @@ -0,0 +1,18 @@ +@typedef {Object} can-dom-events/EventDefinition EventDefinition +@description Definition of a custom event that may be added to an event registry. +@parent can-dom-events.types +@type {Object} + @option {String} [defaultEventType] + The default event type of the event. + + @option {function} [addEventListener] + The function to add the listener to the target. + @param {DomEventTarget} target The target to which to add the listener. + @param {String} eventType The event type which should be used to register the listener. + @param {*} eventArgs The arguments should to configure the listener behavior. + + @option {function} [removeEventListener] + The function to remove the listener from the target. + @param {DomEventTarget} target The target to which to add the listener. + @param {String} eventType The event type which should be used to register the listener. + @param {*} eventArgs The arguments should to configure the listener behavior. diff --git a/doc/event-registry.md b/doc/event-registry.md new file mode 100644 index 0000000..e938eb2 --- /dev/null +++ b/doc/event-registry.md @@ -0,0 +1,4 @@ +@typedef {Object} can-dom-events/EventRegistry EventRegistry +@parent can-dom-events.types +@hide +@description Blah diff --git a/helpers/make-event-registry.js b/helpers/make-event-registry.js index c1b7b5b..55e7986 100644 --- a/helpers/make-event-registry.js +++ b/helpers/make-event-registry.js @@ -8,9 +8,10 @@ function EventRegistry () { * @module can-dom-events/helpers/make-event-registry * @parent can-dom-events.helpers * @description Create an event registry. - * @group make-event-registry.registry 0 EventRegistry * @signature `makeEventRegistry()` - * + * @return {can-dom-events/EventRegistry} + * @hide + * * @body * * ```js @@ -36,7 +37,7 @@ module.exports = function makeEventRegistry () { * Check whether an event type has already been registered. * * @signature `eventRegistry.has( eventType )` - * @parent make-event-registry.registry + * @parent can-dom-events/EventRegistry * @param {String} eventType The event type for which to check. * @return {Boolean} Whether the event type is registered. */ @@ -50,7 +51,7 @@ EventRegistry.prototype.has = function (eventType) { * Retrieve an event type which has already been registered. * * @signature `eventRegistry.get( eventType )` - * @parent make-event-registry.registry + * @parent can-dom-events/EventRegistry * @param {String} eventType The event type for which to retrieve. * @return {EventDefinition} The registered event definition, or undefined if unregistered. */ @@ -64,7 +65,7 @@ EventRegistry.prototype.get = function (eventType) { * Add an event to the registry. * * @signature `eventRegistry.add( event [, eventType ] )` - * @parent make-event-registry.registry + * @parent can-dom-events/EventRegistry * @param {EventDefinition} event The event definition to register. * @param {String} eventType The event type with which to register the event. * @return {function} The callback to remove the event from the registry.