@@ -39,7 +39,7 @@ on, and it's controlled by two three-way switches and a clapper: ``` Triggering the clapper or either of the switches will change the state of the -lightbulb. The switches and the clapper don't care what state the lightbulb is +lightbulb. The switches and the clapper don’t care what state the lightbulb is in; they just want to change the state. Without custom events, you might write some code like this: @@ -72,9 +72,9 @@ $( ".switch, .clapper" ).click(function() { }); ``` -This last bit of code is not that exciting, but something important has happened: we've moved the behavior of the lightbulb to the lightbulb, and away from the switches and the clapper. +This last bit of code is not that exciting, but something important has happened: we’ve moved the behavior of the lightbulb to the lightbulb, and away from the switches and the clapper. -Let's make our example a little more interesting. We'll add another room to our house, along with a master switch, as shown here: +Let’s make our example a little more interesting. We’ll add another room to our house, along with a master switch, as shown here: ``` ``` -This gives us a container (#twitter) for our widget, a template for our results +This gives us a container (`#twitter`) for our widget, a template for our results containers (hidden via CSS), and a simple form where users can input a search -term. (For the sake of simplicity, we're going to assume that our application +term. (For the sake of simplicity, we’re going to assume that our application is JavaScript-only and that our users will always have CSS.) -There are two types of objects we'll want to act on: the results containers, +There are two types of objects we’ll want to act on: the results containers, and the Twitter container. -The results containers are the heart of the application. We'll create a plugin -that will prepare each results container once it's added to the Twitter +The results containers are the heart of the application. We’ll create a plugin +that will prepare each results container once it’s added to the Twitter container. Among other things, it will bind the custom events for each container and add the action buttons at the top right of each container. Each results container will have the following custom events: -- `refresh` - Mark the container as being in the "refreshing" state, and fire +- `refresh` — Mark the container as being in the “refreshing” state, and fire the request to fetch the data for the search term. -- `populate` - Receive the returned JSON data and use it to populate the container. +- `populate` — Receive the returned JSON data and use it to populate the container. -- `remove` - Remove the container from the page after the user verifies the - request to do so. Verification can be bypassed by passing true as the second - argument to the event handler. The remove event also removes the term +- `remove` — Remove the container from the page after the user verifies the + request to do so. Verification can be bypassed by passing `true` as the second + argument to the event handler. The `remove` event also removes the term associated with the results container from the global object containing the search terms. -- `collapse` - Add a class of collapsed to the container, which will hide the - results via CSS. It will also turn the container's "Collapse" button into an - "Expand" button. +- `collapse` — Add a class of collapsed to the container, which will hide the + results via CSS. It will also turn the container’s “Collapse” button into an + “Expand” button. -- `expand` - Remove the collapsed class from the container. It will also turn - the container's "Expand" button into a "Collapse" button. +- `expand` — Remove the collapsed class from the container. It will also turn + the container’s “Expand” button into a “Collapse” button. The plugin is also responsible for adding the action buttons to the container. -It binds a click event to each action's list item, and uses the list item's +It binds a click event to each action’s list item, and uses the list item’s class to determine which custom event will be triggered on the corresponding results container. @@ -344,7 +344,7 @@ $.fn.twitterResult.events = { The Twitter container itself will have just two custom events: -- `getResults` - Receives a search term and checks to determine whether there's +- `getResults` — Receives a search term and checks to determine whether there’s already a results container for the term; if not, adds a results container using the results template, set up the results container using the `$.fn.twitterResult` plugin discussed above, and then triggers the `refresh` @@ -352,11 +352,11 @@ The Twitter container itself will have just two custom events: Finally, it will store the search term so the application knows not to re-fetch the term. -- `getTrends` - Queries Twitter for the top 10 trending terms, then iterates +- `getTrends` — Queries Twitter for the top 10 trending terms, then iterates over them and triggers the `getResults` event for each of them, thereby adding a results container for each term. -Here's how the Twitter container bindings look: +Here’s how the Twitter container bindings look: ``` $( "#twitter" ).on( "getResults", function( e, term ) { @@ -392,14 +392,14 @@ $( "#twitter" ).on( "getResults", function( e, term ) { }); ``` -So far, we've written a lot of code that does approximately nothing, but that's +So far, we’ve written a lot of code that does approximately nothing, but that’s OK. By specifying all the behaviors that we want our core objects to have, -we've created a solid framework for rapidly building out the interface. +we’ve created a solid framework for rapidly building out the interface. -Let's start by hooking up our text input and the "Load Trending Terms" button. -For the text input, we'll capture the term that was entered in the input and -pass it as we trigger the Twitter container's `getResults` event. Clicking the -"Load Trending Terms" will trigger the Twitter container's `getTrends` event: +Let’s start by hooking up our text input and the “Load Trending Terms” button. +For the text input, we’ll capture the term that was entered in the input and +pass it as we trigger the Twitter container’s `getResults` event. Clicking the +“Load Trending Terms” will trigger the Twitter container’s `getTrends` event: ``` $( "form" ).submit(function( event ) { @@ -413,10 +413,10 @@ $( "#get_trends" ).click(function() { }); ``` -By adding a few buttons with the appropriate IDs, we can make it possible to +By adding a few buttons with the appropriate ID’s, we can make it possible to remove, collapse, expand, and refresh all results containers at once, as shown -below. For the remove button, note how we're passing a value of true to the -event handler as its second argument, telling the event handler that we don't +below. For the remove button, note how we’re passing a value of `true` to the +event handler as its second argument, telling the event handler that we don’t want to verify the removal of individual containers. ``` @@ -439,7 +439,7 @@ Custom events offer a new way of thinking about your code: they put the emphasis on the target of a behavior, not on the element that triggers it. If you take the time at the outset to spell out the pieces of your application, as well as the behaviors those pieces need to exhibit, custom events can provide a -powerful way for you to "talk" to those pieces, either one at a time or en +powerful way for you to “talk” to those pieces, either one at a time or en masse. Once the behaviors of a piece have been described, it becomes trivial to trigger those behaviors from anywhere, allowing for rapid creation of and experimentation with interface options. Finally, custom events can enhance code diff --git a/page/events/introduction-to-events.md b/page/events/introduction-to-events.md index 089e52ab..b540abe9 100644 --- a/page/events/introduction-to-events.md +++ b/page/events/introduction-to-events.md @@ -2,23 +2,23 @@ title: Introducing Events level: beginner source: http://jqfundamentals.com/legacy -attribution: +attribution: - jQuery Fundamentals --- ## Introduction -Web pages are all about interaction. Users perform a countless number of actions such as moving their mice over the page, clicking on elements, and typing in textboxes—all of these are examples of events. In addition to these user events, there are a slew of others that occur, like when the page is loaded, when video begins playing or is paused, etc. Whenever something interesting occurs on the page, an event is fired, meaning that the browser basically announces that something has happened. It's this announcement that allows developers to "listen" for events and react to them appropriately. +Web pages are all about interaction. Users perform a countless number of actions such as moving their mice over the page, clicking on elements, and typing in textboxes — all of these are examples of events. In addition to these user events, there are a slew of others that occur, like when the page is loaded, when video begins playing or is paused, etc. Whenever something interesting occurs on the page, an event is fired, meaning that the browser basically announces that something has happened. It’s this announcement that allows developers to “listen” for events and react to them appropriately. -## What's a DOM event? +## What’s a DOM event? -As mentioned, there are a myriad of event types, but perhaps the ones that are easiest to understand are user events, like when someone clicks on an element or types into a form. These types of events occur on an element, meaning that when a user clicks on a button for example, the button has had an event occur on it. While user interactions aren't the only types of DOM events, they're certainly the easiest to understand when starting out. MDN has a good reference of [available DOM events](https://developer.mozilla.org/en/DOM/DOM_event_reference). +As mentioned, there are a myriad of event types, but perhaps the ones that are easiest to understand are user events, like when someone clicks on an element or types into a form. These types of events occur on an element, meaning that when a user clicks on a button for example, the button has had an event occur on it. While user interactions aren’t the only types of DOM events, they’re certainly the easiest to understand when starting out. MDN has a good reference of [available DOM events](https://developer.mozilla.org/en/DOM/DOM_event_reference). ## Ways to listen for events -There are many ways to listen for events. Actions are constantly occurring on a webpage, but the developer is only notified about them if they're *listening* for them. Listening for an event basically means you're waiting for the browser to tell you that a specific event has occurred and then you'll specify how the page should react. +There are many ways to listen for events. Actions are constantly occurring on a webpage, but the developer is only notified about them if they’re *listening* for them. Listening for an event basically means you’re waiting for the browser to tell you that a specific event has occurred and then you’ll specify how the page should react. To specify to the browser what to do when an event occurs, you provide a function, also known as an *event handler*. This function is executed whenever the event occurs (or until the event is unbound). @@ -28,14 +28,14 @@ For instance, to alert a message whenever a user clicks on a button, you might w Say hello ``` -The event we want to listen to is specified by the button's `onclick` attribute, and the event handler is the `alert` function which alerts "Hello" to the user. While this works, it's an abysmal way to achieve this functionality for a couple of reasons: +The event we want to listen to is specified by the button’s `onclick` attribute, and the event handler is the `alert` function which alerts “Hello” to the user. While this works, it’s an abysmal way to achieve this functionality for a couple of reasons: -1. First, we're coupling our view code (HTML) with our interaction code (JS). That means that whenever we need to update functionality, we'd have to edit our HTML which is just a bad practice and a maintenance nightmare. -2. Second, it's not scalable. If you had to attach this functionality onto numerous buttons, you'd not only bloat the page with a bunch of repetitious code, but you would again destroy maintainability. +1. First, we’re coupling our view code (HTML) with our interaction code (JS). That means that whenever we need to update functionality, we’d have to edit our HTML which is just a bad practice and a maintenance nightmare. +2. Second, it’s not scalable. If you had to attach this functionality onto numerous buttons, you’d not only bloat the page with a bunch of repetitious code, but you would again destroy maintainability. -Utilizing inline event handlers like this can be considered *obtrusive JavaScript,* but its opposite, *unobtrusive JavaScript* is a much more common way of discussing the topic. The notion of *unobtrusive JavaScript* is that your HTML and JS are kept separate and are therefore more maintainable. Separation of concerns is important because it keeps like pieces of code together (i.e. HTML, JS, CSS) and unlike pieces of code apart, facilitating changes, enhancements, etc. Furthermore, unobtrusive JavaScript stresses the importance of adding the least amount of cruft to a page as possible. If a user's browser doesn't support JavaScript, then it shouldn't be intertwined into the markup of the page. Also, to prevent naming collisions, JS code should utilize a single namespace for different pieces of functionality or libraries. jQuery is a good example of this, in that the `jQuery` object/constructor (and also the `$` alias to `jQuery`) only utilizes a single global variable, and all of jQuery's functionality is packaged into that one object. +Utilizing inline event handlers like this can be considered *obtrusive JavaScript,* but its opposite, *unobtrusive JavaScript* is a much more common way of discussing the topic. The notion of *unobtrusive JavaScript* is that your HTML and JS are kept separate and are therefore more maintainable. Separation of concerns is important because it keeps like pieces of code together (i.e. HTML, JS, CSS) and unlike pieces of code apart, facilitating changes, enhancements, etc. Furthermore, unobtrusive JavaScript stresses the importance of adding the least amount of cruft to a page as possible. If a user’s browser doesn’t support JavaScript, then it shouldn’t be intertwined into the markup of the page. Also, to prevent naming collisions, JS code should utilize a single namespace for different pieces of functionality or libraries. jQuery is a good example of this, in that the `jQuery` object/constructor (and also the `$` alias to `jQuery`) only utilizes a single global variable, and all of jQuery’s functionality is packaged into that one object. -To accomplish the desired task unobtrusively, let's change our HTML a little bit by removing the `onclick` attribute and replacing it with an `id`, which we'll utilize to "hook onto" the button from within a script file. +To accomplish the desired task unobtrusively, let’s change our HTML a little bit by removing the `onclick` attribute and replacing it with an `id`, which we’ll utilize to “hook onto” the button from within a script file. ``` Say hello @@ -52,7 +52,7 @@ helloBtn.addEventListener( "click", function( event ) { }, false ); ``` -Here we're saving a reference to the button element by calling `getElementById` and assigning its return value to a variable. We then call `addEventListener` and provide an event handler function that will be called whenever that event occurs. While there's nothing wrong with this code as it will work fine in modern browsers, it won't fare well in versions of IE prior to IE9. This is because Microsoft chose to implement a different method, `attachEvent`, as opposed to the W3C standard `addEventListener`, and didn't get around to changing it until IE9 was released. For this reason, it's beneficial to utilize jQuery because it abstracts away browser inconsistencies, allowing developers to use a single API for these types of tasks, as seen below. +Here we’re saving a reference to the button element by calling `getElementById` and assigning its return value to a variable. We then call `addEventListener` and provide an event handler function that will be called whenever that event occurs. While there’s nothing wrong with this code as it will work fine in modern browsers, it won’t fare well in versions of IE prior to IE9. This is because Microsoft chose to implement a different method, `attachEvent`, as opposed to the W3C standard `addEventListener`, and didn’t get around to changing it until IE9 was released. For this reason, it’s beneficial to utilize jQuery because it abstracts away browser inconsistencies, allowing developers to use a single API for these types of tasks, as seen below. ``` // Event binding using a convenience method @@ -61,7 +61,7 @@ $( "#helloBtn" ).click(function( event ) { }); ``` -The `$("#helloBtn")` code selects the button element using the `$` (aka `jQuery`) function and returns a jQuery object. The jQuery object has a bunch of methods (functions) available to it, one of them named `click`, which resides in the jQuery object's prototype. We call the `click` method on the jQuery object and pass along an anonymous function event handler that's going to be executed when a user clicks the button, alerting "Hello." to the user. +The `$( "#helloBtn" )` code selects the button element using the `$` (a.k.a. `jQuery`) function and returns a jQuery object. The jQuery object has a bunch of methods (functions) available to it, one of them named `click`, which resides in the jQuery object’s prototype. We call the `click` method on the jQuery object and pass along an anonymous function event handler that’s going to be executed when a user clicks the button, alerting “Hello.” to the user. There are a number of ways that events can be listened for using jQuery: @@ -100,22 +100,22 @@ $( "body" ).on( "click", "button", function( event ) { }); ``` -As of jQuery 1.7, all events are bound via the `on` method, whether you call it directly or whether you use an alias/shortcut method such as `bind` or `click`, which are mapped to the `on` method internally. With this in mind, it's beneficial to use the `on` method because the others are all just syntactic sugar, and utilizing the `on` method is going to result in faster and more consistent code. +As of jQuery 1.7, all events are bound via the `on` method, whether you call it directly or whether you use an alias/shortcut method such as `bind` or `click`, which are mapped to the `on` method internally. With this in mind, it’s beneficial to use the `on` method because the others are all just syntactic sugar, and utilizing the `on` method is going to result in faster and more consistent code. -Let's look at the `on` examples from above and discuss their differences. In the first example, a string of `click` is passed as the first argument to the `on` method, and an anonymous function is passed as the second. This looks a lot like the `bind` method before it. Here, we're attaching an event handler directly to `#helloBtn`. If there were any other buttons on the page, they wouldn't alert "Hello" when clicked because the event is only attached to `#helloBtn`. +Let’s look at the `on` examples from above and discuss their differences. In the first example, a string of `click` is passed as the first argument to the `on` method, and an anonymous function is passed as the second. This looks a lot like the `bind` method before it. Here, we’re attaching an event handler directly to `#helloBtn`. If there were any other buttons on the page, they wouldn’t alert “Hello” when clicked because the event is only attached to `#helloBtn`. -In the second `on` example, we're passing an object (denoted by the curly braces `{}`), which has a property of `click` whose value is an anonymous function. The second argument to the `on` method is a jQuery selector string of `button`. While examples 1–3 are functionally equivalent, example 4 is different in that the `body` element is listening for click events that occur on *any* button element, not just `#helloBtn`. The final example above is exactly the same as the one preceding it, but instead of passing an object, we pass an event string, a selector string, and the callback. Both of these are examples of event delegation, a process by which an element higher in the DOM tree listens for events occurring on its children. +In the second `on` example, we’re passing an object (denoted by the curly braces `{}`), which has a property of `click` whose value is an anonymous function. The second argument to the `on` method is a jQuery selector string of `button`. While examples 1–3 are functionally equivalent, example 4 is different in that the `body` element is listening for click events that occur on *any* button element, not just `#helloBtn`. The final example above is exactly the same as the one preceding it, but instead of passing an object, we pass an event string, a selector string, and the callback. Both of these are examples of event delegation, a process by which an element higher in the DOM tree listens for events occurring on its children. -Event delegation works because of the notion of *event bubbling*. For most events, whenever something occurs on a page (like an element is clicked), the event travels from the element it occurred on, up to its parent, then up to the parent's parent, and so on, until it reaches the root element, aka the `window`. So in our table example, whenever a `td` is clicked, its parent `tr` would also be notified of the click, the parent `table` would be notified, the `body` would be notified, and ultimately the `window` would be notified as well. While event bubbling and delegation work well, the delegating element (in our example, the `table`) should always be as close to the delegatees as possible so the event doesn't have to travel way up the DOM tree before its handler function is called. +Event delegation works because of the notion of *event bubbling*. For most events, whenever something occurs on a page (like an element is clicked), the event travels from the element it occurred on, up to its parent, then up to the parent’s parent, and so on, until it reaches the root element, a.k.a. the `window`. So in our table example, whenever a `td` is clicked, its parent `tr` would also be notified of the click, the parent `table` would be notified, the `body` would be notified, and ultimately the `window` would be notified as well. While event bubbling and delegation work well, the delegating element (in our example, the `table`) should always be as close to the delegatees as possible so the event doesn’t have to travel way up the DOM tree before its handler function is called. -The two main pros of event delegation over binding directly to an element (or set of elements) are performance and the aforementioned event bubbling. Imagine having a large table of 1000 cells and binding to an event for each cell. That's 1000 separate event handlers that the browser has to attach, even if they're all mapped to the same function. Instead of binding to each individual cell though, we could instead use delegation to listen for events that occur on the parent table and react accordingly. One event would be bound instead of 1000, resulting in way better performance and memory management. +The two main pros of event delegation over binding directly to an element (or set of elements) are performance and the aforementioned event bubbling. Imagine having a large table of 1,000 cells and binding to an event for each cell. That’s 1,000 separate event handlers that the browser has to attach, even if they’re all mapped to the same function. Instead of binding to each individual cell though, we could instead use delegation to listen for events that occur on the parent table and react accordingly. One event would be bound instead of 1,000, resulting in way better performance and memory management. -The event bubbling that occurs affords us the ability to add cells via AJAX for example, without having to bind events directly to those cells since the parent table is listening for clicks and is therefore notified of clicks on its children. If we weren't using delegation, we'd have to constantly bind events for every cell that's added which is not only a performance issue, but could also become a maintenance nightmare. +The event bubbling that occurs affords us the ability to add cells via AJAX for example, without having to bind events directly to those cells since the parent table is listening for clicks and is therefore notified of clicks on its children. If we weren’t using delegation, we’d have to constantly bind events for every cell that’s added which is not only a performance issue, but could also become a maintenance nightmare. ## The event object -In all of the previous examples, we've been using anonymous functions and specifying an `event` argument within that function. Let's change it up a little bit. +In all of the previous examples, we’ve been using anonymous functions and specifying an `event` argument within that function. Let’s change it up a little bit. ``` // Binding a named function @@ -126,11 +126,11 @@ function sayHello( event ) { $( "#helloBtn" ).on( "click", sayHello ); ``` -In this slightly different example, we're defining a function called `sayHello` and then passing that function into the `on` method instead of an anonymous function. So many online examples show anonymous functions used as event handlers, but it's important to realize that you can also pass defined functions as event handlers as well. This is important if different elements or different events should perform the same functionality. This helps to keep your code DRY. +In this slightly different example, we’re defining a function called `sayHello` and then passing that function into the `on` method instead of an anonymous function. So many online examples show anonymous functions used as event handlers, but it’s important to realize that you can also pass defined functions as event handlers as well. This is important if different elements or different events should perform the same functionality. This helps to keep your code DRY. -But what about that `event` argument in the `sayHello` function—what is it and why does it matter? In all DOM event callbacks, jQuery passes an *event object* argument which contains information about the event, such as precisely when and where it occurred, what type of event it was, which element the event occurred on, and a plethora of other information. Of course you don't have to call it `event`; you could call it `e` or whatever you want to, but `event` is a pretty common convention. +But what about that `event` argument in the `sayHello` function — what is it and why does it matter? In all DOM event callbacks, jQuery passes an *event object* argument which contains information about the event, such as precisely when and where it occurred, what type of event it was, which element the event occurred on, and a plethora of other information. Of course you don’t have to call it `event`; you could call it `e` or whatever you want to, but `event` is a pretty common convention. -If the element has default functionality for a specific event (like a link opens a new page, a button in a form submits the form, etc), that default functionality can be cancelled. This is often useful for AJAX requests. When a user clicks on a button to submit a form via AJAX, we'd want to cancel the button/form's default action (to submit it to the form's `action` attribute), and we would instead do an AJAX request to accomplish the same task for a more seamless experience. To do this, we would utilize the event object and call its `preventDefault` method. We can also prevent the event from bubbling up the DOM tree using `stopPropagation` so that parent elements aren't notified of its occurrence (in the case that event delegation is being used). +If the element has default functionality for a specific event (like a link opens a new page, a button in a form submits the form, etc.), that default functionality can be cancelled. This is often useful for AJAX requests. When a user clicks on a button to submit a form via AJAX, we’d want to cancel the button/form’s default action (to submit it to the form’s `action` attribute), and we would instead do an AJAX request to accomplish the same task for a more seamless experience. To do this, we would utilize the event object and call its `.preventDefault()` method. We can also prevent the event from bubbling up the DOM tree using `.stopPropagation()` so that parent elements aren’t notified of its occurrence (in the case that event delegation is being used). ``` // Preventing a default action from occurring and stopping the event bubbling @@ -139,6 +139,7 @@ $( "form" ).on( "submit", function( event ) { // Prevent the form's default submission. event.preventDefault(); + // Prevent event from bubbling up DOM tree, prohibiting delegation event.stopPropagation(); // Make an AJAX request to submit the form data @@ -146,11 +147,11 @@ $( "form" ).on( "submit", function( event ) { }); ``` -When utilizing both `preventDefault` and `stopPropagation` simultaneously, you can instead `return false` to achieve both in a more concise manner, but it's advisable to only `return false` when both are actually necessary and not just for the sake of terseness. A final note on `stopPropagation` is that when using it in delegated events, the soonest that event bubbling can be stopped is when the event reaches the element that is delegating it. +When utilizing both `.preventDefault()` and `.stopPropagation()` simultaneously, you can instead `return false` to achieve both in a more concise manner, but it’s advisable to only `return false` when both are actually necessary and not just for the sake of terseness. A final note on `.stopPropagation()` is that when using it in delegated events, the soonest that event bubbling can be stopped is when the event reaches the element that is delegating it. -It's also important to note that the event object contains a property called `originalEvent`, which is the event object that the browser itself created. jQuery wraps this native event object with some useful methods and properties, but in some instances, you'll need to access the original event via `event.originalEvent` for instance. This is especially useful for touch events on mobile devices and tablets. +It’s also important to note that the event object contains a property called `originalEvent`, which is the event object that the browser itself created. jQuery wraps this native event object with some useful methods and properties, but in some instances, you’ll need to access the original event via `event.originalEvent` for instance. This is especially useful for touch events on mobile devices and tablets. -Finally, to inspect the event itself and see all of the data it contains, you should log the event in the browser's console using `console.log`. This will allow you to see all of an event's properties (including the `originalEvent`) which can be really helpful for debugging. +Finally, to inspect the event itself and see all of the data it contains, you should log the event in the browser’s console using `console.log`. This will allow you to see all of an event’s properties (including the `originalEvent`) which can be really helpful for debugging. ``` // Logging an event's information diff --git a/page/events/triggering-event-handlers.md b/page/events/triggering-event-handlers.md index c98fbddb..83c56199 100644 --- a/page/events/triggering-event-handlers.md +++ b/page/events/triggering-event-handlers.md @@ -2,20 +2,20 @@ title : Triggering Event Handlers level: intermediate source: http://jqfundamentals.com/legacy -attribution: +attribution: - jQuery Fundamentals --- -jQuery provides a way to trigger the event handlers bound to an element without any user interaction via the +jQuery provides a way to trigger the event handlers bound to an element without any user interaction via the `.trigger()` method. -## What handlers can be .trigger()'d +## What handlers can be .trigger()’d? -jQuery's event handling system is a layer on top of native browser events. When an event handler is added using -`.on("click",function() {...})`, it can be triggered using jQuery's `.trigger("click")`because jQuery stores a -reference to that handler when it is originally added. Additionally, it will trigger the javascript inside the -"onclick" attribute. The `.trigger()` function cannot be used to mimic native browser events, such as -clicking on a file input box or an anchor tag. This is because, there is no event handler attached using jQuery's +jQuery’s event handling system is a layer on top of native browser events. When an event handler is added using +`.on( "click", function() {...} )`, it can be triggered using jQuery’s `.trigger( "click" )` because jQuery stores a +reference to that handler when it is originally added. Additionally, it will trigger the JavaScript inside the +`onclick` attribute. The `.trigger()` function cannot be used to mimic native browser events, such as +clicking on a file input box or an anchor tag. This is because, there is no event handler attached using jQuery’s event system that corresponds to these events. ``` @@ -31,7 +31,7 @@ $( "a" ).trigger( "click" ); In order to trigger a native browser event, you have to use [document.createEventObject](http://msdn.microsoft.com/en-us/library/ie/ms536390%28v=vs.85%29.aspx) for < IE9 and [document.createEvent](https://developer.mozilla.org/en/DOM/document.createEvent) for all other browsers. Using these two APIs, you can programmatically create an event that behaves exactly as if someone has actually clicked on a file input box. The default action will happen, and the browse file dialog will display. -The jQuery UI Team created [jquery.simulate.js](https://github.com/eduardolundgren/jquery-simulate/blob/master/jquery.simulate.js) in order to simplify triggering a native browser event for use in their automated testing. Its usage is modeled after jQuery's trigger. +The jQuery UI Team created [jquery.simulate.js](https://github.com/eduardolundgren/jquery-simulate/blob/master/jquery.simulate.js) in order to simplify triggering a native browser event for use in their automated testing. Its usage is modeled after jQuery’s trigger. ``` // Triggering a native browser event using the simulate plugin @@ -52,11 +52,11 @@ There are four differences between `.trigger()` and `.triggerHandler()` For more information see the [triggerHandler documentation](http://api.jquery.com/triggerHandler) -## Don't use `.trigger()` simply to execute specific functions +## Don’t use `.trigger()` simply to execute specific functions While this method has its uses, it should not be used simply to call a function that was bound as a click -handler. Instead, you should store the function you want to call in a -variable, and pass the variable name when you do your binding. Then, you can +handler. Instead, you should store the function you want to call in a +variable, and pass the variable name when you do your binding. Then, you can call the function itself whenever you want, without the need for `.trigger()`. @@ -76,5 +76,4 @@ foo(); // instead of $( "p" ).trigger( "click" ) ``` A more complex architecture can built on top of trigger using the [publish-subscribe pattern](http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) using [jQuery plugins](https://gist.github.com/661855). -With this technique, `$.fn.trigger` can be used to notify other sections of code that an application specific event has happened. - +With this technique, `$.fn.trigger` can be used to notify other sections of code that an application specific event has happened. From 86a2eefd2d5df60ebaeb61687a73411452d377b2 Mon Sep 17 00:00:00 2001 From: Markus Amalthea Magnuson Date: Tue, 5 Mar 2013 01:02:35 +0100 Subject: [PATCH 3/3] No entities. --- page/events/event-basics.md | 18 ++--- page/events/event-delegation.md | 8 +- page/events/event-extensions.md | 48 +++++------ page/events/event-helpers.md | 2 +- page/events/handling-events.md | 20 ++--- page/events/history-of-events.md | 2 +- page/events/inside-event-handling-function.md | 2 +- page/events/introduction-to-custom-events.md | 80 +++++++++---------- page/events/introduction-to-events.md | 48 +++++------ page/events/triggering-event-handlers.md | 12 +-- 10 files changed, 120 insertions(+), 120 deletions(-) diff --git a/page/events/event-basics.md b/page/events/event-basics.md index 8076cbb6..a9485f8d 100644 --- a/page/events/event-basics.md +++ b/page/events/event-basics.md @@ -10,14 +10,14 @@ level: beginner ### Setting Up Event Responses on DOM Elements jQuery makes it straightforward to set up event-driven responses on page elements. -These events are often triggered by the end user’s interaction with the page, +These events are often triggered by the end user's interaction with the page, such as when text is entered into a form element or the mouse pointer is moved. In some cases, such as the page load and unload events, the browser itself will trigger the event. -jQuery offers convenience methods for most native browser events. These methods — -including `$.fn.click`, `$.fn.focus`, `$.fn.blur`, `$.fn.change`, etc. — are shorthand -for jQuery’s `$.fn.on` method. The `on` method is useful for binding the same handler +jQuery offers convenience methods for most native browser events. These methods — +including `$.fn.click`, `$.fn.focus`, `$.fn.blur`, `$.fn.change`, etc. — are shorthand +for jQuery's `$.fn.on` method. The `on` method is useful for binding the same handler function to multiple events, when you want to provide data to the event hander, when you are working with custom events, or when you want to pass an object of multiple events and handlers. @@ -41,7 +41,7 @@ $( "p" ).on( "click", function() { It is important to note that `$.fn.on` can only create event listeners on elements that exist *at the time you set up the listeners*. Similar elements created after the event listeners are established will not automatically pick up event behaviors -you’ve set up previously. For example: +you've set up previously. For example: ``` $( document ).ready(function(){ @@ -74,7 +74,7 @@ the page display area (not the entire browser window). #### type -The type of the event (e.g. “click”). +The type of the event (e.g. "click"). #### which @@ -168,8 +168,8 @@ $( "p" ).on({ ### Namespacing Events For complex applications and for plugins you share with others, it can be -useful to namespace your events so you don’t unintentionally disconnect events -that you didn’t or couldn’t know about. +useful to namespace your events so you don't unintentionally disconnect events +that you didn't or couldn't know about. ``` // Namespacing events @@ -201,7 +201,7 @@ $( "p" ).off( "click", bar ); // foo is still bound to the click event ### Setting Up Events to Run Only Once -Sometimes you need a particular handler to run only once — after that, you may +Sometimes you need a particular handler to run only once — after that, you may want no handler to run, or you may want a different handler to run. jQuery provides the `$.fn.one` method for this purpose. diff --git a/page/events/event-delegation.md b/page/events/event-delegation.md index 0b5ac55c..dd27e268 100644 --- a/page/events/event-delegation.md +++ b/page/events/event-delegation.md @@ -39,7 +39,7 @@ While this works perfectly fine, there are drawbacks. Consider this: // add a new element on to our existing list $( "#list" ).append( "

