Give a proper example of originalEvent, discourage use of jQuery.event.props

[dmethvin]

Docs at http://api.jquery.com/category/events/event-object/ say to use originalEvent and then show the unadvisable practice of pushing additional properties on jQuery.event.props to be copied to the event object. Copying lots of properties slows down each delivered event.

[JonathanThiyagarajan]

Are you telling jQuery isn't passing the touches property on in its custom event object. As described in the event object's documentation, you can use event.originalEvent in your first example to access the "special properties" it has while still getting the benefits of the jQuery normalized event object, e.g.

$('.image').bind('touchstart', function(event) {
  alert(event.originalEvent.touches.length);
}); 

Or you can use the following jquery code jQuery.event.props.push("touches");

[DavidAustin]

originalEvent needs to be properly documented. The line "Certain events may have properties specific to them" is weak and doesn't lead the reader to conclude that originalEvent is useful.

Certainly examples should be given.

[dmethvin]

Since this is tagged as help wanted, we'd be glad to consider a pull request. Everyone here is a volunteer.

[mgol]

See jquery/jquery#3112. As @silverwind pointed out, we've now removed jQuery.event.props completely in jquery/jquery@e61fccb so this snippet is now not only not advised but will break in jQuery 3.0.0. We need to remove it ASAP and certainly before jQuery 3.0.0 comes out.

[mgol]

I've added the 3.0.0 milestone.

[silverwind]

Might be good to make a changelog entry too for the removal of jQuery.event.props.

[mgol]

@silverwind What changelog do you have in mind?

[mgol]

Ah, you probably mean the Version subsection. We have an in-progress branch at https://github.com/jquery/api.jquery.com/tree/v3.0.0-docs that will land when jQuery 3.0.0 comes but I see it's quite out of date (and doesn't even compile on my machine anymore). @AurelioDeRosa do you know what's the state of that?

[silverwind]

I see you're not keeping a formal changelog. I meant the blog posts, like this one.

[mgol]

@silverwind OK. :) We've already added the description to the upgrade guide; there are no links to this page yet, we'll include one in the blog post summarizing the 3.0.0 release.