`. - - Keep sentences short and to the point. A good rule-of-thumb is to break up any sentence longer than 21 words into two or more seperate thoughts. - - Lists: - - Use bulleted lists when necessary to share a series of five or more points. - - Use numbered lists only when providing step-by-step instruction - note that this should be avoided. - - Use a period at the end of each ordered list item, and a period or comma at the end of an unordered list item. +- Use headings to break up content into easier-to-read sections. Begin headings within an article with `

`. +- Keep sentences short and to the point. A good rule-of-thumb is to break up any sentence longer than 21 words into two or more separate thoughts. +- Lists: + - Use bulleted lists when necessary to share a series of five or more points. + - Use numbered lists only when providing step-by-step instruction – note that this should be avoided. + - Use a period at the end of each ordered list item, and a period or comma at the end of an unordered list item. #### Spelling - - Use standard American English spelling. - - Capitalization: - - Capitalize all proper nouns. - - Do not capitalize HTML elements in code examples. - - Capitalize all words in a heading or sub-heading with the exception of article adjectives and the prepositions like "with," "of," or "to." - - Capitalize the first word in a list. - - Punctuation: - - Periods and commas go inside quotation marks. - - Avoid using semicolons. +- Use standard American English spelling. +- Capitalization: + - Capitalize all proper nouns. + - Do not capitalize HTML elements in code examples. + - Capitalize all words in a heading or sub-heading with the exception of article adjectives and the prepositions like "with," "of," or "to." + - Capitalize the first word in a list. +- Punctuation: + - Periods and commas go inside quotation marks. + - Avoid using semicolons. #### Pronoun Usage - - Don't use "I," "me," "us," "our," "we," and gender-specific pronouns such as "him" or "she." - - Use the second-person pronoun "you" when addressing the reader, and the definite article "the" when addressing code or content: - - *"You will be able to foo bar after you bar the foo."* - - *"Insert the paragraph after the unordered list."* +- Don't use "I," "me," "us," "our," "we," and gender-specific pronouns such as "him" or "she." +- Use the second-person pronoun "you" when addressing the reader, and the definite article "the" when addressing code or content: + - *"You will be able to foo bar after you bar the foo."* + - *"Insert the paragraph after the unordered list."* #### Voice & Tone - - Do write in clear, easy-to-understand statements. - - Do write in active voice. - - Do keep the audience in mind while writing. - - Do write conversationally. - - Do write in the second person to address the reader. - - Do use the imperative mood. - - Do use humor strategically. When in doubt, err on the side of formality. - - Do use hyperlinks to refer readers to concepts or topics that have been covered in other sections. - - Do attribute others. - - Don't assume the reader will have prior knowledge of topics or concepts, especially when targeting beginner or intermediate audiences. - - Don't use rhetorical questions. - - Don't write in first or third person. +- Do write in clear, easy-to-understand statements. +- Do write in active voice. +- Do keep the audience in mind while writing. +- Do write conversationally. +- Do write in the second person to address the reader. +- Do use the imperative mood. +- Do use humor strategically. When in doubt, err on the side of formality. +- Do use hyperlinks to refer readers to concepts or topics that have been covered in other sections. +- Do attribute others. +- Don't assume the reader will have prior knowledge of topics or concepts, especially when targeting beginner or intermediate audiences. +- Don't use rhetorical questions. +- Don't write in first or third person. #### Linking & Referencing Content - - Link to relevant content within the learn.jquery.com site to refer readers to previously covered topics or concepts. - - Link to the jQuery blog or API documentation when necessary. - - Use inline hyperlinks to reference relevant content. - - Acceptable external resources: - - Mozilla Developer Network - - Webplatform.org - - htmldog.com +- Link to relevant content within the learn.jquery.com site to refer readers to previously covered topics or concepts. +- Link to the jQuery blog or API documentation when necessary. +- Use inline hyperlinks to reference relevant content. +- Acceptable external resources: + - [Mozilla Developer Network](https://developer.mozilla.org/en-US/) + - [Webplatform.org](http://www.webplatform.org/) + - [htmldog.com](http://www.htmldog.com/) ### Code Examples - - Use examples to illustrate important concepts. - - Examples should indicate what the expected result will be in comments before code is presented. - - Break long examples up into shorter sections to aid comprehension. - - Favor "Right Way" examples over "Wrong Way" examples - there is more than one wrong way to do something, after all. - - Use good comments so that explanation within prose isn't necessary. - - Test your code examples before submitting. - - Use the [jQuery Core Code Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) for your code examples. +- Use examples to illustrate important concepts. +- Examples should indicate what the expected result will be in comments before code is presented. +- Break long examples up into shorter sections to aid comprehension. +- Favor "Right Way" examples over "Wrong Way" examples – there is more than one wrong way to do something, after all. +- Use good comments so that explanation within prose isn't necessary. +- Test your code examples before submitting. +- Use the [jQuery Core Code Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) for your code examples. diff --git a/page/using-jquery-core.md b/page/using-jquery-core.md index aa925283..2080731a 100644 --- a/page/using-jquery-core.md +++ b/page/using-jquery-core.md @@ -1,8 +1,10 @@ ---- -title: Using jQuery Core -level: beginner -customFields: - - - key: "icon" - value: "star-empty" ---- + diff --git a/page/using-jquery-core/attributes.md b/page/using-jquery-core/attributes.md index af75f0c4..0094e4ac 100644 --- a/page/using-jquery-core/attributes.md +++ b/page/using-jquery-core/attributes.md @@ -1,28 +1,27 @@ ---- -title : Attributes -level : beginner ---- + + An element's attributes can contain useful information for your application, so it's important to be able to get and set them. -## `$.fn.attr` +## The `.attr()` method -The `$.fn.attr` method acts as both a getter and a setter. As a setter, `$.fn.attr` can accept either a key and a value, or an object containing one or more key/value pairs. +The `.attr()` method acts as both a getter and a setter. As a setter, `.attr()` can accept either a key and a value, or an object containing one or more key/value pairs. -`$.fn.attr` as a setter: +`.attr()` as a setter: ``` -// Setting attributes -$("a").attr( "href", "allMyHrefsAreTheSameNow.html" ); +$( "a" ).attr( "href", "allMyHrefsAreTheSameNow.html" ); -$("a").attr({ - title: "all titles are the same too!", - href: "somethingNew.html" +$( "a" ).attr({ + title: "all titles are the same too!", + href: "somethingNew.html" }); ``` -`$.fn.attr` as a getter: +`.attr()` as a getter: ``` -// Getting attributes -$("a").attr("href"); // returns the href for the first a element in the document +$( "a" ).attr( "href" ); // Returns the href for the first a element in the document ``` diff --git a/page/using-jquery-core/avoid-conflicts-other-libraries.md b/page/using-jquery-core/avoid-conflicts-other-libraries.md index 5c37d1a4..caa91aac 100644 --- a/page/using-jquery-core/avoid-conflicts-other-libraries.md +++ b/page/using-jquery-core/avoid-conflicts-other-libraries.md @@ -1,170 +1,140 @@ ---- -title : Avoiding Conflicts with Other Libraries -attribution: jQuery Fundamentals -level: beginner -source: http://jqfundamentals.com/legacy -attribution: - - jQuery Fundamentals ---- - -The jQuery library and virtually all of its plugins are contained within the -`jQuery` namespace. As a general rule, global objects are stored inside the -jQuery namespace as well, so you shouldn't get a clash between jQuery and any -other library (like prototype.js, MooTools, or YUI). - -That said, there is one caveat: *by default, jQuery uses `$` as a shortcut for -`jQuery`.* Thus, if you are using another JavaScript library that uses the `$` -variable, you can run into conflicts with jQuery. In order to avoid these -conflicts, you need to put jQuery in no-conflict mode immediately after it is -loaded onto the page and before you attempt to use jQuery in your page. - -##Putting jQuery into No-Conflict Mode - -When you put jQuery into no-conflict mode, you have the option of assigning a -new variable name to replace the `$` alias. + + +The jQuery library and virtually all of its plugins are contained within the `jQuery` namespace. As a general rule, global objects are stored inside the jQuery namespace as well, so you shouldn't get a clash between jQuery and any other library (like prototype.js, MooTools, or YUI). + +That said, there is one caveat: *by default, jQuery uses `$` as a shortcut for `jQuery`.* Thus, if you are using another JavaScript library that uses the `$` variable, you can run into conflicts with jQuery. In order to avoid these conflicts, you need to put jQuery in no-conflict mode immediately after it is loaded onto the page and before you attempt to use jQuery in your page. + +## Putting jQuery Into No-Conflict Mode + +When you put jQuery into no-conflict mode, you have the option of assigning a new variable name to replace the `$` alias. ``` - + ``` -In the code above, the `$` will revert back to its meaning in original library. -You'll still be able to use the full function name `jQuery` as well as the new -alias `$j` in the rest of your application. The new alias can be named anything -you'd like: `jq`, `$J`, `awesomeQuery`, etc. +In the code above, the `$` will revert back to its meaning in original library. You'll still be able to use the full function name `jQuery` as well as the new alias `$j` in the rest of your application. The new alias can be named anything you'd like: `jq`, `$J`, `awesomeQuery`, etc. -Finally, if you don't want to define another alternative to the full `jQuery` -function name (you really like to use `$` and don't care about using the other -library's `$` method), then there's still another approach you might try: -simply add the `$` as an argument passed to your `jQuery(document).ready()` -function. This is most frequently used in the case where you still want the -benefits of really concise jQuery code, but don't want to cause conflicts with -other libraries. +Finally, if you don't want to define another alternative to the full `jQuery` function name (you really like to use `$` and don't care about using the other library's `$` method), then there's still another approach you might try: simply add the `$` as an argument passed to your `jQuery( document ).ready()` function. This is most frequently used in the case where you still want the benefits of really concise jQuery code, but don't want to cause conflicts with other libraries. ``` - + +// The $ variable in the global scope has the prototype.js meaning. +window.onload = function(){ + var mainDiv = $( "main" ); +} + ``` -This is probably the ideal solution for most of your code, considering that -there'll be less code that you'll have to change in order to achieve complete -compatibility. +This is probably the ideal solution for most of your code, considering that there'll be less code that you'll have to change in order to achieve complete compatibility. -##Including jQuery Before Other Libraries +## Including jQuery Before Other Libraries -The code snippets above rely on jQuery being loaded after prototype.js is -loaded. If you include jQuery before other libraries, you may use `jQuery` when -you do some work with jQuery, but the `$` will have the meaning defined in the -other library. There is no need to relinquish the `$` alias by calling -`jQuery.noConflict()`. +The code snippets above rely on jQuery being loaded after prototype.js is loaded. If you include jQuery before other libraries, you may use `jQuery` when you do some work with jQuery, but the `$` will have the meaning defined in the other library. There is no need to relinquish the `$` alias by calling `jQuery.noConflict()`. ``` - + ``` -##Summary of Ways to Reference the jQuery Function +## Summary of Ways to Reference the jQuery Function -Here's a recap of ways you can reference the jQuery function when the presence -of another library creates a conflict over the use of the `$` variable: +Here's a recap of ways you can reference the jQuery function when the presence of another library creates a conflict over the use of the `$` variable: -###Create a New Alias +### Create a New Alias -The `jQuery.noConflict()` method returns a reference to the jQuery function, so -you can capture it in whatever variable you'd like: +The `jQuery.noConflict()` method returns a reference to the jQuery function, so you can capture it in whatever variable you'd like: ``` ``` -###Use an Immediately Invoked Function Expression +### Use an Immediately Invoked Function Expression -You can continue to use the standard `$` by wrapping your code in an -immediately invoked function expression; this is also a standard pattern for -jQuery plugin authoring, where the author cannot know whether another library -will have taken over the `$`. See the [Plugins](/plugins) section for more -information about writing plugins. +You can continue to use the standard `$` by wrapping your code in an immediately invoked function expression; this is also a standard pattern for jQuery plugin authoring, where the author cannot know whether another library will have taken over the `$`. See the [Plugins](/plugins/) section for more information about writing plugins. ``` - + ``` -Note that if you use this technique, you will not be able to use prototype.js -methods inside the immediately invoked function that expect `$` to be -prototype.js's `$`. +Note that if you use this technique, you will not be able to use prototype.js methods inside the immediately invoked function. `$` will be a reference to jQuery, not prototype.js. -###Use the Argument That's Passed to the `jQuery(document).ready()` Function +### Use the Argument That's Passed to the `jQuery( document ).ready()` Function ``` ``` @@ -176,9 +146,9 @@ Or using the more concise syntax for the DOM ready function: ``` diff --git a/page/using-jquery-core/css-styling-dimensions.md b/page/using-jquery-core/css-styling-dimensions.md index 6be6fa90..7e980694 100644 --- a/page/using-jquery-core/css-styling-dimensions.md +++ b/page/using-jquery-core/css-styling-dimensions.md @@ -1,45 +1,52 @@ ---- -title : CSS, Styling, & Dimensions -level: beginner ---- + + jQuery includes a handy way to get and set CSS properties of elements: ``` -// Getting CSS properties -$("h1").css("fontSize"); // returns a string such as "19px" -$("h1").css("font-size"); // also works +// Getting CSS properties. + +$( "h1" ).css( "fontSize" ); // Returns a string such as "19px". + +$( "h1" ).css( "font-size" ); // Also works. ``` ``` -// Setting CSS properties -$("h1").css( "fontSize", "100px" ); // setting an individual property +// Setting CSS properties. -// setting multiple properties -$("h1").css({ - fontSize: "100px", - color: "red" +$( "h1" ).css( "fontSize", "100px" ); // Setting an individual property. + +// Setting multiple properties. +$( "h1" ).css({ + fontSize: "100px", + color: "red" }); ``` -Note the style of the argument on the second line — it is an object that contains multiple properties. This is a common way to pass multiple arguments to a function, and many jQuery setter methods accept objects to set mulitple values at once. +Note the style of the argument on the second line – it is an object that contains multiple properties. This is a common way to pass multiple arguments to a function, and many jQuery setter methods accept objects to set multiple values at once. -CSS properties that normally include a hyphen need to be camelCased in JavaScript. For example, the CSS property `font-size` is expressed as `fontSize` when used as a property name in JavaScript. However, this does not apply when passing the name of a CSS property to the `$.fn.css()` method as a string — in that case, either the camelCased or hyphenated form will work. +CSS properties that normally include a hyphen need to be camelCased in JavaScript. For example, the CSS property `font-size` is expressed as `fontSize` when used as a property name in JavaScript. However, this does not apply when passing the name of a CSS property to the `.css()` method as a string – in that case, either the camelCased or hyphenated form will work. -It's not recommended to use `$.fn.css()` as a setter in production-ready code, but when passing in an object to set CSS, CSS properties will be camelCased instead of using a hypen. +It's not recommended to use `.css()` as a setter in production-ready code, but when passing in an object to set CSS, CSS properties will be camelCased instead of using a hyphen. ## Using CSS Classes for Styling -As a getter, the `$.fn.css()` method is valuable. However, it should generally be avoided as a setter in production-ready code, because it's generally best to keep presentational information out of JavaScript code. Instead, write CSS rules for classes that describe the various visual states, and then change the class on the element. +As a getter, the `.css()` method is valuable. However, it should generally be avoided as a setter in production-ready code, because it's generally best to keep presentational information out of JavaScript code. Instead, write CSS rules for classes that describe the various visual states, and then change the class on the element. ``` -// Working with classes -var $h1 = $("h1"); +// Working with classes. + +var h1 = $( "h1" ); -$h1.addClass("big"); -$h1.removeClass("big"); -$h1.toggleClass("big"); +h1.addClass( "big" ); +h1.removeClass( "big" ); +h1.toggleClass( "big" ); -if ( $h1.hasClass("big") ) { ... } +if ( h1.hasClass( "big" ) ) { + ... +} ``` Classes can also be useful for storing state information about an element, such as indicating that an element is selected. @@ -51,24 +58,22 @@ jQuery offers a variety of methods for obtaining and modifying dimension and pos The code below shows a brief overview of the dimensions functionality in jQuery. For complete details about jQuery dimension methods, visit the [dimensions documentation on api.jquery.com](http://api.jquery.com/category/dimensions/). ``` -// Basic dimensions methods - -// sets the width of all H1 elements -$("h1").width("50px"); -// gets the width of the first H1 -$("h1").width(); +// Basic dimensions methods. +// Sets the width of all

elements. +$( "h1" ).width( "50px" ); -// sets the height of all H1 elements -$("h1").height("50px"); +// Gets the width of the first

element. +$( "h1" ).width(); -// gets the height of the first H1 -$("h1").height(); +// Sets the height of all

elements. +$( "h1" ).height( "50px" ); +// Gets the height of the first

element. +$( "h1" ).height(); -// returns an object containing position -// information for the first H1 relative to -// its "offset (positioned) parent" -$("h1").position(); +// Returns an object containing position information for +// the first

relative to its "offset (positioned) parent". +$( "h1" ).position(); ``` diff --git a/page/using-jquery-core/data-methods.md b/page/using-jquery-core/data-methods.md index b218f5b9..33500e3d 100644 --- a/page/using-jquery-core/data-methods.md +++ b/page/using-jquery-core/data-methods.md @@ -1,40 +1,41 @@ ---- -title : Data Methods -level: intermediate -source: http://jqfundamentals.com/legacy -attribution: - - jQuery Fundamentals ---- + + There's often data about an element you want to store with the element. In plain JavaScript, you might do this by adding a property to the DOM element, but you'd have to deal with memory leaks in some browsers. jQuery offers a straightforward way to store data related to an element, and it manages the memory issues for you. ``` -// Storing and retrieving data related to an element -$("#myDiv").data( "keyName", { foo: "bar" } ); +// Storing and retrieving data related to an element. + +$( "#myDiv" ).data( "keyName", { foo: "bar" } ); -// { foo: "bar" } -$("#myDiv").data("keyName"); +$( "#myDiv" ).data( "keyName" ); // Returns { foo: "bar" } ``` -Any kind of data can be stored on an element. For the purposes of this article, `$.fn.data` will be used to store references to other elements. +Any kind of data can be stored on an element. For the purposes of this article, `.data()` will be used to store references to other elements. -For example, you may want to establish a relationship between a list item and a `

` that's inside of it. This relationship could be established every single time the list item is touched, but a better solution would be to establish the relationship once, then store a pointer to the `

` on the list item using `$.fn.data`: +For example, you may want to establish a relationship between a list item and a `

` that's inside of it. This relationship could be established every single time the list item is touched, but a better solution would be to establish the relationship once, then store a pointer to the `

