Fixes #2146 - document Element.NativeEvents #2165

Merged
merged 1 commit into from Dec 19, 2011

2 participants

@arian
MooTools member

because it is useful for users when new (html5) event types appear

@ibolmo ibolmo commented on the diff Dec 10, 2011
Docs/Element/Element.Event.md
+Each event type has a value, possible values are `0` (`undefined`, `null`), `1`, and `2`.
+
+### Type 0 Events
+
+By default it is undefined. In this case you can add events, but you should manually fire them.
+
+#### Example:
+
+ element.addEvent('pizza', fn);
+ element.fireEvent('pizza', 'yum!');
+
+The event is not actually added to the DOM, but is only registered in a JS object.
+
+### Type 1 Events
+
+The second case is if the value is 1. This time the object is attached to the DOM. Usually by element.addEventListener, or element.attacheEvent in older versions of IE. You can still use `element.fireEvent('load')` to manually fire events.
@ibolmo
MooTools member
ibolmo added a line comment Dec 10, 2011

attacheEvent

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ibolmo ibolmo commented on the diff Dec 10, 2011
Docs/Element/Element.Event.md
+#### Example:
+
+ element.addEvent('pizza', fn);
+ element.fireEvent('pizza', 'yum!');
+
+The event is not actually added to the DOM, but is only registered in a JS object.
+
+### Type 1 Events
+
+The second case is if the value is 1. This time the object is attached to the DOM. Usually by element.addEventListener, or element.attacheEvent in older versions of IE. You can still use `element.fireEvent('load')` to manually fire events.
+
+### Type 2 Events
+
+The final case is if the value is 2. This is the same as case 1. The only difference is that the event object, containing interesting data, is wrapped and normalized by event wrapper ([DOMEvent][]). This is the most used variant, for mouse events (like *click*) and keyboard events.
+
+The reason to differentiate between 1 and 2 is that 1 is usually used for events that don't have interesting data, like onload, onscroll, onresize. Those last two fire an awful lot as well.
@ibolmo
MooTools member
ibolmo added a line comment Dec 10, 2011

don't have interesting data like: onload, onscroll, and onresize, or it's more performant. The latter two, for example, are fired frequently.

@ibolmo
MooTools member
ibolmo added a line comment Dec 10, 2011

Also, not sure if you'd like to onresize keywords.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ibolmo ibolmo commented on the diff Dec 10, 2011
Docs/Element/Element.Event.md
+
+The event is not actually added to the DOM, but is only registered in a JS object.
+
+### Type 1 Events
+
+The second case is if the value is 1. This time the object is attached to the DOM. Usually by element.addEventListener, or element.attacheEvent in older versions of IE. You can still use `element.fireEvent('load')` to manually fire events.
+
+### Type 2 Events
+
+The final case is if the value is 2. This is the same as case 1. The only difference is that the event object, containing interesting data, is wrapped and normalized by event wrapper ([DOMEvent][]). This is the most used variant, for mouse events (like *click*) and keyboard events.
+
+The reason to differentiate between 1 and 2 is that 1 is usually used for events that don't have interesting data, like onload, onscroll, onresize. Those last two fire an awful lot as well.
+
+### Adding unsupported events
+
+As browsers evolve, new event types appear that you want to use, or browser specific events that are not supported by MooTools because they are only useful in specific cases. If you want to use those through the MooTools API there is a problem. The problem is that the event type has to be registered in the object, otherwise it will handle the event as case 0. This can be done with, for example:
@ibolmo
MooTools member
ibolmo added a line comment Dec 10, 2011

Not all events are supported by MooTools' Element Events API because of edge use cases or new events supported by the browser. To add support for a native event, just augment the Element.NativeEvents object with the key and appropriate key value (use the above). For example to add popstate support in your application:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ibolmo ibolmo merged commit ba51b8a into mootools:master Dec 19, 2011
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment