From 6e7a811a5049588d6e2f7ff295c314fedd748049 Mon Sep 17 00:00:00 2001 From: Anne Hawley Brett Date: Mon, 15 Jun 2015 19:58:45 -0400 Subject: [PATCH 1/2] splits into two tutorials for setup and fundamentals content changes to reflect best practices and use cases --- order.json | 3 +- page/about-jquery/how-jquery-works.md | 208 ----------------------- page/about-jquery/how-to-setup-jquery.md | 108 ++++++++++++ page/about-jquery/using-jquery.md | 155 +++++++++++++++++ 4 files changed, 265 insertions(+), 209 deletions(-) delete mode 100644 page/about-jquery/how-jquery-works.md create mode 100644 page/about-jquery/how-to-setup-jquery.md create mode 100644 page/about-jquery/using-jquery.md diff --git a/order.json b/order.json index ee998761..42d18ce2 100644 --- a/order.json +++ b/order.json @@ -4,7 +4,8 @@ "contributing", { "about-jquery": [ - "how-jquery-works", + "how-to-setup-jquery", + "using-jquery", "additional-support" ] }, diff --git a/page/about-jquery/how-jquery-works.md b/page/about-jquery/how-jquery-works.md deleted file mode 100644 index 4fbb1eab..00000000 --- a/page/about-jquery/how-jquery-works.md +++ /dev/null @@ -1,208 +0,0 @@ - - -### jQuery: The Basics - -This is a basic tutorial, designed to help you get started using jQuery. If you don't have a test page setup yet, start by creating the following HTML page: - -``` - - - - - - - - jQuery - - - - -``` - -The `src` attribute in the ` - - - -``` - -### Adding and Removing an HTML Class - -**Important:** *You must place the remaining jQuery examples inside the `ready` event so that your code executes when the document is ready to be worked on.* - -Another common task is adding or removing a class. - -First, add some style information into the `` of the document, like this: - -``` - -``` - -Next, add the [.addClass()](http://api.jquery.com/addClass/) call to the script: - -``` -$( "a" ).addClass( "test" ); -``` - -All `` elements are now bold. - -To remove an existing class, use [.removeClass()](http://api.jquery.com/removeClass/): - -``` -$( "a" ).removeClass( "test" ); -``` - -### Special Effects - -jQuery also provides some handy [effects](http://api.jquery.com/category/effects/) to help you make your web sites stand out. For example, if you create a click handler of: - -``` -$( "a" ).click(function( event ) { - - event.preventDefault(); - - $( this ).hide( "slow" ); - -}); -``` - -Then the link slowly disappears when clicked. - -## Callbacks and Functions - -Unlike many other programming languages, JavaScript enables you to freely pass functions around to be executed at a later time. A *callback* is a function that is passed as an argument to another function and is executed after its parent function has completed. Callbacks are special because they patiently wait to execute until their parent finishes. Meanwhile, the browser can be executing other functions or doing all sorts of other work. - -To use callbacks, it is important to know how to pass them into their parent function. - -### Callback *without* Arguments - -If a callback has no arguments, you can pass it in like this: - -``` -$.get( "myhtmlpage.html", myCallBack ); -``` - -When [$.get()](http://api.jquery.com/jQuery.get/) finishes getting the page `myhtmlpage.html`, it executes the `myCallBack()` function. - -* **Note:** The second parameter here is simply the function name (but *not* as a string, and without parentheses). - -### Callback *with* Arguments - -Executing callbacks with arguments can be tricky. - -#### Wrong - -This code example will ***not*** work: - -``` -$.get( "myhtmlpage.html", myCallBack( param1, param2 ) ); -``` - -The reason this fails is that the code executes `myCallBack( param1, param2 )` immediately and then passes `myCallBack()`'s *return value* as the second parameter to `$.get()`. We actually want to pass the function `myCallBack()`, not `myCallBack( param1, param2 )`'s return value (which might or might not be a function). So, how to pass in `myCallBack()` *and* include its arguments? - -#### Right - -To defer executing `myCallBack()` with its parameters, you can use an anonymous function as a wrapper. Note the use of `function() {`. The anonymous function does exactly one thing: calls `myCallBack()`, with the values of `param1` and `param2`. - -``` -$.get( "myhtmlpage.html", function() { - - myCallBack( param1, param2 ); - -}); -``` - -When `$.get()` finishes getting the page `myhtmlpage.html`, it executes the anonymous function, which executes `myCallBack( param1, param2 )`. diff --git a/page/about-jquery/how-to-setup-jquery.md b/page/about-jquery/how-to-setup-jquery.md new file mode 100644 index 00000000..92a7437b --- /dev/null +++ b/page/about-jquery/how-to-setup-jquery.md @@ -0,0 +1,108 @@ + + +### jQuery: Setup + +This is a basic tutorial, designed to help you get started using jQuery. Start by creating the following HTML page and name it `index.html`, and open it in the browser: + +``` + + + + + + + + jQuery + + + + +``` + +The `src` attribute in the first ` + + + + +``` + +The ` - +jQuery + + ``` -The `src` attribute in the first `` element must point to a copy of jQuery. Download a copy of jQuery from the [Downloading jQuery](http://jquery.com/download/) page and store the `jquery.js` file in the same directory as your HTML file. +The `src` attribute in the first `` element must point to a copy of jQuery. Download a copy of jQuery from the [Downloading jQuery](http://jquery.com/download/) page and store the `jquery.js` file in the same directory as `index.html`. *Note: When you download jQuery, the file name may contain a version number, e.g., `jquery-x.y.z.js`. Make sure to either rename this file to `jquery.js` or update the `src` attribute of the `` element to match the file name.* @@ -30,79 +30,59 @@ Create another file in the same directory called `demo.js`. The `src` attribute ### Launching Code on Document Ready -To run code as soon as the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction) is loaded and ready to be manipulated, jQuery has a statement known as the [ready event](http://api.jquery.com/ready/): +To run code as soon as the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction) is loaded and ready to be manipulated, jQuery has a statement known as the [ready method](http://api.jquery.com/ready/): ``` -$( document ).ready(function() { - +$( document ).ready( function() { // Your code here. +} ); -}); +// Or the shorthand: +$( function() { + // Document is ready! +} ); ``` For example, inside the `ready` event, you can add a click handler to the link: ``` -$( document ).ready(function() { - +$( document ).ready( function() { $( "a" ).on( "click", function popUp( event ) { - alert( "Thanks for visiting!" ); - - }); - -}); + } ); +} ); ``` -Copy the above jQuery code into your JavaScript file. Then, save your HTML file and reload the demo page in your browser. Clicking the link should now first display an alert pop-up, then continue with the browser's default behavior of navigating to http://jquery.com. +Copy the above jQuery code into `main.js`, then save `index.html` and reload the page. Clicking the link should now first display an alert pop-up, and then continue with the browser's default behavior of navigating to http://jquery.com. For `click` and most other [events](http://api.jquery.com/category/events/), you can prevent the default browser behavior by calling `event.preventDefault()` in the event handler: ``` -$( document ).ready(function() { - +$( document ).ready( function() { $( "a" ).on( "click", function customResponse( event ) { - - alert( "As you can see, the link no longer took you to jquery.com" ); - + alert( "As you can see, the link no longer took you to jquery.com." ); + event.preventDefault(); - - }); - -}); + } ); +} ); ``` -Try replacing your first snippet of jQuery code, which you previously copied into your JavaScript file, with the one above. Save the HTML file and reload the page to try it out. +Try replacing the first snippet of jQuery code, which you previously copied into `main.js`, with the one above. Save `index.html` and reload the page to try it out. -###Alternative Setups +### Alternative Setups -Commonly used shorthand for the `ready` event uses `$` to reference jQuery: - -``` -$(function() { - - $( "a" ).on("click", function raiseAlert( event ) { - - alert( "Works interchangeably!" ); - - }); - -}); -``` - -You may encounter a somewhat similar strategy of running the code in an `onload` event as opposed to using `ready`, as shown below. `onload` will wait for all assets such as images and external style sheets to be fully loaded, so it should only be used in cases where the JavaScript needs to reference values from those assets. +You may encounter a somewhat similar strategy of running the code in an `onload` method as opposed to using `ready`, as shown below. `onload` will wait for all assets such as images and external style sheets to be fully loaded, so it should only be used in cases where the JavaScript needs to reference values from those assets. ``` window.onload = function waitForIt() { - - alert( "This will typically be slower than using .ready()" ); - + alert( "This will be slower than using .ready() and is not recommended." ); }; ``` -In other cases you may want to alias the jQuery namespace to avoid potential conflicts with other JavaScript libraries that may also use `$`. The `ready` function can take an argument, so you can pass it another function that takes the jQuery global object as its argument. This provides a "private" function scope in which you can safely reference jQuery by `$`. +In other cases you may want to alias the jQuery namespace to avoid potential conflicts with other JavaScript libraries that also use `$`. The `ready` method can take an argument, so you can pass it callback function that takes the jQuery global object as its argument. This provides a "private" function scope in which you can safely reference jQuery by `$`. -```jQuery( document ).ready(function setUp( $ ) { +``` +jQuery( document ).ready( function setUp( $ ) { // Code using $ as usual goes here. -}); +} ); ``` \ No newline at end of file