` on the list item using `.data()`: ``` -// Storing a relationship between elements using $.fn.data -$("#myList li").each(function() { +// Storing a relationship between elements using .data() + +$( "#myList li" ).each(function() { - var $li = $( this ); - var $div = $li.find("div.content"); + var li = $( this ); + var div = li.find( "div.content" ); - $li.data( "contentDiv", $div ); + li.data( "contentDiv", div ); }); -// later, we don't have to find the div again; +// Later, we don't have to find the div again; // we can just read it from the list item's data -var $firstLi = $("#myList li:first"); +var firstLi = $( "#myList li:first" ); -$firstLi.data("contentDiv").html("new content"); +firstLi.data( "contentDiv" ).html( "new content" ); ``` -In addition to passing `$.fn.data` a single key-value pair to store data, you can also pass an object containing one or more pairs. +In addition to passing `.data()` a single key-value pair to store data, you can also pass an object containing one or more pairs. diff --git a/page/using-jquery-core/document-ready.md b/page/using-jquery-core/document-ready.md index bf11c8b6..2ae07cc5 100644 --- a/page/using-jquery-core/document-ready.md +++ b/page/using-jquery-core/document-ready.md @@ -1,56 +1,60 @@ ---- -title : $( document ).ready() -level: beginner ---- -A page can't be manipulated safely until the document is “ready.” jQuery detects this state of readiness for you. Code included inside `$( document ).ready()` will only run once the page DOM (Document Object Model) is ready for JavaScript code to execute. Code included inside `$( window ).load(function(){ ... })` will run once the entire page (images or iframes), not just the DOM, is ready. + + +A page can't be manipulated safely until the document is "ready." jQuery detects this state of readiness for you. Code included inside `$( document ).ready()` will only run once the page Document Object Model (DOM) is ready for JavaScript code to execute. Code included inside `$( window ).on( "load", function() { ... })` will run once the entire page (images or iframes), not just the DOM, is ready. ``` -// A $( document ).ready() block +// A $( document ).ready() block. $( document ).ready(function() { - console.log("ready!"); + console.log( "ready!" ); }); ``` -Experienced developers sometimes use shorthand for `$( document ).ready()`. If you are writing code that people who aren't experienced with jQuery may see, it's best to use the long form. +Experienced developers sometimes use the shorthand `$()` for `$( document ).ready()`. If you are writing code that people who aren't experienced with jQuery may see, it's best to use the long form. ``` // Shorthand for $( document ).ready() $(function() { - console.log("ready!"); + console.log( "ready!" ); }); ``` You can also pass a named function to `$( document ).ready()` instead of passing an anonymous function. ``` -// Passing a named function instead of an anonymous function +// Passing a named function instead of an anonymous function. function readyFn( jQuery ) { - // code to run when the document is ready + // Code to run when the document is ready. } $( document ).ready( readyFn ); -// OR -$( window ).load( readyFn ); +// or: +$( window ).on( "load", readyFn ); ``` -The below example shows `$( document ).ready()` and `$( window ).load()` in action. The code tries to load a website url in an iframe and checks for both events: +The example below shows `$( document ).ready()` and `$( window ).on( "load" )` in action. The code tries to load a website URL in an ` - + + + + + + + ``` + +To learn more about `.ready()` method, you can read [the relevant documenation page](https://api.jquery.com/ready/). diff --git a/page/using-jquery-core/dollar-object-vs-function.md b/page/using-jquery-core/dollar-object-vs-function.md index a4409681..44763197 100644 --- a/page/using-jquery-core/dollar-object-vs-function.md +++ b/page/using-jquery-core/dollar-object-vs-function.md @@ -1,34 +1,25 @@ ---- -title : $ vs $() -level: beginner -source: http://jqfundamentals.com/legacy -attribution: - - jQuery Fundamentals ---- -Until now, we’ve been dealing entirely with methods that are called on a jQuery -object. For example: + + +Until now, we've been dealing entirely with methods that are called on a jQuery object. For example: ``` -$("h1").remove(); +$( "h1" ).remove(); ``` -Most jQuery methods are called on jQuery objects as shown above; these methods -are said to be part of the `$.fn` namespace, or the “jQuery prototype,” and are -best thought of as jQuery object methods. +Most jQuery methods are called on jQuery objects as shown above; these methods are said to be part of the `$.fn` namespace, or the "jQuery prototype," and are best thought of as jQuery object methods. + +However, there are several methods that do not act on a selection; these methods are said to be part of the jQuery namespace, and are best thought of as core jQuery methods. -However, there are several methods that do not act on a selection; these -methods are said to be part of the jQuery namespace, and are best thought of as -core jQuery methods. +This distinction can be incredibly confusing to new jQuery users. Here's what you need to remember: -This distinction can be incredibly confusing to new jQuery users. Here’s what -you need to remember: +* Methods called on jQuery selections are in the `$.fn` namespace, and automatically receive and return the selection as `this`. +* Methods in the `$` namespace are generally utility-type methods, and do not work with selections; they are not automatically passed any arguments, and their return value will vary. -* Methods called on jQuery selections are in the `$.fn` namespace, and - automatically receive and return the selection as this. -* Methods in the $ namespace are generally utility-type methods, and do not - work with selections; they are not automatically passed any arguments, and - their return value will vary. +There are a few cases where object methods and core methods have the same names, such as `$.each()` and `.each()`. In these cases, be extremely careful when reading the documentation that you are exploring the correct method. -There are a few cases where object methods and core methods have the same -names, such as `$.each` and `$.fn.each`. In these cases, be extremely careful -when reading the documentation that you are exploring the correct method. +In this guide, if a method can be called on a jQuery selection, we'll refer to it just by its name: `.each()`. If it is a [utility method](/using-jquery-core/utility-methods/) -- that is, a method that isn't called on a selection -- we'll refer to it explicitly as a method in the jQuery namespace: `$.each()`. diff --git a/page/using-jquery-core/faq.md b/page/using-jquery-core/faq.md index b1b15bff..2e754bd6 100644 --- a/page/using-jquery-core/faq.md +++ b/page/using-jquery-core/faq.md @@ -1,8 +1,10 @@ ---- -title: Frequently Asked Questions -level: beginner -customFields: - - - key: "icon" - value: "question-sign" ---- + diff --git a/page/using-jquery-core/faq/how-do-i-check-uncheck-a-checkbox-input-or-radio-button.md b/page/using-jquery-core/faq/how-do-i-check-uncheck-a-checkbox-input-or-radio-button.md index 63066159..e6a6f6b5 100644 --- a/page/using-jquery-core/faq/how-do-i-check-uncheck-a-checkbox-input-or-radio-button.md +++ b/page/using-jquery-core/faq/how-do-i-check-uncheck-a-checkbox-input-or-radio-button.md @@ -1,14 +1,13 @@ ---- -title: How do I check/uncheck a checkbox input or radio button? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + You can check or uncheck a checkbox element or a radio button using the `.prop()` method: ``` // Check #x -$("#x").prop( "checked", true ); +$( "#x" ).prop( "checked", true ); // Uncheck #x -$("#x").prop( "checked", false ); -``` \ No newline at end of file +$( "#x" ).prop( "checked", false ); +``` diff --git a/page/using-jquery-core/faq/how-do-i-determine-the-state-of-a-toggled-element.md b/page/using-jquery-core/faq/how-do-i-determine-the-state-of-a-toggled-element.md index 162b2489..718df5e2 100644 --- a/page/using-jquery-core/faq/how-do-i-determine-the-state-of-a-toggled-element.md +++ b/page/using-jquery-core/faq/how-do-i-determine-the-state-of-a-toggled-element.md @@ -1,20 +1,21 @@ ---- -title: How do I determine the state of a toggled element? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + -You can determine whether an element is collapsed or not by using the :visible and :hidden selectors. +You can determine whether an element is collapsed or not by using the `:visible` and `:hidden` selectors. ``` -var isVisible = $("#myDiv").is(":visible"); +var isVisible = $( "#myDiv" ).is( ":visible" ); -var isHidden = $("#myDiv").is(":hidden"); +var isHidden = $( "#myDiv" ).is( ":hidden" ); ``` -If you're simply acting on an element based on its visibility, just include ":visible" or ":hidden" in the selector expression. For example: +If you're simply acting on an element based on its visibility, just include `:visible` or `:hidden` in the selector expression. For example: ``` -$("#myDiv:visible").animate({ - left: "+=200px" +$( "#myDiv:visible" ).animate({ + + left: "+=200px" + }, "slow" ); ``` diff --git a/page/using-jquery-core/faq/how-do-i-disable-enable-a-form-element.md b/page/using-jquery-core/faq/how-do-i-disable-enable-a-form-element.md index 02b11096..9ab3afa5 100644 --- a/page/using-jquery-core/faq/how-do-i-disable-enable-a-form-element.md +++ b/page/using-jquery-core/faq/how-do-i-disable-enable-a-form-element.md @@ -1,14 +1,13 @@ ---- -title: How do I disable/enable a form element? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + You can enable or disable a form element using the `.prop()` method: ``` // Disable #x -$("#x").prop( "disabled", true ); +$( "#x" ).prop( "disabled", true ); // Enable #x -$("#x").prop( "disabled", false ); -``` \ No newline at end of file +$( "#x" ).prop( "disabled", false ); +``` diff --git a/page/using-jquery-core/faq/how-do-i-get-the-text-value-of-a-selected-option.md b/page/using-jquery-core/faq/how-do-i-get-the-text-value-of-a-selected-option.md index ae14d8b5..b98cd07e 100644 --- a/page/using-jquery-core/faq/how-do-i-get-the-text-value-of-a-selected-option.md +++ b/page/using-jquery-core/faq/how-do-i-get-the-text-value-of-a-selected-option.md @@ -1,12 +1,11 @@ ---- -title: How do I get the text value of a selected option? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + Select elements typically have two values that you want to access. First there's the value to be sent to the server, which is easy: ``` -$("#myselect").val(); +$( "#myselect" ).val(); // => 1 ``` @@ -14,17 +13,17 @@ The second is the text value of the select. For example, using the following sel ``` - Mr - Mrs - Ms - Dr - Prof + Mr + Mrs + Ms + Dr + Prof ``` -If you wanted to get the string "Mr" if the first option was selected (instead of just "1"), you would do that in the following way: +If you wanted to get the string "Mr" if the first option was selected (instead of just "1") you would do that in the following way: ``` -$("#myselect option:selected").text(); +$( "#myselect option:selected" ).text(); // => "Mr" -``` \ No newline at end of file +``` diff --git a/page/using-jquery-core/faq/how-do-i-pull-a-native-dom-element-from-a-jquery-object.md b/page/using-jquery-core/faq/how-do-i-pull-a-native-dom-element-from-a-jquery-object.md index c43ea864..e4ba9e95 100644 --- a/page/using-jquery-core/faq/how-do-i-pull-a-native-dom-element-from-a-jquery-object.md +++ b/page/using-jquery-core/faq/how-do-i-pull-a-native-dom-element-from-a-jquery-object.md @@ -1,18 +1,17 @@ ---- -title: How do I pull a native DOM element from a jQuery object? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + A jQuery object is an array-like wrapper around one or more DOM elements. To get a reference to the actual DOM elements (instead of the jQuery object), you have two options. The first (and fastest) method is to use array notation: ``` -$("#foo")[ 0 ]; // equivalent to document.getElementById("foo") +$( "#foo" )[ 0 ]; // Equivalent to document.getElementById( "foo" ) ``` -The second method is to use the [get](http://api.jquery.com/get/) function: +The second method is to use the [.get()](http://api.jquery.com/get/) function: ``` -$("#foo").get( 0 ); // identical to above, only slower +$( "#foo" ).get( 0 ); // Identical to above, only slower. ``` -You can also call [get](http://api.jquery.com/get/) without any arguments to retrieve a true array of DOM elements. \ No newline at end of file +You can also call [.get()](http://api.jquery.com/get/) without any arguments to retrieve a true array of DOM elements. diff --git a/page/using-jquery-core/faq/how-do-i-replace-text-from-the-3rd-element-of-a-list-of-10-items.md b/page/using-jquery-core/faq/how-do-i-replace-text-from-the-3rd-element-of-a-list-of-10-items.md index 1e2c4110..02fe3e92 100644 --- a/page/using-jquery-core/faq/how-do-i-replace-text-from-the-3rd-element-of-a-list-of-10-items.md +++ b/page/using-jquery-core/faq/how-do-i-replace-text-from-the-3rd-element-of-a-list-of-10-items.md @@ -1,20 +1,19 @@ ---- -title: How do I replace text from the 3rd element of a list of 10 items? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + -Either the :eq() selector or the .eq() method will allow you to select the proper item. However, to replace the text, you must get the value before you set it: +Either the `:eq()` selector or the `.eq()` method will allow you to select the proper item. However, to replace the text, you must get the value before you set it: ``` -// This doesn"t work; text() returns a string, not the jQuery object -$( this ).find("li a").eq( 2 ).text().replace( "foo", "bar" ); +// This doesn't work; text() returns a string, not the jQuery object: +$( this ).find( "li a" ).eq( 2 ).text().replace( "foo", "bar" ); -// This works -var $thirdLink = $( this ).find("li a").eq( 2 ); +// This works: +var thirdLink = $( this ).find( "li a" ).eq( 2 ); -var linkText = $thirdLink.text().replace( "foo", "bar" ); +var linkText = thirdLink.text().replace( "foo", "bar" ); -$thirdLink.text( linkText ); +thirdLink.text( linkText ); ``` -The first example just discards the modified text. The second example saves the modified text and then replaces the old text with the new modified text. Remember, .text() gets; .text("foo") sets. \ No newline at end of file +The first example just discards the modified text. The second example saves the modified text and then replaces the old text with the new modified text. Remember, `.text()` gets; `.text( "foo" )` sets. diff --git a/page/using-jquery-core/faq/how-do-i-select-an-element-by-an-id-that-has-characters-used-in-css-notation.md b/page/using-jquery-core/faq/how-do-i-select-an-element-by-an-id-that-has-characters-used-in-css-notation.md index 7dd0c9bf..36f533f0 100644 --- a/page/using-jquery-core/faq/how-do-i-select-an-element-by-an-id-that-has-characters-used-in-css-notation.md +++ b/page/using-jquery-core/faq/how-do-i-select-an-element-by-an-id-that-has-characters-used-in-css-notation.md @@ -1,32 +1,31 @@ ---- -title: How do I select an element by an ID that has characters used in CSS notation? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + -Because jQuery uses CSS syntax for selecting elements, some characters are interpreted as CSS notation. For example, ID attributes, after an initial letter (a-z or A-Z), may also use periods and colons, in addition to letters, numbers, hyphens, and underscores (see [W3C Basic HTML Data Types](http://www.w3.org/TR/html4/types.html#type-id)). The colon (":") and period (".") are problematic within the context of a jQuery selector because they indicate a pseudo-class and class, respectively. - -In order to tell jQuery to treat these characters literally rather than as CSS notation, they must be "escaped" by placing two backslashes in front of them. +Because jQuery uses CSS syntax for selecting elements, some characters are interpreted as CSS notation. In order to tell jQuery to treat these characters literally rather than as CSS notation, they must be escaped by placing two backslashes in front of them. See the [Selector documentation](http://api.jquery.com/category/selectors/) for further details. ``` -// Does not work -$("#some:id") +// Does not work: +$( "#some:id" ) // Works! -$("#some\\:id") +$( "#some\\:id" ) -// Does not work -$("#some.id") +// Does not work: +$( "#some.id" ) // Works! -$("#some\\.id") +$( "#some\\.id" ) ``` -The following function takes care of escaping these characters and places a "#" at the beginning of the ID string: +On jQuery version 3.0 or later, the function [jQuery.escapeSelector()](https://api.jquery.com/jQuery.escapeSelector/) should be used to escape such selectors. + +Otherwise, the following function takes care of escaping these characters and places a "#" at the beginning of the ID string for convenience: ``` -function jq( myid ) { +function escapeSelector( myid ) { - return "#" + myid.replace( /(:|\.)/g, "\\$1" ); + return "#" + myid.replace( /(\/|:|\.|\[|\]|,|=|@)/g, "\\$1" ); } ``` @@ -34,5 +33,5 @@ function jq( myid ) { The function can be used like so: ``` -$( jq("some.id") ) -``` \ No newline at end of file +$( escapeSelector( "some.id" ) ) +``` diff --git a/page/using-jquery-core/faq/how-do-i-select-an-item-using-class-or-id.md b/page/using-jquery-core/faq/how-do-i-select-an-item-using-class-or-id.md index 5f635a3e..aad1bb1d 100644 --- a/page/using-jquery-core/faq/how-do-i-select-an-item-using-class-or-id.md +++ b/page/using-jquery-core/faq/how-do-i-select-an-item-using-class-or-id.md @@ -1,35 +1,34 @@ ---- -title: How do I select an item using class or ID? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + This code selects an element with an ID of "myDivId". Since IDs are unique, this expression always selects either zero or one elements depending upon whether or not an element with the specified ID exists. ``` -$("#myDivId") +$( "#myDivId" ); ``` This code selects an element with a class of "myCssClass". Since any number of elements can have the same class, this expression will select any number of elements. ``` -$(".myCssClass") +$( ".myCssClass" ); ``` A jQuery object containing the selected element can be assigned to a JavaScript variable like normal: ``` -var myDivElement = $("#myDivId"); +var myDivElement = $( "#myDivId" ); ``` Usually, elements in a jQuery object are acted on by other jQuery functions: ``` -var myValue = $("#myDivId").val(); // get the value of a form input +var myValue = $( "#myDivId" ).val(); // Get the value of a form input. -$("#myDivId").val("hello world"); // set the value of a form input +$( "#myDivId" ).val( "hello world" ); // Set the value of a form input. ``` ### Related Articles * [Selecting Elements](/using-jquery-core/selecting-elements/) -* [Working with Selections](/using-jquery-core/working-with-selections/) \ No newline at end of file +* [Working with Selections](/using-jquery-core/working-with-selections/) diff --git a/page/using-jquery-core/faq/how-do-i-select-elements-when-i-already-have-a-dom-element.md b/page/using-jquery-core/faq/how-do-i-select-elements-when-i-already-have-a-dom-element.md index aa6cb416..10490556 100644 --- a/page/using-jquery-core/faq/how-do-i-select-elements-when-i-already-have-a-dom-element.md +++ b/page/using-jquery-core/faq/how-do-i-select-elements-when-i-already-have-a-dom-element.md @@ -1,24 +1,23 @@ ---- -title: How do I select elements when I already have a DOM element? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + If you have a variable containing a DOM element, and want to select elements related to that DOM element, simply wrap it in a jQuery object. ``` -var myDomElement = document.getElementById("foo"); // a plain DOM element +var myDomElement = document.getElementById( "foo" ); // A plain DOM element. -$( myDomElement ).find("a"); // finds all anchors inside the DOM element +$( myDomElement ).find( "a" ); // Finds all anchors inside the DOM element. ``` Many people try to concatenate a DOM element or jQuery object with a CSS selector, like so: ``` -$( myDomElement + ".bar" ); // This is equivalent to $("[object HTMLElement].bar") +$( myDomElement + ".bar" ); // This is equivalent to $( "[object HTMLElement].bar" ); ``` Unfortunately, you cannot concatenate strings to objects. -###Related Articles +### Related Articles -* [The jQuery Object](/using-jquery-core/jquery-object/) \ No newline at end of file +* [The jQuery Object](/using-jquery-core/jquery-object/) diff --git a/page/using-jquery-core/faq/how-do-i-test-whether-an-element-exists.md b/page/using-jquery-core/faq/how-do-i-test-whether-an-element-exists.md index 4d9025fb..c6ef018e 100644 --- a/page/using-jquery-core/faq/how-do-i-test-whether-an-element-exists.md +++ b/page/using-jquery-core/faq/how-do-i-test-whether-an-element-exists.md @@ -1,14 +1,13 @@ ---- -title: How do I test whether an element exists? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + -Use the [length](http://api.jquery.com/length/) property of the jQuery collection returned by your selector: +Use the [.length](http://api.jquery.com/length/) property of the jQuery collection returned by your selector: ``` -if ( $("#myDiv").length ) { +if ( $( "#myDiv" ).length ) { - $("#myDiv").show(); + $( "#myDiv" ).show(); } ``` @@ -16,5 +15,5 @@ if ( $("#myDiv").length ) { Note that it isn't always necessary to test whether an element exists. The following code will show the element if it exists, and do nothing (with no errors) if it does not: ``` -$("#myDiv").show(); -``` \ No newline at end of file +$( "#myDiv" ).show(); +``` diff --git a/page/using-jquery-core/faq/how-do-i-test-whether-an-element-has-a-particular-class.md b/page/using-jquery-core/faq/how-do-i-test-whether-an-element-has-a-particular-class.md index 96cfd316..8ebe9e19 100644 --- a/page/using-jquery-core/faq/how-do-i-test-whether-an-element-has-a-particular-class.md +++ b/page/using-jquery-core/faq/how-do-i-test-whether-an-element-has-a-particular-class.md @@ -1,33 +1,32 @@ ---- -title: How do I test whether an element has a particular class? -source: http://docs.jquery.com/Frequently_Asked_Questions ---- + -[hasClass](http://api.jquery.com/hasClass/) (added in version 1.2) handles this common use case: +[.hasClass()](http://api.jquery.com/hasClass/) (added in version 1.2) handles this common use case: ``` -$("div").click(function() { +$( "div" ).click(function() { - if ( $( this ).hasClass("protected") ) { + if ( $( this ).hasClass( "protected" ) ) { - $( this ) - .animate({ left: -10 }) - .animate({ left: 10 }) - .animate({ left: -10 }) - .animate({ left: 10 }) - .animate({ left: 0 }); + $( this ) + .animate({ left: -10 }) + .animate({ left: 10 }) + .animate({ left: -10 }) + .animate({ left: 10 }) + .animate({ left: 0 }); - } + } }); ``` -You can also use the [is()](http://api.jquery.com/is/) method along with an appropriate selector for more advanced matching: +You can also use the [.is()](http://api.jquery.com/is/) method along with an appropriate selector for more advanced matching: ``` -if ( $("#myDiv").is(".pretty.awesome") ) { +if ( $( "#myDiv" ).is( ".pretty.awesome" ) ) { - $("#myDiv").show(); + $( "#myDiv" ).show(); } ``` @@ -35,9 +34,9 @@ if ( $("#myDiv").is(".pretty.awesome") ) { Note that this method allows you to test for other things as well. For example, you can test whether an element is hidden (by using the custom [:hidden](http://api.jquery.com/hidden-selector/) selector): ``` -if ( $("#myDiv").is(":hidden") ) { +if ( $( "#myDiv" ).is( ":hidden" ) ) { - $("#myDiv").show(); + $( "#myDiv" ).show(); } -``` \ No newline at end of file +``` diff --git a/page/using-jquery-core/iterating.md b/page/using-jquery-core/iterating.md index 1e8cea67..1e95eeff 100644 --- a/page/using-jquery-core/iterating.md +++ b/page/using-jquery-core/iterating.md @@ -1,13 +1,14 @@ ---- -title : Iterating over jQuery and non-jQuery Objects ---- -jQuery provides an object iterator utility called `$.each()` as well as a jQuery collection iterator: `.each()`. These are not interchangeable. In addition, there are a couple of helpful methods called `$.map()` and `.map()` that can shortcut one of our common iteration use cases. + + +jQuery provides an object iterator utility called `$.each()` as well as a jQuery collection iterator: `.each()`. These are not interchangeable. In addition, there are a couple of helpful methods called `$.map()` and `.map()` that can shortcut one of our common iteration use cases. ### `$.each()` -[`$.each`](http://api.jquery.com/jQuery.each/) is a generic iterator function for looping over object, arrays, and array-like objects. Plain objects are iterated via their named properties while arrays and array-like objects are iterated via their indices. +[`$.each()`](http://api.jquery.com/jQuery.each/) is a generic iterator function for looping over object, arrays, and array-like objects. Plain objects are iterated via their named properties while arrays and array-like objects are iterated via their indices. -`$.each()` is essentially a drop-in replacement of a traditional `for` or 'for-in' loop. Given: +`$.each()` is essentially a drop-in replacement of a traditional `for` or `for-in` loop. Given: ``` var sum = 0; @@ -15,64 +16,69 @@ var sum = 0; var arr = [ 1, 2, 3, 4, 5 ]; ``` -then this: +Then this: + ``` for ( var i = 0, l = arr.length; i < l; i++ ) { - sum += arr[ i ]; + sum += arr[ i ]; } console.log( sum ); // 15 ``` -can be replaced with this: +Can be replaced with this: ``` $.each( arr, function( index, value ){ - sum += value; + sum += value; }); console.log( sum ); // 15 ``` -Notice that `arr[ index ]` can't be accessed as the value is conveniently passed to the callback in `$.each()`. In addition, given: +Notice that we don't have to access `arr[ index ]` as the value is conveniently passed to the callback in `$.each()`. + +In addition, given: ``` var sum = 0; var obj = { - foo: 1, - bar: 2 + foo: 1, + bar: 2 } ``` -then this: +Then this: ``` for (var item in obj) { - sum += obj[ item ]; + sum += obj[ item ]; } console.log( sum ); // 3 ``` -can be replaced with this: +Can be replaced with this: ``` $.each( obj, function( key, value ) { - sum += value; + sum += value; }); console.log( sum ); // 3 ``` -Again, `obj[ key ]` is passed directly to the callback and thus can't be accessed. Note that `$.each()` is for plain objects, arrays, array-like objects *that are not jQuery collections*. +Again, we don't have to directly access `obj[ key ]` as the value is passed directly to the callback. + +Note that `$.each()` is for plain objects, arrays, array-like objects *that are not jQuery collections*. This would be considered incorrect: ``` -// incorrect -$.each( $("p"), function() { - // Do something +// Incorrect: +$.each( $( "p" ), function() { + // Do something }); ``` @@ -86,17 +92,17 @@ For example, given the following markup: ```