Item #101

" ); ``` -If we were to click our newly added item, nothing would happen. This is because of the directly bound event that we attached previously. Direct events are only attached to elements at the time we called the `.on()` method for our existing collection of ``’s, that is only the ``’s that were found when we call `$()`. +If we were to click our newly added item, nothing would happen. This is because of the directly bound event that we attached previously. Direct events are only attached to elements at the time we called the `.on()` method for our existing collection of ``'s, that is only the ``'s that were found when we call `$()`. ## Event Propagation Understanding how events propagate is an important factor in being able to leverage Event Delegation. Any time an anchor tags is clicked, a *click* event is fired for the: @@ -62,9 +62,9 @@ $( "#list" ).on( "click", "a", function( event ) { console.log( $( this ).text() ); }); ``` -Notice for the second parameter to the `.on()` method we are telling it which selector to listen for. Now when a *click* event is triggered on our `

`, our delegated event will check to see if the triggering element matches our selector (`"a"`). If it does, our anonymous function will execute. We have now attached a single *click* event listener to our `
` instead of an unknown number of directly bound events on our ``’s. +Notice for the second parameter to the `.on()` method we are telling it which selector to listen for. Now when a *click* event is triggered on our `
`, our delegated event will check to see if the triggering element matches our selector (`"a"`). If it does, our anonymous function will execute. We have now attached a single *click* event listener to our `
` instead of an unknown number of directly bound events on our ``'s. -Now lets say that whenever a link is clicked we want to check and see if the `href` attribute starts with “http” and if it does we want to set the `target` attribute to `_blank`. +Now lets say that whenever a link is clicked we want to check and see if the `href` attribute starts with "http" and if it does we want to set the `target` attribute to `_blank`. ``` // attach a delegated event $( "#list" ).on( "click", "a", function( event ) { @@ -74,7 +74,7 @@ $( "#list" ).on( "click", "a", function( event ) { } }); ``` -This simply passes the `.is()` method a selector to see if the element’s `href` attributes starts with “http”. Also we have removed the `event.preventDefault();` statement, this is because we want the default action to happen (which is to following the `href`) +This simply passes the `.is()` method a selector to see if the element's `href` attributes starts with "http". Also we have removed the `event.preventDefault();` statement, this is because we want the default action to happen (which is to following the `href`) We can actually take this a step further and make our code simpler and more concise by allowing the selector argument to `.on()` do our logic for us. ``` diff --git a/page/events/event-extensions.md b/page/events/event-extensions.md index 7df7f1f8..ff4563f7 100644 --- a/page/events/event-extensions.md +++ b/page/events/event-extensions.md @@ -4,45 +4,45 @@ level: advanced --- jQuery offers several ways to extend its event system to provide custom functionality when events are attached to elements. Internally in jQuery, these extensions are primarily used to ensure that standard events such as `submit` and `change` behave consistently across browsers. However, they can also be used to define new events with custom behavior. -This document covers the extensions available starting with jQuery 1.7; a sparsely documented subset of this functionality has been available since jQuery 1.3 but the differences in functionality are extensive. For an overview of special events in earlier versions, see [Ben Alman’s jQuery Special Events](http://benalman.com/news/2010/03/jquery-special-events/) article. +This document covers the extensions available starting with jQuery 1.7; a sparsely documented subset of this functionality has been available since jQuery 1.3 but the differences in functionality are extensive. For an overview of special events in earlier versions, see [Ben Alman's jQuery Special Events](http://benalman.com/news/2010/03/jquery-special-events/) article. > **Note:** jQuery event extensions are an advanced feature; they require deeper knowledge of both browser behavior and jQuery internals than most of the API. Most users of jQuery will not need to use event extensions, and those who do should use them with care. For example, on a large project with third-party plugins, changing the behavior of standard events such as `click` or `mouseover` can cause serious compatibility issues. ### Events overview and general advice -When writing an event extension, it is essential to understand the flow of events through jQuery’s internal event system. For a description of the event system from the API level, including a discussion of event delegation, see the [`.on()`](http://api.jquery.com/on) method. +When writing an event extension, it is essential to understand the flow of events through jQuery's internal event system. For a description of the event system from the API level, including a discussion of event delegation, see the [`.on()`](http://api.jquery.com/on) method. -To simplify event management, jQuery only attaches a single event handler per element per event type (using `addEventListener` on W3C-compliant browsers or `attachEvent` on older IE) and then dispatches to event handlers that are attached via jQuery’s APIs. For example, if three “click” event handlers are attached to an element, jQuery attaches its own handler when the first handler is attached and adds the user’s event handler to a list to be executed when the event occurs. For subsequent event handlers, jQuery only adds them to its own internal list since it has already called the browser to attach its solitary handler. Conversely, jQuery removes its own event handler from the browser when the final event of a particular type is removed from the element. +To simplify event management, jQuery only attaches a single event handler per element per event type (using `addEventListener` on W3C-compliant browsers or `attachEvent` on older IE) and then dispatches to event handlers that are attached via jQuery's APIs. For example, if three "click" event handlers are attached to an element, jQuery attaches its own handler when the first handler is attached and adds the user's event handler to a list to be executed when the event occurs. For subsequent event handlers, jQuery only adds them to its own internal list since it has already called the browser to attach its solitary handler. Conversely, jQuery removes its own event handler from the browser when the final event of a particular type is removed from the element. -An event can be a *native* event defined by the W3C and fired by the browser in response to something such as a user clicking a mouse button or pressing a key. It can also be a *custom* event, triggered only by code via jQuery’s `.trigger()` or `.triggerHandler()` methods. Code can also trigger native browser events, which is convenient for simulating user actions. +An event can be a *native* event defined by the W3C and fired by the browser in response to something such as a user clicking a mouse button or pressing a key. It can also be a *custom* event, triggered only by code via jQuery's `.trigger()` or `.triggerHandler()` methods. Code can also trigger native browser events, which is convenient for simulating user actions. In general, jQuery does not have intrinsic knowledge of whether an event name may be fired by a browser. So by default, jQuery always attaches an event to the browser when an API call is made to add an event handler for that event. If that event type is never generated by the browser, the only way the handler will be called is if JavaScript code triggers the event. Although there is generally no harm in attaching an unused event name to the browser, the default behavior can be overridden using the special event `setup` hook as described below. Whenever elements are removed from a document via jQuery, the event system tries to ensure that events and related data are removed from the elements to prevent memory leaks. (Older versions of Internet Explorer are notorious for leaking memory in these situations if not managed carefully.) If an event extension attaches events or creates new objects, it should detach those objects or clear the data when the event is removed by defining `remove` and `teardown` hooks. -jQuery event extension developers should avoid using event names that have special meaning in a DOM setting. Event names such as “click”, “change”, or “load” have specific semantics defined by the W3C, so using them as custom events can cause unexpected behavior. Generally, jQuery event extensions should *only* be used for W3C-defined event names when the extension is normalizing behavior across browsers. A common convention to avoid collisions for custom events is to embed a colon or dash in the event type name, since no W3C events use those characters. +jQuery event extension developers should avoid using event names that have special meaning in a DOM setting. Event names such as "click", "change", or "load" have specific semantics defined by the W3C, so using them as custom events can cause unexpected behavior. Generally, jQuery event extensions should *only* be used for W3C-defined event names when the extension is normalizing behavior across browsers. A common convention to avoid collisions for custom events is to embed a colon or dash in the event type name, since no W3C events use those characters. -Although jQuery’s event system is oriented towards delivering DOM events to DOM elements, jQuery methods can be used to attach and trigger events on plain objects. For example, it can be used as a simple publish/subscribe mechanism. Developers of event extensions should attempt to avoid unwanted behavior if their extensions are used in a mixed scenario with DOM and plain objects. The canonical way that jQuery detects a DOM element is to check for `elem.nodeType === 1` on the object. +Although jQuery's event system is oriented towards delivering DOM events to DOM elements, jQuery methods can be used to attach and trigger events on plain objects. For example, it can be used as a simple publish/subscribe mechanism. Developers of event extensions should attempt to avoid unwanted behavior if their extensions are used in a mixed scenario with DOM and plain objects. The canonical way that jQuery detects a DOM element is to check for `elem.nodeType === 1` on the object. ### jQuery.event.props: Array jQuery defines an [Event object](http://api.jquery.com/jQuery.Event/) that represents a cross-browser subset of the information available when an event occurs. The `jQuery.event.props` property is an array of string names for properties that are always copied when jQuery processes a *native* browser event. (Events fired in code by `.trigger()` do not use this list, since the code can construct a `jQuery.Event` object with the needed values and trigger using that object.) -To add a property name to this list, use `jQuery.event.props.push( "newPropertyName" )`. However, be aware that every event processed by jQuery will now attempt to copy this property name from the native browser event to jQuery’s constructed event. If the property does not exist for that event type, it will get an undefined value. Adding many properties to this list can significantly reduce event delivery performance, so for infrequently-needed properties it is more efficient to use the value directly from `event.originalEvent` instead. If properties must be copied, you are strongly advised to use `jQuery.event.fixHooks` as of version 1.7. +To add a property name to this list, use `jQuery.event.props.push( "newPropertyName" )`. However, be aware that every event processed by jQuery will now attempt to copy this property name from the native browser event to jQuery's constructed event. If the property does not exist for that event type, it will get an undefined value. Adding many properties to this list can significantly reduce event delivery performance, so for infrequently-needed properties it is more efficient to use the value directly from `event.originalEvent` instead. If properties must be copied, you are strongly advised to use `jQuery.event.fixHooks` as of version 1.7. ### jQuery.event.fixHooks: Object The `fixHooks` interface provides a per-event-type way to extend or normalize the event object that jQuery creates when it processes a *native* browser event. A `fixHooks` entry is an object that has two properties, each being optional: `props`: Array: -Strings representing properties that should be copied from the browser’s event object to the jQuery event object. If omitted, no additional properties are copied beyond the standard ones that jQuery copies and normalizes (e.g. `event.target` and `event.relatedTarget`). +Strings representing properties that should be copied from the browser's event object to the jQuery event object. If omitted, no additional properties are copied beyond the standard ones that jQuery copies and normalizes (e.g. `event.target` and `event.relatedTarget`). `filter`: Function( event, originalEvent ): -jQuery calls this function after it constructs the `jQuery.Event` object, copies standard properties from `jQuery.event.props`, and copies the `fixHooks`-specific props (if any) specified above. The function can create new properties on the event object or modify existing ones. The second argument is the browser’s native event object, which is also available in `event.originalEvent`. +jQuery calls this function after it constructs the `jQuery.Event` object, copies standard properties from `jQuery.event.props`, and copies the `fixHooks`-specific props (if any) specified above. The function can create new properties on the event object or modify existing ones. The second argument is the browser's native event object, which is also available in `event.originalEvent`. -Note that for all events, the browser’s native event object is available in `event.originalEvent`; if the jQuery event handler examines the properties there instead of jQuery’s normalized `event` object, there is no need to create a `fixHooks` entry to copy or modify the properties. +Note that for all events, the browser's native event object is available in `event.originalEvent`; if the jQuery event handler examines the properties there instead of jQuery's normalized `event` object, there is no need to create a `fixHooks` entry to copy or modify the properties. -For example, to set a hook for the “drop” event that copies the `dataTransfer` property, assign an object to `jQuery.event.fixHooks.drop`: +For example, to set a hook for the "drop" event that copies the `dataTransfer` property, assign an object to `jQuery.event.fixHooks.drop`: ``` jQuery.event.fixHooks.drop = { @@ -88,7 +88,7 @@ As with `fixHooks`, the special event hooks design assumes it will be very rare #### noBubble: Boolean -Indicates whether this event type should be bubbled when the `.trigger()` method is called; by default it is `false`, meaning that a triggered event will bubble to the element’s parents up to the document (if attached to a document) and then to the window. Note that defining `noBubble` on an event will effectively prevent that event from being used for delegated events with `.trigger()`. +Indicates whether this event type should be bubbled when the `.trigger()` method is called; by default it is `false`, meaning that a triggered event will bubble to the element's parents up to the document (if attached to a document) and then to the window. Note that defining `noBubble` on an event will effectively prevent that event from being used for delegated events with `.trigger()`. #### bindType: String, delegateType: String @@ -105,11 +105,11 @@ jQuery.event.special.pushy = { When these properties are defined, the following behavior occurs in the jQuery event system: -* Event handlers for the “pushy” event are actually attached to “click” — both directly bound and delegated events. -* Special event hooks for “click” are called if they exist, *except* the `handle` hook for “pushy” is called when an event is delivered if one exists. -* Event handlers for “pushy” must be removed using the “pushy” event name, and are unaffected if “click” events are removed from the same elements. +* Event handlers for the "pushy" event are actually attached to "click" — both directly bound and delegated events. +* Special event hooks for "click" are called if they exist, *except* the `handle` hook for "pushy" is called when an event is delivered if one exists. +* Event handlers for "pushy" must be removed using the "pushy" event name, and are unaffected if "click" events are removed from the same elements. -So given the special event above, this code shows that a pushy isn’t removed by removing clicks. That might be an effective way to defend against an ill-behaved plugin that didn’t namespace its removal of click events, for example: +So given the special event above, this code shows that a pushy isn't removed by removing clicks. That might be an effective way to defend against an ill-behaved plugin that didn't namespace its removal of click events, for example: ``` var $p = $( "p" ); @@ -131,7 +131,7 @@ $p.trigger( "click" ); // still triggers "pushy" $p.off( "pushy" ); ``` -These two properties are often used in conjunction with a `handle` hook function; the hook might, for example, change the event name from “click” to “pushy” before calling event handlers. See below for an example. +These two properties are often used in conjunction with a `handle` hook function; the hook might, for example, change the event name from "click" to "pushy" before calling event handlers. See below for an example. #### The handleObj object @@ -147,7 +147,7 @@ $( ".dialog" ).on( "click.myPlugin", "button", { The type of event, such as `"click"`. When special event mapping is used via `bindType` or `delegateType`, this will be the mapped type. `origType`: String: -The original type name (in this case, `"click"`) regardless of whether it was mapped via `bindType` or `delegateType`. So when a “pushy” event is mapped to “click” its `origType` would be “pushy”. See the examples in those special event properties above for more detail. +The original type name (in this case, `"click"`) regardless of whether it was mapped via `bindType` or `delegateType`. So when a "pushy" event is mapped to "click" its `origType` would be "pushy". See the examples in those special event properties above for more detail. `namespace`: String: Namespace(s), if any, provided when the event was attached, such as `"myPlugin"`. When multiple namespaces are given, they are separated by periods and sorted in ascending alphabetical order. If no namespaces are provided, this property is an empty string. @@ -163,13 +163,13 @@ Event handler function passed to jQuery during event binding; in the example it #### setup: function( data: Object, namespaces, eventHandle: function ) -The setup hook is called the first time an event of a particular type is attached to an element; this provides the hook an opportunity to do processing that will apply to all events of this type on this element. The `this` keyword will be a reference to the element where the event is being attached and `eventHandle` is jQuery’s event handler function. In most cases the `namespaces` argument should not be used, since it only represents the namespaces of the *first* event being attached; subsequent events may not have this same namespaces. +The setup hook is called the first time an event of a particular type is attached to an element; this provides the hook an opportunity to do processing that will apply to all events of this type on this element. The `this` keyword will be a reference to the element where the event is being attached and `eventHandle` is jQuery's event handler function. In most cases the `namespaces` argument should not be used, since it only represents the namespaces of the *first* event being attached; subsequent events may not have this same namespaces. This hook can perform whatever processing it desires, including attaching its own event handlers to the element or to other elements and recording setup information on the element using the `jQuery.data()` method. If the setup hook wants jQuery to add a browser event (via `addEventListener` or `attachEvent`, depending on browser) it should return `false`. In all other cases, jQuery will not add the browser event, but will continue all its other bookkeeping for the event. This would be appropriate, for example, if the event was never fired by the browser but invoked by `.trigger()`. To attach the jQuery event handler in the setup hook, use the `eventHandle` argument. #### teardown: function() -The teardown hook is called when the final event of a particular type is removed from an element. The `this` keyword will be a reference to the element where the event is being cleaned up. This hook should return `false` if it wants jQuery to remove the event from the browser’s event system (via `removeEventListener` or `detachEvent`). In most cases, the setup and teardown hooks should return the same value. +The teardown hook is called when the final event of a particular type is removed from an element. The `this` keyword will be a reference to the element where the event is being cleaned up. This hook should return `false` if it wants jQuery to remove the event from the browser's event system (via `removeEventListener` or `detachEvent`). In most cases, the setup and teardown hooks should return the same value. If the setup hook attached event handlers or added data to an element through a mechanism such as `jQuery.data()`, the teardown hook should reverse the process and remove them. jQuery will generally remove the data and events when an element is totally removed from the document, but failing to remove data or events on teardown will cause a memory leak if the element stays in the document. @@ -183,17 +183,17 @@ When an event handler is removed from an element using an API such as `.off()`, #### trigger: function( event: jQuery.Event, data: Object ) -Called when the `.trigger()` or `.triggerHandler()` methods are used to trigger an event for the special type from code, as opposed to events that originate from within the browser. The `this` keyword will be the element being triggered, and the event argument will be a `jQuery.Event` object constructed from the caller’s input. At minimum, the event type, data, namespace, and target properties are set on the event. The data argument represents additional data passed by `.trigger()` if present. +Called when the `.trigger()` or `.triggerHandler()` methods are used to trigger an event for the special type from code, as opposed to events that originate from within the browser. The `this` keyword will be the element being triggered, and the event argument will be a `jQuery.Event` object constructed from the caller's input. At minimum, the event type, data, namespace, and target properties are set on the event. The data argument represents additional data passed by `.trigger()` if present. The trigger hook is called early in the process of triggering an event, just after the `jQuery.Event` object is constructed and before any handlers have been called. It can process the triggered event in any way, for example by calling `event.stopPropagation()` or `event.preventDefault()` before returning. If the hook returns `false`, jQuery does not perform any further event triggering actions and returns immediately. Otherwise, it performs the normal trigger processing, calling any event handlers for the element and bubbling the event (unless propagation is stopped in advance or `noBubble` was specified for the special event) to call event handlers attached to parent elements. #### _default: function( event: jQuery.Event, data: Object ) -When the `.trigger()` method finishes running all the event handlers for an event, it also looks for and runs any method on the target object by the same name unless of the handlers called `event.preventDefault()`. So, `.trigger( "submit" )` will execute the `submit()` method on the element if one exists. When a `_default` hook is specified, the hook is called just prior to checking for and executing the element’s default method. If this hook returns the value `false` the element’s default method will be called; otherwise it is not. +When the `.trigger()` method finishes running all the event handlers for an event, it also looks for and runs any method on the target object by the same name unless of the handlers called `event.preventDefault()`. So, `.trigger( "submit" )` will execute the `submit()` method on the element if one exists. When a `_default` hook is specified, the hook is called just prior to checking for and executing the element's default method. If this hook returns the value `false` the element's default method will be called; otherwise it is not. #### handle: function( event: jQuery.Event, data: Object ) -jQuery calls a handle hook when the event has occurred and jQuery would normally call the user’s event handler specified by `.on()` or another event binding method. If the hook exists, jQuery calls it *instead of* that event handler, passing it the event and any data passed from `.trigger()` if it was not a native event. The `this` keyword is the DOM element being handled, and `event.handleObj` property has the detailed event information. +jQuery calls a handle hook when the event has occurred and jQuery would normally call the user's event handler specified by `.on()` or another event binding method. If the hook exists, jQuery calls it *instead of* that event handler, passing it the event and any data passed from `.trigger()` if it was not a native event. The `this` keyword is the DOM element being handled, and `event.handleObj` property has the detailed event information. Based in the information it has, the handle hook should decide whether to call the original handler function which is in `event.handleObj.handler`. It can modify information in the event object before calling the original handler, but *must restore* that data before returning or subsequent unrelated event handlers may act unpredictably. In most cases, the handle hook should return the result of the original handler, but that is at the discretion of the hook. The handle hook is unique in that it is the only special event function hook that is called under its original special event name when the type is mapped using `bindType` and `delegateType`. For that reason, it is almost always an error to have anything other than a handle hook present if the special event defines a `bindType` and `delegateType`, since those other hooks will never be called. @@ -202,7 +202,7 @@ The handle hook is unique in that it is the only special event function hook tha This `multiclick` special event maps itself into a standard click event, but uses a handle hook so that it can monitor the event and only deliver it when the user clicks on the element a multiple of the number of times specified during event binding. -The hook stores the current click count in the data object, so multiclick handlers on different elements don’t interfere with each other. It changes the event type to the original “multiclick” type before calling the handler and restores it to the mapped “click” type before returning: +The hook stores the current click count in the data object, so multiclick handlers on different elements don't interfere with each other. It changes the event type to the original "multiclick" type before calling the handler and restores it to the mapped "click" type before returning: ``` jQuery.event.special.multiclick = { diff --git a/page/events/event-helpers.md b/page/events/event-helpers.md index a30c8b6c..ca8a321b 100644 --- a/page/events/event-helpers.md +++ b/page/events/event-helpers.md @@ -25,7 +25,7 @@ $( "#menu li" ).hover(function() { ### `$.fn.toggle` -The `$.fn.toggle` method is triggered by the “click” event and accepts two or +The `$.fn.toggle` method is triggered by the "click" event and accepts two or more functions. Each time the click event occurs, the next function in the list is called. Generally, `$.fn.toggle` is used with just two functions; however, it will accept an unlimited number of functions. Be careful, though: diff --git a/page/events/handling-events.md b/page/events/handling-events.md index 45cc3c15..c4267fba 100644 --- a/page/events/handling-events.md +++ b/page/events/handling-events.md @@ -7,7 +7,7 @@ attribution: --- jQuery provides a method `.on()` to respond to any event on the selected elements. This is called an _event binding_. -Although `.on()` isn’t the only method provided for event binding, it is a best +Although `.on()` isn't the only method provided for event binding, it is a best practice to use this for jQuery 1.7+. To learn more, [read more about the evolution of event binding in jQuery](/events/history-of-events). @@ -33,7 +33,7 @@ $( "p" ).on( "click", function() { #### Many events, but only one event handler Suppose you want to trigger the same event whenever the mouse hovers over or leaves -the selected elements. The best practice for this is to use “mouseenter mouseleave”. +the selected elements. The best practice for this is to use "mouseenter mouseleave". Note the difference between this and the next example. ``` @@ -68,7 +68,7 @@ $( "div" ).on({ #### The event object -Handling events can be tricky. It’s often helpful to use the extra information contained +Handling events can be tricky. It's often helpful to use the extra information contained in the event object passed to the event handler for more control. To become familiar with the event object, use this code to inspect it in your browser console after you click on a `
` in the page. For a breakdown of the event object, see [Inside the Event Handling Function](/events/inside-event-handling-function/). @@ -93,9 +93,9 @@ $( "p" ).on( "click", { ``` -#### Binding events to elements that don’t exist yet +#### Binding events to elements that don't exist yet -This is called _event delegation_. Here’s an example just for completeness, but see the +This is called _event delegation_. Here's an example just for completeness, but see the page on [Event Delegation](/events/event-delegation/) for a full explanation. ``` @@ -106,7 +106,7 @@ $( "ul" ).on( "click", "li", function() { ### Connecting Events to Run Only Once -Sometimes you need a particular handler to run only once — after that, you may +Sometimes you need a particular handler to run only once — after that, you may want no handler to run, or you may want a different handler to run. jQuery provides the `.one()` method for this purpose. @@ -128,9 +128,9 @@ or multiple handlers, passing custom data and event delegation. ### Disconnecting Events -Although all the fun of jQuery occurs in the `.on()` method, it’s counterpart is just as important +Although all the fun of jQuery occurs in the `.on()` method, it's counterpart is just as important if you want to be a responsible developer. `.off()` cleans up that event -binding when you don’t need it anymore. Complex user interfaces with lots of event bindings +binding when you don't need it anymore. Complex user interfaces with lots of event bindings can bog down browser performance, so using the `.off()` method diligently is a best practice to ensure that you only have the event bindings that you need, when you need them. @@ -158,7 +158,7 @@ $( "p" ).off( "click", bar ); ### Namespacing Events For complex applications and for plugins you share with others, it can be -useful to namespace your events so you don’t unintentionally disconnect events -that you didn’t or couldn’t know about. For details, see Event Namespacing. +useful to namespace your events so you don't unintentionally disconnect events +that you didn't or couldn't know about. For details, see Event Namespacing. diff --git a/page/events/history-of-events.md b/page/events/history-of-events.md index 788bf1ed..16b30df6 100644 --- a/page/events/history-of-events.md +++ b/page/events/history-of-events.md @@ -37,7 +37,7 @@ As discussed in the [event delegation](/event/event-delegation) article, this is ### [.bind()](http://api.jquery.com/bind/) delegation (Deprecated) Introduced in jQuery v1.0 -Generally we don’t associate `.bind()` with *event delegation*, however prior to jQuery v1.3 it was the only means of delegation available to us. +Generally we don't associate `.bind()` with *event delegation*, however prior to jQuery v1.3 it was the only means of delegation available to us. ``` ​$( "#list" ).bind( "click", function( event ) { diff --git a/page/events/inside-event-handling-function.md b/page/events/inside-event-handling-function.md index b7f896f0..0c13f5a2 100644 --- a/page/events/inside-event-handling-function.md +++ b/page/events/inside-event-handling-function.md @@ -17,7 +17,7 @@ the page. #### type -The type of the event (e.g. “click”). +The type of the event (e.g. "click"). #### which diff --git a/page/events/introduction-to-custom-events.md b/page/events/introduction-to-custom-events.md index 0cafc195..17b84adb 100644 --- a/page/events/introduction-to-custom-events.md +++ b/page/events/introduction-to-custom-events.md @@ -8,13 +8,13 @@ attribution: ## Custom Events -We’re all familiar with the basic events — click, mouseover, focus, blur, -submit, etc. — that we can latch on to as a user interacts with the browser. +We're all familiar with the basic events — click, mouseover, focus, blur, +submit, etc. — that we can latch on to as a user interacts with the browser. Custom events open up a whole new world of event-driven programming. In this -chapter, we’ll use jQuery’s custom events system to make a simple Twitter +chapter, we'll use jQuery's custom events system to make a simple Twitter search application. -It can be difficult at first to understand why you’d want to use custom events, +It can be difficult at first to understand why you'd want to use custom events, when the built-in events seem to suit your needs just fine. It turns out that custom events offer a whole new way of thinking about event-driven JavaScript. Instead of focusing on the element that triggers an action, custom events put @@ -27,7 +27,7 @@ including: Why should you care? An example is probably the best way to explain. Suppose you have a lightbulb in a room in a house. The lightbulb is currently turned -on, and it’s controlled by two three-way switches and a clapper: +on, and it's controlled by two three-way switches and a clapper: ```
@@ -39,7 +39,7 @@ on, and it’s controlled by two three-way switches and a clapper: ``` Triggering the clapper or either of the switches will change the state of the -lightbulb. The switches and the clapper don’t care what state the lightbulb is +lightbulb. The switches and the clapper don't care what state the lightbulb is in; they just want to change the state. Without custom events, you might write some code like this: @@ -72,9 +72,9 @@ $( ".switch, .clapper" ).click(function() { }); ``` -This last bit of code is not that exciting, but something important has happened: we’ve moved the behavior of the lightbulb to the lightbulb, and away from the switches and the clapper. +This last bit of code is not that exciting, but something important has happened: we've moved the behavior of the lightbulb to the lightbulb, and away from the switches and the clapper. -Let’s make our example a little more interesting. We’ll add another room to our house, along with a master switch, as shown here: +Let's make our example a little more interesting. We'll add another room to our house, along with a master switch, as shown here: ```
@@ -94,8 +94,8 @@ Let’s make our example a little more interesting. We’ll add another If there are any lights on in the house, we want the master switch to turn all the lights off; otherwise, we want it to turn all lights on. To accomplish -this, we’ll add two more custom events to the lightbulbs: `turnOn` and -`turnOff`. We’ll make use of them in the `changeState` custom event, and use +this, we'll add two more custom events to the lightbulbs: `turnOn` and +`turnOff`. We'll make use of them in the `changeState` custom event, and use some logic to decide which one the master switch should trigger: ``` @@ -128,7 +128,7 @@ $( "#master_switch" ).click(function() { Note how the behavior of the master switch is attached to the master switch; the behavior of a lightbulb belongs to the lightbulbs. -If you’re accustomed to object-oriented programming, you may find it useful to +If you're accustomed to object-oriented programming, you may find it useful to think of custom events as methods of objects. Loosely speaking, the object to which the method belongs is created via the jQuery selector. Binding the `changeState` custom event to all `$( ".light" )` elements is akin to having a @@ -139,7 +139,7 @@ class called `Light` with a method of `changeState`, and then instantiating new In the world of custom events, there are two important jQuery methods: `$.fn.on` and `$.fn.trigger`. In the [Events](/events/) chapter, we saw how to use these -methods for working with user events; for this chapter, it’s important to +methods for working with user events; for this chapter, it's important to remember two things: - `$.fn.on` method takes an event type and an event handling function as @@ -170,7 +170,7 @@ $( document ).trigger( "myCustomEvent", [ "bim", "baz" ] ); ### A Sample Application -To demonstrate the power of custom events, we’re going to create a simple tool +To demonstrate the power of custom events, we're going to create a simple tool for searching Twitter. The tool will offer several ways for a user to add search terms to the display: by entering a search term in a text box, by entering multiple search terms in the URL, and by querying Twitter for trending @@ -180,7 +180,7 @@ The results for each term will be shown in a results container; these containers will be able to be expanded, collapsed, refreshed, and removed, either individually or all at once. -When we’re done, it will look like this: +When we're done, it will look like this:  @@ -203,38 +203,38 @@ When we’re done, it will look like this: This gives us a container (`#twitter`) for our widget, a template for our results containers (hidden via CSS), and a simple form where users can input a search -term. (For the sake of simplicity, we’re going to assume that our application +term. (For the sake of simplicity, we're going to assume that our application is JavaScript-only and that our users will always have CSS.) -There are two types of objects we’ll want to act on: the results containers, +There are two types of objects we'll want to act on: the results containers, and the Twitter container. -The results containers are the heart of the application. We’ll create a plugin -that will prepare each results container once it’s added to the Twitter +The results containers are the heart of the application. We'll create a plugin +that will prepare each results container once it's added to the Twitter container. Among other things, it will bind the custom events for each container and add the action buttons at the top right of each container. Each results container will have the following custom events: -- `refresh` — Mark the container as being in the “refreshing” state, and fire +- `refresh` — Mark the container as being in the "refreshing" state, and fire the request to fetch the data for the search term. -- `populate` — Receive the returned JSON data and use it to populate the container. +- `populate` — Receive the returned JSON data and use it to populate the container. -- `remove` — Remove the container from the page after the user verifies the +- `remove` — Remove the container from the page after the user verifies the request to do so. Verification can be bypassed by passing `true` as the second argument to the event handler. The `remove` event also removes the term associated with the results container from the global object containing the search terms. -- `collapse` — Add a class of collapsed to the container, which will hide the - results via CSS. It will also turn the container’s “Collapse” button into an - “Expand” button. +- `collapse` — Add a class of collapsed to the container, which will hide the + results via CSS. It will also turn the container's "Collapse" button into an + "Expand" button. -- `expand` — Remove the collapsed class from the container. It will also turn - the container’s “Expand” button into a “Collapse” button. +- `expand` — Remove the collapsed class from the container. It will also turn + the container's "Expand" button into a "Collapse" button. The plugin is also responsible for adding the action buttons to the container. -It binds a click event to each action’s list item, and uses the list item’s +It binds a click event to each action's list item, and uses the list item's class to determine which custom event will be triggered on the corresponding results container. @@ -344,7 +344,7 @@ $.fn.twitterResult.events = { The Twitter container itself will have just two custom events: -- `getResults` — Receives a search term and checks to determine whether there’s +- `getResults` — Receives a search term and checks to determine whether there's already a results container for the term; if not, adds a results container using the results template, set up the results container using the `$.fn.twitterResult` plugin discussed above, and then triggers the `refresh` @@ -352,11 +352,11 @@ The Twitter container itself will have just two custom events: Finally, it will store the search term so the application knows not to re-fetch the term. -- `getTrends` — Queries Twitter for the top 10 trending terms, then iterates +- `getTrends` — Queries Twitter for the top 10 trending terms, then iterates over them and triggers the `getResults` event for each of them, thereby adding a results container for each term. -Here’s how the Twitter container bindings look: +Here's how the Twitter container bindings look: ``` $( "#twitter" ).on( "getResults", function( e, term ) { @@ -392,14 +392,14 @@ $( "#twitter" ).on( "getResults", function( e, term ) { }); ``` -So far, we’ve written a lot of code that does approximately nothing, but that’s +So far, we've written a lot of code that does approximately nothing, but that's OK. By specifying all the behaviors that we want our core objects to have, -we’ve created a solid framework for rapidly building out the interface. +we've created a solid framework for rapidly building out the interface. -Let’s start by hooking up our text input and the “Load Trending Terms” button. -For the text input, we’ll capture the term that was entered in the input and -pass it as we trigger the Twitter container’s `getResults` event. Clicking the -“Load Trending Terms” will trigger the Twitter container’s `getTrends` event: +Let's start by hooking up our text input and the "Load Trending Terms" button. +For the text input, we'll capture the term that was entered in the input and +pass it as we trigger the Twitter container's `getResults` event. Clicking the +"Load Trending Terms" will trigger the Twitter container's `getTrends` event: ``` $( "form" ).submit(function( event ) { @@ -413,10 +413,10 @@ $( "#get_trends" ).click(function() { }); ``` -By adding a few buttons with the appropriate ID’s, we can make it possible to +By adding a few buttons with the appropriate ID's, we can make it possible to remove, collapse, expand, and refresh all results containers at once, as shown -below. For the remove button, note how we’re passing a value of `true` to the -event handler as its second argument, telling the event handler that we don’t +below. For the remove button, note how we're passing a value of `true` to the +event handler as its second argument, telling the event handler that we don't want to verify the removal of individual containers. ``` @@ -439,7 +439,7 @@ Custom events offer a new way of thinking about your code: they put the emphasis on the target of a behavior, not on the element that triggers it. If you take the time at the outset to spell out the pieces of your application, as well as the behaviors those pieces need to exhibit, custom events can provide a -powerful way for you to “talk” to those pieces, either one at a time or en +powerful way for you to "talk" to those pieces, either one at a time or en masse. Once the behaviors of a piece have been described, it becomes trivial to trigger those behaviors from anywhere, allowing for rapid creation of and experimentation with interface options. Finally, custom events can enhance code diff --git a/page/events/introduction-to-events.md b/page/events/introduction-to-events.md index b540abe9..2a59c1ac 100644 --- a/page/events/introduction-to-events.md +++ b/page/events/introduction-to-events.md @@ -8,17 +8,17 @@ attribution: ## Introduction -Web pages are all about interaction. Users perform a countless number of actions such as moving their mice over the page, clicking on elements, and typing in textboxes — all of these are examples of events. In addition to these user events, there are a slew of others that occur, like when the page is loaded, when video begins playing or is paused, etc. Whenever something interesting occurs on the page, an event is fired, meaning that the browser basically announces that something has happened. It’s this announcement that allows developers to “listen” for events and react to them appropriately. +Web pages are all about interaction. Users perform a countless number of actions such as moving their mice over the page, clicking on elements, and typing in textboxes — all of these are examples of events. In addition to these user events, there are a slew of others that occur, like when the page is loaded, when video begins playing or is paused, etc. Whenever something interesting occurs on the page, an event is fired, meaning that the browser basically announces that something has happened. It's this announcement that allows developers to "listen" for events and react to them appropriately. -## What’s a DOM event? +## What's a DOM event? -As mentioned, there are a myriad of event types, but perhaps the ones that are easiest to understand are user events, like when someone clicks on an element or types into a form. These types of events occur on an element, meaning that when a user clicks on a button for example, the button has had an event occur on it. While user interactions aren’t the only types of DOM events, they’re certainly the easiest to understand when starting out. MDN has a good reference of [available DOM events](https://developer.mozilla.org/en/DOM/DOM_event_reference). +As mentioned, there are a myriad of event types, but perhaps the ones that are easiest to understand are user events, like when someone clicks on an element or types into a form. These types of events occur on an element, meaning that when a user clicks on a button for example, the button has had an event occur on it. While user interactions aren't the only types of DOM events, they're certainly the easiest to understand when starting out. MDN has a good reference of [available DOM events](https://developer.mozilla.org/en/DOM/DOM_event_reference). ## Ways to listen for events -There are many ways to listen for events. Actions are constantly occurring on a webpage, but the developer is only notified about them if they’re *listening* for them. Listening for an event basically means you’re waiting for the browser to tell you that a specific event has occurred and then you’ll specify how the page should react. +There are many ways to listen for events. Actions are constantly occurring on a webpage, but the developer is only notified about them if they're *listening* for them. Listening for an event basically means you're waiting for the browser to tell you that a specific event has occurred and then you'll specify how the page should react. To specify to the browser what to do when an event occurs, you provide a function, also known as an *event handler*. This function is executed whenever the event occurs (or until the event is unbound). @@ -28,14 +28,14 @@ For instance, to alert a message whenever a user clicks on a button, you might w Say hello ``` -The event we want to listen to is specified by the button’s `onclick` attribute, and the event handler is the `alert` function which alerts “Hello” to the user. While this works, it’s an abysmal way to achieve this functionality for a couple of reasons: +The event we want to listen to is specified by the button's `onclick` attribute, and the event handler is the `alert` function which alerts "Hello" to the user. While this works, it's an abysmal way to achieve this functionality for a couple of reasons: -1. First, we’re coupling our view code (HTML) with our interaction code (JS). That means that whenever we need to update functionality, we’d have to edit our HTML which is just a bad practice and a maintenance nightmare. -2. Second, it’s not scalable. If you had to attach this functionality onto numerous buttons, you’d not only bloat the page with a bunch of repetitious code, but you would again destroy maintainability. +1. First, we're coupling our view code (HTML) with our interaction code (JS). That means that whenever we need to update functionality, we'd have to edit our HTML which is just a bad practice and a maintenance nightmare. +2. Second, it's not scalable. If you had to attach this functionality onto numerous buttons, you'd not only bloat the page with a bunch of repetitious code, but you would again destroy maintainability. -Utilizing inline event handlers like this can be considered *obtrusive JavaScript,* but its opposite, *unobtrusive JavaScript* is a much more common way of discussing the topic. The notion of *unobtrusive JavaScript* is that your HTML and JS are kept separate and are therefore more maintainable. Separation of concerns is important because it keeps like pieces of code together (i.e. HTML, JS, CSS) and unlike pieces of code apart, facilitating changes, enhancements, etc. Furthermore, unobtrusive JavaScript stresses the importance of adding the least amount of cruft to a page as possible. If a user’s browser doesn’t support JavaScript, then it shouldn’t be intertwined into the markup of the page. Also, to prevent naming collisions, JS code should utilize a single namespace for different pieces of functionality or libraries. jQuery is a good example of this, in that the `jQuery` object/constructor (and also the `$` alias to `jQuery`) only utilizes a single global variable, and all of jQuery’s functionality is packaged into that one object. +Utilizing inline event handlers like this can be considered *obtrusive JavaScript,* but its opposite, *unobtrusive JavaScript* is a much more common way of discussing the topic. The notion of *unobtrusive JavaScript* is that your HTML and JS are kept separate and are therefore more maintainable. Separation of concerns is important because it keeps like pieces of code together (i.e. HTML, JS, CSS) and unlike pieces of code apart, facilitating changes, enhancements, etc. Furthermore, unobtrusive JavaScript stresses the importance of adding the least amount of cruft to a page as possible. If a user's browser doesn't support JavaScript, then it shouldn't be intertwined into the markup of the page. Also, to prevent naming collisions, JS code should utilize a single namespace for different pieces of functionality or libraries. jQuery is a good example of this, in that the `jQuery` object/constructor (and also the `$` alias to `jQuery`) only utilizes a single global variable, and all of jQuery's functionality is packaged into that one object. -To accomplish the desired task unobtrusively, let’s change our HTML a little bit by removing the `onclick` attribute and replacing it with an `id`, which we’ll utilize to “hook onto” the button from within a script file. +To accomplish the desired task unobtrusively, let's change our HTML a little bit by removing the `onclick` attribute and replacing it with an `id`, which we'll utilize to "hook onto" the button from within a script file. ``` Say hello @@ -52,7 +52,7 @@ helloBtn.addEventListener( "click", function( event ) { }, false ); ``` -Here we’re saving a reference to the button element by calling `getElementById` and assigning its return value to a variable. We then call `addEventListener` and provide an event handler function that will be called whenever that event occurs. While there’s nothing wrong with this code as it will work fine in modern browsers, it won’t fare well in versions of IE prior to IE9. This is because Microsoft chose to implement a different method, `attachEvent`, as opposed to the W3C standard `addEventListener`, and didn’t get around to changing it until IE9 was released. For this reason, it’s beneficial to utilize jQuery because it abstracts away browser inconsistencies, allowing developers to use a single API for these types of tasks, as seen below. +Here we're saving a reference to the button element by calling `getElementById` and assigning its return value to a variable. We then call `addEventListener` and provide an event handler function that will be called whenever that event occurs. While there's nothing wrong with this code as it will work fine in modern browsers, it won't fare well in versions of IE prior to IE9. This is because Microsoft chose to implement a different method, `attachEvent`, as opposed to the W3C standard `addEventListener`, and didn't get around to changing it until IE9 was released. For this reason, it's beneficial to utilize jQuery because it abstracts away browser inconsistencies, allowing developers to use a single API for these types of tasks, as seen below. ``` // Event binding using a convenience method @@ -61,7 +61,7 @@ $( "#helloBtn" ).click(function( event ) { }); ``` -The `$( "#helloBtn" )` code selects the button element using the `$` (a.k.a. `jQuery`) function and returns a jQuery object. The jQuery object has a bunch of methods (functions) available to it, one of them named `click`, which resides in the jQuery object’s prototype. We call the `click` method on the jQuery object and pass along an anonymous function event handler that’s going to be executed when a user clicks the button, alerting “Hello.” to the user. +The `$( "#helloBtn" )` code selects the button element using the `$` (a.k.a. `jQuery`) function and returns a jQuery object. The jQuery object has a bunch of methods (functions) available to it, one of them named `click`, which resides in the jQuery object's prototype. We call the `click` method on the jQuery object and pass along an anonymous function event handler that's going to be executed when a user clicks the button, alerting "Hello." to the user. There are a number of ways that events can be listened for using jQuery: @@ -100,22 +100,22 @@ $( "body" ).on( "click", "button", function( event ) { }); ``` -As of jQuery 1.7, all events are bound via the `on` method, whether you call it directly or whether you use an alias/shortcut method such as `bind` or `click`, which are mapped to the `on` method internally. With this in mind, it’s beneficial to use the `on` method because the others are all just syntactic sugar, and utilizing the `on` method is going to result in faster and more consistent code. +As of jQuery 1.7, all events are bound via the `on` method, whether you call it directly or whether you use an alias/shortcut method such as `bind` or `click`, which are mapped to the `on` method internally. With this in mind, it's beneficial to use the `on` method because the others are all just syntactic sugar, and utilizing the `on` method is going to result in faster and more consistent code. -Let’s look at the `on` examples from above and discuss their differences. In the first example, a string of `click` is passed as the first argument to the `on` method, and an anonymous function is passed as the second. This looks a lot like the `bind` method before it. Here, we’re attaching an event handler directly to `#helloBtn`. If there were any other buttons on the page, they wouldn’t alert “Hello” when clicked because the event is only attached to `#helloBtn`. +Let's look at the `on` examples from above and discuss their differences. In the first example, a string of `click` is passed as the first argument to the `on` method, and an anonymous function is passed as the second. This looks a lot like the `bind` method before it. Here, we're attaching an event handler directly to `#helloBtn`. If there were any other buttons on the page, they wouldn't alert "Hello" when clicked because the event is only attached to `#helloBtn`. -In the second `on` example, we’re passing an object (denoted by the curly braces `{}`), which has a property of `click` whose value is an anonymous function. The second argument to the `on` method is a jQuery selector string of `button`. While examples 1–3 are functionally equivalent, example 4 is different in that the `body` element is listening for click events that occur on *any* button element, not just `#helloBtn`. The final example above is exactly the same as the one preceding it, but instead of passing an object, we pass an event string, a selector string, and the callback. Both of these are examples of event delegation, a process by which an element higher in the DOM tree listens for events occurring on its children. +In the second `on` example, we're passing an object (denoted by the curly braces `{}`), which has a property of `click` whose value is an anonymous function. The second argument to the `on` method is a jQuery selector string of `button`. While examples 1–3 are functionally equivalent, example 4 is different in that the `body` element is listening for click events that occur on *any* button element, not just `#helloBtn`. The final example above is exactly the same as the one preceding it, but instead of passing an object, we pass an event string, a selector string, and the callback. Both of these are examples of event delegation, a process by which an element higher in the DOM tree listens for events occurring on its children. -Event delegation works because of the notion of *event bubbling*. For most events, whenever something occurs on a page (like an element is clicked), the event travels from the element it occurred on, up to its parent, then up to the parent’s parent, and so on, until it reaches the root element, a.k.a. the `window`. So in our table example, whenever a `td` is clicked, its parent `tr` would also be notified of the click, the parent `table` would be notified, the `body` would be notified, and ultimately the `window` would be notified as well. While event bubbling and delegation work well, the delegating element (in our example, the `table`) should always be as close to the delegatees as possible so the event doesn’t have to travel way up the DOM tree before its handler function is called. +Event delegation works because of the notion of *event bubbling*. For most events, whenever something occurs on a page (like an element is clicked), the event travels from the element it occurred on, up to its parent, then up to the parent's parent, and so on, until it reaches the root element, a.k.a. the `window`. So in our table example, whenever a `td` is clicked, its parent `tr` would also be notified of the click, the parent `table` would be notified, the `body` would be notified, and ultimately the `window` would be notified as well. While event bubbling and delegation work well, the delegating element (in our example, the `table`) should always be as close to the delegatees as possible so the event doesn't have to travel way up the DOM tree before its handler function is called. -The two main pros of event delegation over binding directly to an element (or set of elements) are performance and the aforementioned event bubbling. Imagine having a large table of 1,000 cells and binding to an event for each cell. That’s 1,000 separate event handlers that the browser has to attach, even if they’re all mapped to the same function. Instead of binding to each individual cell though, we could instead use delegation to listen for events that occur on the parent table and react accordingly. One event would be bound instead of 1,000, resulting in way better performance and memory management. +The two main pros of event delegation over binding directly to an element (or set of elements) are performance and the aforementioned event bubbling. Imagine having a large table of 1,000 cells and binding to an event for each cell. That's 1,000 separate event handlers that the browser has to attach, even if they're all mapped to the same function. Instead of binding to each individual cell though, we could instead use delegation to listen for events that occur on the parent table and react accordingly. One event would be bound instead of 1,000, resulting in way better performance and memory management. -The event bubbling that occurs affords us the ability to add cells via AJAX for example, without having to bind events directly to those cells since the parent table is listening for clicks and is therefore notified of clicks on its children. If we weren’t using delegation, we’d have to constantly bind events for every cell that’s added which is not only a performance issue, but could also become a maintenance nightmare. +The event bubbling that occurs affords us the ability to add cells via AJAX for example, without having to bind events directly to those cells since the parent table is listening for clicks and is therefore notified of clicks on its children. If we weren't using delegation, we'd have to constantly bind events for every cell that's added which is not only a performance issue, but could also become a maintenance nightmare. ## The event object -In all of the previous examples, we’ve been using anonymous functions and specifying an `event` argument within that function. Let’s change it up a little bit. +In all of the previous examples, we've been using anonymous functions and specifying an `event` argument within that function. Let's change it up a little bit. ``` // Binding a named function @@ -126,11 +126,11 @@ function sayHello( event ) { $( "#helloBtn" ).on( "click", sayHello ); ``` -In this slightly different example, we’re defining a function called `sayHello` and then passing that function into the `on` method instead of an anonymous function. So many online examples show anonymous functions used as event handlers, but it’s important to realize that you can also pass defined functions as event handlers as well. This is important if different elements or different events should perform the same functionality. This helps to keep your code DRY. +In this slightly different example, we're defining a function called `sayHello` and then passing that function into the `on` method instead of an anonymous function. So many online examples show anonymous functions used as event handlers, but it's important to realize that you can also pass defined functions as event handlers as well. This is important if different elements or different events should perform the same functionality. This helps to keep your code DRY. -But what about that `event` argument in the `sayHello` function — what is it and why does it matter? In all DOM event callbacks, jQuery passes an *event object* argument which contains information about the event, such as precisely when and where it occurred, what type of event it was, which element the event occurred on, and a plethora of other information. Of course you don’t have to call it `event`; you could call it `e` or whatever you want to, but `event` is a pretty common convention. +But what about that `event` argument in the `sayHello` function — what is it and why does it matter? In all DOM event callbacks, jQuery passes an *event object* argument which contains information about the event, such as precisely when and where it occurred, what type of event it was, which element the event occurred on, and a plethora of other information. Of course you don't have to call it `event`; you could call it `e` or whatever you want to, but `event` is a pretty common convention. -If the element has default functionality for a specific event (like a link opens a new page, a button in a form submits the form, etc.), that default functionality can be cancelled. This is often useful for AJAX requests. When a user clicks on a button to submit a form via AJAX, we’d want to cancel the button/form’s default action (to submit it to the form’s `action` attribute), and we would instead do an AJAX request to accomplish the same task for a more seamless experience. To do this, we would utilize the event object and call its `.preventDefault()` method. We can also prevent the event from bubbling up the DOM tree using `.stopPropagation()` so that parent elements aren’t notified of its occurrence (in the case that event delegation is being used). +If the element has default functionality for a specific event (like a link opens a new page, a button in a form submits the form, etc.), that default functionality can be cancelled. This is often useful for AJAX requests. When a user clicks on a button to submit a form via AJAX, we'd want to cancel the button/form's default action (to submit it to the form's `action` attribute), and we would instead do an AJAX request to accomplish the same task for a more seamless experience. To do this, we would utilize the event object and call its `.preventDefault()` method. We can also prevent the event from bubbling up the DOM tree using `.stopPropagation()` so that parent elements aren't notified of its occurrence (in the case that event delegation is being used). ``` // Preventing a default action from occurring and stopping the event bubbling @@ -147,11 +147,11 @@ $( "form" ).on( "submit", function( event ) { }); ``` -When utilizing both `.preventDefault()` and `.stopPropagation()` simultaneously, you can instead `return false` to achieve both in a more concise manner, but it’s advisable to only `return false` when both are actually necessary and not just for the sake of terseness. A final note on `.stopPropagation()` is that when using it in delegated events, the soonest that event bubbling can be stopped is when the event reaches the element that is delegating it. +When utilizing both `.preventDefault()` and `.stopPropagation()` simultaneously, you can instead `return false` to achieve both in a more concise manner, but it's advisable to only `return false` when both are actually necessary and not just for the sake of terseness. A final note on `.stopPropagation()` is that when using it in delegated events, the soonest that event bubbling can be stopped is when the event reaches the element that is delegating it. -It’s also important to note that the event object contains a property called `originalEvent`, which is the event object that the browser itself created. jQuery wraps this native event object with some useful methods and properties, but in some instances, you’ll need to access the original event via `event.originalEvent` for instance. This is especially useful for touch events on mobile devices and tablets. +It's also important to note that the event object contains a property called `originalEvent`, which is the event object that the browser itself created. jQuery wraps this native event object with some useful methods and properties, but in some instances, you'll need to access the original event via `event.originalEvent` for instance. This is especially useful for touch events on mobile devices and tablets. -Finally, to inspect the event itself and see all of the data it contains, you should log the event in the browser’s console using `console.log`. This will allow you to see all of an event’s properties (including the `originalEvent`) which can be really helpful for debugging. +Finally, to inspect the event itself and see all of the data it contains, you should log the event in the browser's console using `console.log`. This will allow you to see all of an event's properties (including the `originalEvent`) which can be really helpful for debugging. ``` // Logging an event's information diff --git a/page/events/triggering-event-handlers.md b/page/events/triggering-event-handlers.md index 83c56199..3ebd44fb 100644 --- a/page/events/triggering-event-handlers.md +++ b/page/events/triggering-event-handlers.md @@ -9,13 +9,13 @@ attribution: jQuery provides a way to trigger the event handlers bound to an element without any user interaction via the `.trigger()` method. -## What handlers can be .trigger()’d? +## What handlers can be .trigger()'d? -jQuery’s event handling system is a layer on top of native browser events. When an event handler is added using -`.on( "click", function() {...} )`, it can be triggered using jQuery’s `.trigger( "click" )` because jQuery stores a +jQuery's event handling system is a layer on top of native browser events. When an event handler is added using +`.on( "click", function() {...} )`, it can be triggered using jQuery's `.trigger( "click" )` because jQuery stores a reference to that handler when it is originally added. Additionally, it will trigger the JavaScript inside the `onclick` attribute. The `.trigger()` function cannot be used to mimic native browser events, such as -clicking on a file input box or an anchor tag. This is because, there is no event handler attached using jQuery’s +clicking on a file input box or an anchor tag. This is because, there is no event handler attached using jQuery's event system that corresponds to these events. ``` @@ -31,7 +31,7 @@ $( "a" ).trigger( "click" ); In order to trigger a native browser event, you have to use [document.createEventObject](http://msdn.microsoft.com/en-us/library/ie/ms536390%28v=vs.85%29.aspx) for < IE9 and [document.createEvent](https://developer.mozilla.org/en/DOM/document.createEvent) for all other browsers. Using these two APIs, you can programmatically create an event that behaves exactly as if someone has actually clicked on a file input box. The default action will happen, and the browse file dialog will display. -The jQuery UI Team created [jquery.simulate.js](https://github.com/eduardolundgren/jquery-simulate/blob/master/jquery.simulate.js) in order to simplify triggering a native browser event for use in their automated testing. Its usage is modeled after jQuery’s trigger. +The jQuery UI Team created [jquery.simulate.js](https://github.com/eduardolundgren/jquery-simulate/blob/master/jquery.simulate.js) in order to simplify triggering a native browser event for use in their automated testing. Its usage is modeled after jQuery's trigger. ``` // Triggering a native browser event using the simulate plugin @@ -52,7 +52,7 @@ There are four differences between `.trigger()` and `.triggerHandler()` For more information see the [triggerHandler documentation](http://api.jquery.com/triggerHandler) -## Don’t use `.trigger()` simply to execute specific functions +## Don't use `.trigger()` simply to execute specific functions While this method has its uses, it should not be used simply to call a function that was bound as a click handler. Instead, you should store the function you want to call in a