-
• Link 1
-
• Link 2
-
• Link 3
+
• Link 1
+
• Link 2
+
• Link 3

``` `.each()` may be used like so: ``` -$("li").each( function( index, element ){ - console.log( $( this ).text() ); +$( "li" ).each( function( index, element ){ + console.log( $( this ).text() ); }); // Logs the following: @@ -109,22 +115,22 @@ $("li").each( function( index, element ){ The question is often raised, "If `this` is the element, why is there a second DOM element argument passed to the callback?" -Whether intentional or inadvert, the execution context may change. When consistently using the keyword `this`, it's easy to end up confusing ourselves or other developers reading the code. Even if the execution context remains the same, it may be more readable to use the second parameter as a named parameter. For example: +Whether intentional or inadvertent, the execution context may change. When consistently using the keyword `this`, it's easy to end up confusing ourselves or other developers reading the code. Even if the execution context remains the same, it may be more readable to use the second parameter as a named parameter. For example: ``` -$("li").each( function( index, listItem ) { +$( "li" ).each( function( index, listItem ) { - this === listItem; // true + this === listItem; // true - // For example only. You probably shouldn't call $.ajax in a loop - $.ajax({ - success: function( data ) { + // For example only. You probably shouldn't call $.ajax() in a loop. + $.ajax({ + success: function( data ) { + // The context has changed. + // The "this" keyword no longer refers to listItem. + this !== listItem; // true + } + }); - // The context has changed. The 'this' keyword - // no longer refers to listItem. - this !== listItem; // true - } - }); }); ``` @@ -133,26 +139,26 @@ $("li").each( function( index, listItem ) { Many jQuery methods implicitly iterate over the entire collection, applying their behavior to each matched element. For example, this is unnecessary: ``` -$("li").each( function( index, el ) { - $( el ).addClass("newClass"); +$( "li" ).each( function( index, el ) { + $( el ).addClass( "newClass" ); }); ``` -and this is fine: +And this is fine: ``` -$("li").addClass("newClass"); +$( "li" ).addClass( "newClass" ); ``` -Each `

` in the document will have the class 'newClass' added. +Each `

` in the document will have the class "newClass" added. On the other hand, some methods do not iterate over the collection. `.each()` is required when we need to get information from the element before setting a new value. This will not work: ``` -// doesn't work: -$("input").val( $( this ).val() + "%" ); +// Doesn't work: +$( "input" ).val( $( this ).val() + "%" ); // .val() does not change the execution context, so this === window ``` @@ -160,9 +166,9 @@ $("input").val( $( this ).val() + "%" ); Rather, this is how it should be written: ``` -$("input").each( function( i, el ) { - var elem = $( el ); - elem.val( elem.val() + "%" ); +$( "input" ).each( function( i, el ) { + var elem = $( el ); + elem.val( elem.val() + "%" ); }); ``` @@ -185,26 +191,25 @@ The following is a list of methods that require `.each()`: * [`.val()`](http://api.jquery.com/val/#val1) (getter) * [`.width()`](http://api.jquery.com/width/#width1) (getter) -Note that in most cases, the 'getter' signature returns the result from the first element in a jQuery collection while the setter acts over the entire collection of matched elements. The exception to this is `.text()` where the getter signature will return a concatenated string of text from all matched elements. +Note that in most cases, the "getter" signature returns the result from the first element in a jQuery collection while the setter acts over the entire collection of matched elements. The exception to this is `.text()` where the getter signature will return a concatenated string of text from all matched elements. -In addition to a setter value, the attribute, property, css setters, and DOM insertion 'setter' methods (i.e. `.text()` and `.html()`) accept anonymous callback functions that are applied to each element in the matching set. The arguments passed to the callback are the index of the matched element within the set and the result of the 'getter' signature of the method. +In addition to a setter value, the attribute, property, CSS setters, and DOM insertion "setter" methods (i.e. `.text()` and `.html()`) accept anonymous callback functions that are applied to each element in the matching set. The arguments passed to the callback are the index of the matched element within the set and the result of the 'getter' signature of the method. For example, these are equivalent: ``` -$("input").each( function( i, el ) { - var elem = $( el ); - elem.val( elem.val() + "%" ); +$( "input" ).each( function( i, el ) { + var elem = $( el ); + elem.val( elem.val() + "%" ); }); - -$("input").val(function( index, value ) { - return value + "%"; +$( "input" ).val(function( index, value ) { + return value + "%"; }); ``` -One other thing to keep in mind with this implicit iteration is that traversal methods such as `.children()` or `.parent()` will act on each matched element in a connection, returning a combined collection of all children or parent nodes. +One other thing to keep in mind with this implicit iteration is that traversal methods such as `.children()` or `.parent()` will act on each matched element in a collection, returning a combined collection of all children or parent nodes. ### [`.map()`](http://api.jquery.com/map/) @@ -215,16 +220,16 @@ For example instead of doing this: ``` var newArr = []; -$("li").each( function() { - newArr.push( this.id ); +$( "li" ).each( function() { + newArr.push( this.id ); }); ``` We can do this: ``` -$("li").map( function(index, element) { - return this.id; +$( "li" ).map( function(index, element) { + return this.id; }).get(); ``` @@ -232,7 +237,7 @@ Notice the `.get()` chained at the end. `.map()` actually returns a jQuery-wrapp ### [`$.map`](http://api.jquery.com/jQuery.map/) -Like `$.each()` and `.each()`, there is a `$.map()` as well as `.map()`. The difference is also very similar to both `.each` methods. `$.map()` works on plain JavaScript arrays while `.map()` works on jQuery element collections. Because it's working on a plain array, `$.map()` returns a plain array and `.get()` does not need to be called — in fact, it will throw an error as it's not a native JavaScript method. +Like `$.each()` and `.each()`, there is a `$.map()` as well as `.map()`. The difference is also very similar to both `.each()` methods. `$.map()` works on plain JavaScript arrays while `.map()` works on jQuery element collections. Because it's working on a plain array, `$.map()` returns a plain array and `.get()` does not need to be called – in fact, it will throw an error as it's not a native JavaScript method. A word of warning: `$.map()` switches the order of callback arguments. This was done in order to match the native JavaScript `.map()` method made available in ECMAScript 5. @@ -246,26 +251,25 @@ For example: diff --git a/page/using-jquery-core/jquery-object.md b/page/using-jquery-core/jquery-object.md index eb99f0ff..2a5f5e5a 100644 --- a/page/using-jquery-core/jquery-object.md +++ b/page/using-jquery-core/jquery-object.md @@ -1,23 +1,24 @@ ---- -title : The jQuery Object -level : beginner ---- + + When creating new elements (or selecting existing ones), jQuery returns the elements in a collection. Many developers new to jQuery assume that this collection is an array. It has a zero-indexed sequence of DOM elements, some familiar array functions, and a `.length` property, after all. Actually, the jQuery object is more complicated than that. -## DOM and DOM elements +## DOM and DOM Elements The Document Object Model (DOM for short) is a representation of an HTML document. It may contain any number of DOM elements. At a high level, a DOM element can be thought of as a "piece" of a web page. It may contain text and/or other DOM elements. DOM elements are described by a type, such as `

`, ``, or `

`, and any number of attributes such as `src`, `href`, `class` and so on. For a more thorough description, refer to [the official DOM specification from the W3C](http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-745549614). -Elements have properties like any JavaScript object. Among these properties are attributes like `tagName` and methods like `appendChild`. These properties are the only way to interact with the web page via JavaScript. +Elements have properties like any JavaScript object. Among these properties are attributes like `.tagName` and methods like `.appendChild()`. These properties are the only way to interact with the web page via JavaScript. ## The jQuery Object It turns out that working directly with DOM elements can be awkward. The jQuery object defines [many](http://api.jquery.com/) methods to smooth out the experience for developers. Some benefits of the jQuery Object include: -*Compatibility* — The implementation of element methods varies across browser vendors and versions. The following snippet attempts to set the inner HTML of a `` element stored in `target`: +*Compatibility* – The implementation of DOM methods varies across browser vendors and versions. The following snippet attempts to set the inner HTML of a `` element stored in `target`: ``` -var target = document.getElementById("target"); +var target = document.getElementById( "target" ); target.innerHTML = "Hello World!"; ``` @@ -25,122 +26,134 @@ target.innerHTML = "Hello World!"; This works in many cases, but it will fail in most versions of Internet Explorer. In that case, the [recommended approach](http://www.quirksmode.org/dom/w3c_html.html) is to use pure DOM methods instead. By wrapping the `target` element in a jQuery object, these edge cases are taken care of, and the expected result is achieved in all supported browsers: ``` -// Setting the inner HTML with jQuery -var target = document.getElementById("target"); +// Setting the inner HTML with jQuery. + +var target = document.getElementById( "target" ); -$( target ).html("Hello World!"); +$( target ).html( "Hello World!" ); ``` -*Convenience* — There are also a lot of common DOM manipulation use cases that are awkward to accomplish with pure DOM methods. For instance, inserting an element stored in `newElement` after the `target` element requires a rather verbose DOM method: +*Convenience* – There are also a lot of common DOM manipulation use cases that are awkward to accomplish with pure DOM methods. For instance, inserting an element stored in `newElement` after the `target` element requires a rather verbose DOM method: ``` -// Inserting a new element after another with the native DOM API -var target = document.getElementById("target"); +// Inserting a new element after another with the native DOM API. -var newElement = document.createElement("div"); +var target = document.getElementById( "target" ); -target.parentNode.insertBefore( target.nextSibling, newElement ) +var newElement = document.createElement( "div" ); + +target.parentNode.insertBefore( newElement, target.nextSibling ); ``` By wrapping the `target` element in a jQuery object, the same task becomes much simpler: ``` -// Inserting a new element after another with jQuery -var target = document.getElementById("target"); +// Inserting a new element after another with jQuery. + +var target = document.getElementById( "target" ); -var newElement = document.createElement("div"); +var newElement = document.createElement( "div" ); $( target ).after( newElement ); ``` For the most part, these details are simply "gotchas" standing between you and your goals. -### Getting Elements in to the jQuery Object +### Getting Elements Into the jQuery Object When the jQuery function is invoked with a CSS selector, it will return a jQuery object wrapping any element(s) that match this selector. For instance, writing: ``` -// Selecting all 'h1' tags -var headers = $("h1"); +// Selecting all

tags. + +var headings = $( "h1" ); ``` -`headers` is now a jQuery element containing *all* the `

` tags already on the page. This can be verified by inspecting the `length` property of `headers`: +`headings` is now a jQuery object containing *all* the `

` tags already on the page. This can be verified by inspecting the `.length` property of `headings`: ``` -// Viewing the number of 'h1' tags on the page -var allHeaders = $("h1"); +// Viewing the number of

tags on the page. + +var headings = $( "h1" ); -alert( allHeaders.length ); +alert( headings.length ); ``` -If the page has more than one `

` tag, this number will be greater than one. If the page has no `

` tags, the `length` property will be zero. Checking the `length` property is a common way to ensure that the selector successfully matched one or more elements. +If the page has more than one `

` tag, this number will be greater than one. If the page has no `

` tags, the `.length` property will be zero. Checking the `.length` property is a common way to ensure that the selector successfully matched one or more elements. -If the goal is to select only the first header element, another step is required. There are a number of ways to accomplish this, but the most straight-forward is the `eq()` function. +If the goal is to select only the first heading element, another step is required. There are a number of ways to accomplish this, but the most straight-forward is the `.eq()` function. ``` -// Selecting only the first 'h1' element on the page (in a jQuery object) -var headers = $("h1"); +// Selecting only the first

element on the page (in a jQuery object) -var firstHeader = headers.eq( 0 ); +var headings = $( "h1" ); + +var firstHeading = headings.eq( 0 ); ``` -Now `firstHeader` is a jQuery object containing only the first `

` element on the page. And because `firstHeader` is a jQuery object, it has useful methods like `.html()` and `.after()`. jQuery also has a method named `.get()` which provides a related function. Instead of returning a jQuery-wrapped DOM element, it returns the DOM element itself. +Now `firstHeading` is a jQuery object containing only the first `

` element on the page. And because `firstHeading` is a jQuery object, it has useful methods like `.html()` and `.after()`. jQuery also has a method named `.get()` which provides a related function. Instead of returning a jQuery-wrapped DOM element, it returns the DOM element itself. ``` -// Selecting only the first 'h1' element on the page -var firstHeaderElem = $("h1").get( 0 ); +// Selecting only the first

element on the page. + +var firstHeadingElem = $( "h1" ).get( 0 ); ``` Alternatively, because the jQuery object is "array-like," it supports array subscripting via brackets: ``` -// Selecting only the first 'h1' element on the page (alternate approach) -var firstHeaderElem = $("h1")[ 0 ]; +// Selecting only the first

element on the page (alternate approach). + +var firstHeadingElem = $( "h1" )[ 0 ]; ``` -In either case, `firstHeaderElem` contains the native DOM element. This means it has DOM properties like `.innerHTML` and methods like `.appendChild()`, but *not* jQuery methods like `.html()` or `.after()`. The `firstHeaderElem` element is more difficult to work with, but there are certain instances that require it. One such instance is making comparisons. +In either case, `firstHeadingElem` contains the native DOM element. This means it has DOM properties like `.innerHTML` and methods like `.appendChild()`, but *not* jQuery methods like `.html()` or `.after()`. The `firstHeadingElem` element is more difficult to work with, but there are certain instances that require it. One such instance is making comparisons. ### Not All jQuery Objects are Created `===` An important detail regarding this "wrapping" behavior is that each wrapped object is unique. This is true *even if the object was created with the same selector or contain references to the exact same DOM elements*. ``` -// Creating two jQuery objects for the same element -var logo1 = $("#logo"); -var logo2 = $("#logo"); +// Creating two jQuery objects for the same element. + +var logo1 = $( "#logo" ); +var logo2 = $( "#logo" ); ``` Although `logo1` and `logo2` are created in the same way (and wrap the same DOM element), they are not the same object. For example: ``` -// Comparing jQuery objects -alert( $("#logo") === $("#logo") ); // alerts 'false' +// Comparing jQuery objects. + +alert( $( "#logo" ) === $( "#logo" ) ); // alerts "false" ``` -However, both objects contain the same DOM element. The `get` method is useful for testing if two jQuery objects have the same DOM element. +However, both objects contain the same DOM element. The `.get()` method is useful for testing if two jQuery objects have the same DOM element. ``` -// Comparing DOM elements -var logo1 = $("$logo"); +// Comparing DOM elements. + +var logo1 = $( "#logo" ); var logo1Elem = logo1.get( 0 ); -var logo2 = $("#logo"); +var logo2 = $( "#logo" ); var logo2Elem = logo2.get( 0 ); -alert( logo1Elem === logo2Elem ); // alerts 'true' +alert( logo1Elem === logo2Elem ); // alerts "true" ``` -Many developers prefix a `$` to the name of variables that contain jQuery objects in order to help differentiate. There is nothing magic about this practice — it just helps some people keep track of what different variables contain. The previous example could be re-written to follow this convention: +Many developers prefix a `$` to the name of variables that contain jQuery objects in order to help differentiate. There is nothing magic about this practice – it just helps some people keep track of what different variables contain. The previous example could be re-written to follow this convention: ``` -// Comparing DOM elements (with more readable variable names) -var $logo1 = $("#logo"); +// Comparing DOM elements (with more readable variable names). + +var $logo1 = $( "#logo" ); var logo1 = $logo1.get( 0 ); -var $logo2 = $("#logo"); +var $logo2 = $( "#logo" ); var logo2 = $logo2.get( 0 ); -alert( logo1 === logo2 ); // alerts 'true' +alert( logo1 === logo2 ); // alerts "true" ``` This code functions identically to the example above, but it is a little more clear to read. @@ -152,17 +165,19 @@ Regardless of the naming convention used, it is very important to make the disti Given a jQuery object with all the paragraph elements on the page: ``` -// Selecting all 'p' elements on the page -var allParagraphs = $("p"); +// Selecting all

elements on the page. + +var allParagraphs = $( "p" ); ``` -...one might expect that the contents will grow and shrink over time as `

` elements are added and removed from the document. jQuery objects do **not** behave in this manner. The set of elements contained within a jQuery object will not change unless explicitly modified. This means that the collection is not "live" — it does not automatically update as the document changes. If the document may have changed since the creation the jQuery object, the collection should be updated by creating a new one. It can be as easy as re-running the same selector: +…one might expect that the contents will grow and shrink over time as `

` elements are added and removed from the document. jQuery objects do **not** behave in this manner. The set of elements contained within a jQuery object will not change unless explicitly modified. This means that the collection is not "live" – it does not automatically update as the document changes. If the document may have changed since the creation of the jQuery object, the collection should be updated by creating a new one. It can be as easy as re-running the same selector: ``` -// Updating the selection -allParagraphs = $("p"); +// Updating the selection. + +allParagraphs = $( "p" ); ``` ### Wrapping Up -Although DOM elements provide all the functionality one needs to create interactive web pages, they can be a hassle to work with. The jQuery object wraps these elements to smooth out this experience and make common tasks easy. When creating or selecting elements with jQuery, the result will always be wrapped in a new jQuery object. If the situation calls for the native DOM elements, they may be accessed through the `.get()` method and/or array-style subscripting. \ No newline at end of file +Although DOM elements provide all the functionality one needs to create interactive web pages, they can be a hassle to work with. The jQuery object wraps these elements to smooth out this experience and make common tasks easy. When creating or selecting elements with jQuery, the result will always be wrapped in a new jQuery object. If the situation calls for the native DOM elements, they may be accessed through the `.get()` method and/or array-style subscripting. diff --git a/page/using-jquery-core/manipulating-elements.md b/page/using-jquery-core/manipulating-elements.md index 0fb65687..d3fe9db1 100644 --- a/page/using-jquery-core/manipulating-elements.md +++ b/page/using-jquery-core/manipulating-elements.md @@ -1,29 +1,29 @@ ---- -title : Manipulating Elements -level: beginner -source: http://jqfundamentals.com/legacy -attribution: - - jQuery Fundamentals ---- + + For complete documentation of jQuery manipulation methods, visit the [Manipulation documentation on api.jquery.com](http://api.jquery.com/category/manipulation/). -## Getting and Setting Information about Elements +## Getting and Setting Information About Elements -There are many ways to can change an existing element. Among the most common tasks is changing the inner HTML or attribute of an element. jQuery offers simple, cross-browser methods for these sorts of manipulations. You can also get information about elements using many of the same methods in their getter incarnations. For more information on getters and setters, see the [Working with Selections](/working-with-selections) section. Here are a few methods you can use to get and set information about elements: +There are many ways to change an existing element. Among the most common tasks is changing the inner HTML or attribute of an element. jQuery offers simple, cross-browser methods for these sorts of manipulations. You can also get information about elements using many of the same methods in their getter incarnations. For more information on getters and setters, see the [Working with Selections](/using-jquery-core/working-with-selections/) section. Here are a few methods you can use to get and set information about elements: - * **`$.fn.html`** - Get or set the html contents. - * **`$.fn.text`** - Get or set the text contents; HTML will be stripped. - * **`$.fn.attr`** - Get or set the value of the provided attribute. - * **`$.fn.width`** - Get or set the width in pixels of the first element in the selection as an integer. - * **`$.fn.height`** - Get or set the height in pixels of the first element in the selection as an integer. - * **`$.fn.position`** - Get an object with position information for the first element in the selection, relative to its first positioned ancestor. _This is a getter only_. - * **`$.fn.val`** - Get or set the value of form elements. +* **`.html()`** – Get or set the HTML contents. +* **`.text()`** – Get or set the text contents; HTML will be stripped. +* **`.attr()`** – Get or set the value of the provided attribute. +* **`.width()`** – Get or set the width in pixels of the first element in the selection as an integer. +* **`.height()`** – Get or set the height in pixels of the first element in the selection as an integer. +* **`.position()`** – Get an object with position information for the first element in the selection, relative to its first positioned ancestor. _This is a getter only_. +* **`.val()`** – Get or set the value of form elements. Changing things about elements is trivial, but remember that the change will affect all elements in the selection. If you just want to change one element, be sure to specify that in the selection before calling a setter method. ``` -// Changing the HTML of an element -$("#myDiv p:first").html("New first paragraph!"); +// Changing the HTML of an element. +$( "#myDiv p:first" ).html( "New first paragraph!" ); ``` ## Moving, Copying, and Removing Elements @@ -33,136 +33,130 @@ While there are a variety of ways to move elements around the DOM, there are gen * Place the selected element(s) relative to another element. * Place an element relative to the selected element(s). -For example, jQuery provides `$.fn.insertAfter` and `$.fn.after`. The `$.fn.insertAfter` method places the selected element(s) after the element that provided as an argument. The `$.fn.after` method places the element provided as an argument after the selected element. Several other methods follow this pattern: `$.fn.insertBefore` and `$.fn.before`, `$.fn.appendTo` and `$.fn.append`, and `$.fn.prependTo` and `$.fn.prepend`. +For example, jQuery provides `.insertAfter()` and `.after()`. The `.insertAfter()` method places the selected element(s) after the element provided as an argument. The `.after()` method places the element provided as an argument after the selected element. Several other methods follow this pattern: `.insertBefore()` and `.before()`, `.appendTo()` and `.append()`, and `.prependTo()` and `.prepend()`. -The method that makes the most sense will depend on what elements are selected, and whether you need to store a reference to the elements you're adding to the page. If you need to store a reference, you will always want to take the first approach — placing the selected elements relative to another element — as it returns the element(s) you're placing. In this case, `$.fn.insertAfter`, `$.fn.insertBefore`, `$.fn.appendTo`, and `$.fn.prependTo` should be the tools of choice. +The method that makes the most sense will depend on what elements are selected, and whether you need to store a reference to the elements you're adding to the page. If you need to store a reference, you will always want to take the first approach – placing the selected elements relative to another element – as it returns the element(s) you're placing. In this case, `.insertAfter()`, `.insertBefore()`, `.appendTo()`, and `.prependTo()` should be the tools of choice. ``` -// Moving elements using different approaches +// Moving elements using different approaches. -// make the first list item the last list item -var $li = $("#myList li:first").appendTo("#myList"); +// Make the first list item the last list item: +var li = $( "#myList li:first" ).appendTo( "#myList" ); -// another approach to the same problem -$("#myList").append( $("#myList li:first") ); +// Another approach to the same problem: +$( "#myList" ).append( $( "#myList li:first" ) ); -// note that there's no way to access the -// list item that we moved, as this returns -// the list itself +// Note that there's no way to access the list item +// that we moved, as this returns the list itself. ``` ## Cloning Elements -Methods such as `$.fn.appendTo` move the element, but sometimes a copy of the element is needed instead. In this case, use `$.fn.clone` first: +Methods such as `.appendTo()` move the element, but sometimes a copy of the element is needed instead. In this case, use `.clone()` first: ``` -// Making a copy of an element +// Making a copy of an element. -// copy the first list item to the end of the list -$("#myList li:first").clone().appendTo("#myList"); +// Copy the first list item to the end of the list: +$( "#myList li:first" ).clone().appendTo( "#myList" ); ``` -If you need to copy related data and events, be sure to pass `true` as an argument to `$.fn.clone`. - +If you need to copy related data and events, be sure to pass `true` as an argument to `.clone()`. ## Removing Elements -There are two ways to remove elements from the page: `$.fn.remove` and `$.fn.detach`. Use `$.fn.remove` when you want to permanently remove the selection from the page. while `$.fn.remove` does return the removed element(s), those elements will not have their associated data and events attached to them if you return them to the page. +There are two ways to remove elements from the page: `.remove()` and `.detach()`. Use `.remove()` when you want to permanently remove the selection from the page. While `.remove()` does return the removed element(s), those elements will not have their associated data and events attached to them if you return them to the page. -Use `$.fn.detach` if you need the data and events to persist. Like `$.fn.remove`, it returns the selection, but it also maintains the data and events associated with the selection, so you can restore the selection to the page at a later time. +Use `.detach()` if you need the data and events to persist. Like `.remove()`, it returns the selection, but it also maintains the data and events associated with the selection, so you can restore the selection to the page at a later time. -The `$.fn.detach` method is extremely valuable if you are doing heavy manipulation on an element. In that case, it's beneficial to `$.fn.detach` the element from the page, work on it in your code, then restore it to the page when you're done. This limits expensive "DOM touches" while maintaining the element's data and events. +The `.detach()` method is extremely valuable if you are doing heavy manipulation on an element. In that case, it's beneficial to `.detach()` the element from the page, work on it in your code, then restore it to the page when you're done. This limits expensive "DOM touches" while maintaining the element's data and events. -If you want to leave the element on the page but remove its contents, you can use `$.fn.empty` to dispose of the element's inner HTML. +If you want to leave the element on the page but remove its contents, you can use `.empty()` to dispose of the element's inner HTML. ## Creating New Elements jQuery offers a trivial and elegant way to create new elements using the same `$()` method used to make selections: ``` -// Creating new elements from an HTML string -$("

This is a new paragraph

"); - -$("

new list item

"); +// Creating new elements from an HTML string. +$( "

This is a new paragraph

" ); +$( "

new list item

" ); ``` ``` -// Creating a new element with an attribute object +// Creating a new element with an attribute object. $( "", { - html : "This is a new link", - "class" : "new", - href : "foo.html" + html: "This is a new link", + "class": "new", + href: "foo.html" }); ``` -Note that the attributes object in the second argument above, the property name class is quoted, although the property names 'text' and 'href' are not. Property names generally do not need to be quoted unless they are reserved words (as class is in this case). +Note that the attributes object in the second argument above, the property name class is quoted, although the property names `html` and `href` are not. Property names generally do not need to be quoted unless they are [reserved words](https://mathiasbynens.be/notes/reserved-keywords) (as `class` is in this case). When you create a new element, it is not immediately added to the page. There are several ways to add an element to the page once it's been created. ``` -// Getting a new element on to the page -var $myNewElement = $("

New element

"); +// Getting a new element on to the page. + +var myNewElement = $( "

New element

" ); -$myNewElement.appendTo("#content"); +myNewElement.appendTo( "#content" ); -$myNewElement.insertAfter("ul:last"); // this will remove the p from #content! +myNewElement.insertAfter( "ul:last" ); // This will remove the p from #content! -$("ul").last().after( $myNewElement.clone() ); // clone the p so now we have 2 +$( "ul" ).last().after( myNewElement.clone() ); // Clone the p so now we have two. ``` -The created element doesn't need to be stored in a variable — you can call the method to add the element to the page directly after the `$()`. However, most of the time you'll want a reference to the element you added so you won't have to select it later. +The created element doesn't need to be stored in a variable – you can call the method to add the element to the page directly after the `$()`. However, most of the time you'll want a reference to the element you added so you won't have to select it later. You can also create an element as you're adding it to the page, but note that in this case you don't get a reference to the newly created element: ``` -// Creating and adding an element to the page at the same time -$("ul").append("

list item

"); +// Creating and adding an element to the page at the same time. +$( "ul" ).append( "

list item

" ); ``` -The syntax for adding new elements to the page is easy, so it's tempting to forget that there's a huge performance cost for adding to the DOM repeatedly. If you're adding many elements to the same container, you'll want to concatenate all the html into a single string, and then append that string to the container instead of appending the elements one at a time. Use an array to gather all the pieces together, then join them into a single string for appending. +The syntax for adding new elements to the page is easy, so it's tempting to forget that there's a huge performance cost for adding to the DOM repeatedly. If you're adding many elements to the same container, you'll want to concatenate all the HTML into a single string, and then append that string to the container instead of appending the elements one at a time. Use an array to gather all the pieces together, then join them into a single string for appending: ``` var myItems = []; -var $myList = $("#myList"); +var myList = $( "#myList" ); for ( var i = 0; i < 100; i++ ) { - - myItems.push( "

item " + i + "

" ); - + myItems.push( "

item " + i + "

" ); } -$myList.append( myItems.join("") ); +myList.append( myItems.join( "" ) ); ``` ## Manipulating Attributes -jQuery's attribute manipulation capabilities are extensive. Basic changes are simple, but the `$.fn.attr` method also allows for more complex manipulations. It can either set an explicit value, or set a value using the return value of a function. When the function syntax is used, the function receives two arguments: the zero-based index of the element whose attribute is being changed, and the current value of the attribute being changed. +jQuery's attribute manipulation capabilities are extensive. Basic changes are simple, but the `.attr()` method also allows for more complex manipulations. It can either set an explicit value, or set a value using the return value of a function. When the function syntax is used, the function receives two arguments: the zero-based index of the element whose attribute is being changed, and the current value of the attribute being changed. ``` -// Manipulating a single attribute -$("#myDiv a:first").attr( "href", "newDestination.html" ); +// Manipulating a single attribute. +$( "#myDiv a:first" ).attr( "href", "newDestination.html" ); ``` ``` -// Manipulating multiple attributes -$("#myDiv a:first").attr({ - href: "newDestination.html", - rel: "super-special" +// Manipulating multiple attributes. +$( "#myDiv a:first" ).attr({ + href: "newDestination.html", + rel: "nofollow" }); ``` ``` -// Using a function to determine an attribute's new value -$("#myDiv a:first").attr({ - rel: "super-special", - href: function( idx, href ) { - return "/new/" + href; - } +// Using a function to determine an attribute's new value. +$( "#myDiv a:first" ).attr({ + rel: "nofollow", + href: function( idx, href ) { + return "/new/" + href; + } }); -$("#myDiv a:first").attr( "href", function( idx, href ) { - - return "/new/" + href; - +$( "#myDiv a:first" ).attr( "href", function( idx, href ) { + return "/new/" + href; }); ``` diff --git a/page/using-jquery-core/selecting-elements.md b/page/using-jquery-core/selecting-elements.md index 127bd850..08db0659 100644 --- a/page/using-jquery-core/selecting-elements.md +++ b/page/using-jquery-core/selecting-elements.md @@ -1,112 +1,67 @@ ---- -title : Selecting Elements -level: beginner ---- + -The most basic concept of jQuery is to “select some elements and do something with them.” jQuery supports most CSS3 selectors, as well as some non-standard selectors. For a complete selector reference, visit the [Selectors documentation on api.jquery.com](http://api.jquery.com/category/selectors/). +The most basic concept of jQuery is to "select some elements and do something with them." jQuery supports most CSS3 selectors, as well as some non-standard selectors. For a complete selector reference, visit the [Selectors documentation on api.jquery.com](http://api.jquery.com/category/selectors/). ## Selecting Elements by ID ``` -// Selecting elements by ID -$("#myId"); // note IDs must be unique per page +$( "#myId" ); // Note IDs must be unique per page. ``` ## Selecting Elements by Class Name ``` -// Selecting elements by class name -$("div.myClass"); // performance improves if you specify element type +$( ".myClass" ); ``` ## Selecting Elements by Attribute ``` -// Selecting elements by attribute -$("input[name='first_name']"); // beware, this can be very slow in older browsers +$( "input[name='first_name']" ); ``` ## Selecting Elements by Compound CSS Selector ``` -// Selecting elements by compound CSS selector -$("#contents ul.people li"); +$( "#contents ul.people li" ); ``` -## Pseudo-selectors +## Selecting Elements with a Comma-separated List of Selectors ``` -// Pseudo-selectors -$("a.external:first"); -$("tr:odd"); - -// select all input-like elements in a form (more on this below) -$("#myForm :input"); -$("div:visible"); - -// all except the first three divs -$("div:gt(2)"); - -// all currently animated divs -$("div:animated"); +$( "div.myClass, ul.people" ); ``` -**Note:** when using the `:visible` and `:hidden` pseudo-selectors, jQuery tests the actual visibility of the element, not its CSS visibility or display. jQuery looks to see if the element's physical height and width on the page are both greater than zero. - -However, this test doesn't work with `` elements. In the case of `` jQuery does check the CSS display property, and considers an element hidden if its display property is set to none. - -Elements that have not been added to the DOM will always be considered hidden, even if the CSS that would affect them would render them visible. See the [Manipulating Elements](/manipulating-elements) section to learn how to create and add elements to the DOM. - -For reference, here is the code jQuery uses to determine whether an element is visible or hidden: +## Pseudo-Selectors ``` -jQuery.expr.filters.hidden = function( elem ) { - - var width = elem.offsetWidth; - var height = elem.offsetHeight; - var skip = elem.nodeName.toLowerCase() === "tr"; - - // does the element have 0 height, 0 width, - // and it's not a ? - return width === 0 && height === 0 && !skip ? - - // then it must be hidden - true : +$( "a.external:first" ); +$( "tr:odd" ); - // but if it has width and height - // and it's not a - width > 0 && height > 0 && !skip ? +// Select all input-like elements in a form (more on this below). +$( "#myForm :input" ); +$( "div:visible" ); - // then it must be visible - false : +// All except the first three divs. +$( "div:gt(2)" ); - // if we get here, the element has width - // and height, but it's also a , - // so check its display property to - // decide whether it's hidden - jQuery.curCSS( elem, "display" ) === "none"; -}; +// All currently animated divs. +$( "div:animated" ); +``` -jQuery.expr.filters.visible = function( elem ) { +**Note:** When using the `:visible` and `:hidden` pseudo-selectors, jQuery tests the actual visibility of the element, not its CSS `visibility` or `display` properties. jQuery looks to see if the element's physical height and width on the page are both greater than zero. - return !jQuery.expr.filters.hidden( elem ); +However, this test doesn't work with `` elements. In the case of `` jQuery does check the CSS `display` property, and considers an element hidden if its `display` property is set to `none`. -}; -``` +Elements that have not been added to the DOM will always be considered hidden, even if the CSS that would affect them would render them visible. See the [Manipulating Elements](/manipulating-elements) section to learn how to create and add elements to the DOM. ## Choosing Selectors -Choosing good selectors is one way to improve JavaScript's performance. A little specificity — for example, including an element type when selecting elements by class name — can go a long way. On the other hand, too much specificity can be a bad thing. A selector such as `#myTable thead tr th.special` is overkill if a selector such as `#myTable th.special` will get the job done. +Choosing good selectors is one way to improve JavaScript's performance. Too much specificity can be a bad thing. A selector such as `#myTable thead tr th.special` is overkill if a selector such as `#myTable th.special` will get the job done. -jQuery offers many attribute-based selectors, allowing selections based on the content of arbitrary attributes using simplified regular expressions. - -``` -// find all s whose rel attribute -// ends with "thinger" -$("a[rel$='thinger']"); -``` - -While these can be useful in a pinch, they can also be extremely slow in older browsers. Wherever possible, make selections using IDs, class names, and tag names. ### Does My Selection Contain Any Elements? @@ -114,19 +69,19 @@ Once you've made a selection, you'll often want to know whether you have anythin ``` // Doesn't work! -if ( $("div.foo") ) { - ... +if ( $( "div.foo" ) ) { + ... } ``` -This won't work. When a selection is made using `$()`, an object is always returned, and objects always evaluate to true. Even if the selection doesn't contain any elements, the code inside the if statement will still run. +This won't work. When a selection is made using `$()`, an object is always returned, and objects always evaluate to `true`. Even if the selection doesn't contain any elements, the code inside the `if` statement will still run. -The best way to determine if there are any elements is to test the selection's length property, which tells you how many elements were selected. If the answer is 0, the length property will evaluate to false when used as a boolean value: +The best way to determine if there are any elements is to test the selection's `.length` property, which tells you how many elements were selected. If the answer is 0, the `.length` property will evaluate to `false` when used as a boolean value: ``` -//Testing whether a selection contains elements -if ( $("div.foo").length ) { - ... +// Testing whether a selection contains elements. +if ( $( "div.foo" ).length ) { + ... } ``` @@ -135,11 +90,9 @@ if ( $("div.foo").length ) { jQuery doesn't cache elements for you. If you've made a selection that you might need to make again, you should save the selection in a variable rather than making the selection repeatedly. ``` -var $divs = $("div"); +var divs = $( "div" ); ``` -In the example above, the variable name begins with a dollar sign. Unlike in other languages, there's nothing special about the dollar sign in JavaScript — it's just another character. Here, it's used to indicate that the variable contains a jQuery object. This practice is merely convention, and is not mandatory. - Once the selection is stored in a variable, you can call jQuery methods on the variable just like you would have called them on the original selection. A selection only fetches the elements that are on the page at the time the selection is made. If elements are added to the page later, you'll have to repeat the selection or otherwise add them to the selection stored in the variable. Stored selections don't magically update when the DOM changes. @@ -149,193 +102,78 @@ A selection only fetches the elements that are on the page at the time the selec Sometimes the selection contains more than what you're after. jQuery offers several methods for refining and filtering selections. ``` -// Refining selections -$("div.foo").has("p"); // div.foo elements that contain

tags -$("h1").not(".bar"); // h1 elements that don't have a class of bar -$("ul li").filter(".current"); // unordered list items with class of current -$("ul li").first(); // just the first unordered list item -$("ul li").eq( 5 ); // the sixth +// Refining selections. +$( "div.foo" ).has( "p" ); // div.foo elements that contain

tags +$( "h1" ).not( ".bar" ); // h1 elements that don't have a class of bar +$( "ul li" ).filter( ".current" ); // unordered list items with class of current +$( "ul li" ).first(); // just the first unordered list item +$( "ul li" ).eq( 5 ); // the sixth ``` ### Selecting Form Elements jQuery offers several pseudo-selectors that help find elements in forms. These are especially helpful because it can be difficult to distinguish between form elements based on their state or type using standard CSS selectors. -#### :button - -Using the `:button` pseudo-selector targets just the `