` 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 `

` on the list item using `.data()`: ``` -// Storing a relationship between elements using $.fn.data +// Storing a relationship between elements using .data() $("#myList li").each(function() { var $li = $( this ); @@ -37,4 +37,4 @@ var $firstLi = $("#myList li:first"); $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/dollar-object-vs-function.md b/page/using-jquery-core/dollar-object-vs-function.md index fc462ae0..a6e40d4e 100644 --- a/page/using-jquery-core/dollar-object-vs-function.md +++ b/page/using-jquery-core/dollar-object-vs-function.md @@ -30,5 +30,10 @@ you need to remember: their return value will vary. 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 +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 -- 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/manipulating-elements.md b/page/using-jquery-core/manipulating-elements.md index 41aa9a4e..d213020e 100644 --- a/page/using-jquery-core/manipulating-elements.md +++ b/page/using-jquery-core/manipulating-elements.md @@ -11,13 +11,13 @@ For complete documentation of jQuery manipulation methods, visit the [Manipulati 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](/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. @@ -33,9 +33,9 @@ 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 that 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 @@ -53,7 +53,7 @@ $("#myList").append( $("#myList li:first") ); ## 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 @@ -62,18 +62,18 @@ Methods such as `$.fn.appendTo` move the element, but sometimes a copy of the el $("#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 @@ -110,7 +110,7 @@ $myNewElement.insertAfter("ul:last"); // this will remove the p from #content! $("ul").last().after( $myNewElement.clone() ); // clone the p so now we have 2 ``` -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: @@ -136,7 +136,7 @@ $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 diff --git a/page/using-jquery-core/traversing.md b/page/using-jquery-core/traversing.md index 7c60563e..a84beafb 100644 --- a/page/using-jquery-core/traversing.md +++ b/page/using-jquery-core/traversing.md @@ -6,7 +6,7 @@ Once you've made an initial selection with jQuery, you can traverse deeper into ## Parents -The methods for finding the parents from a selection include `$.fn.parent()`, `$.fn.parents()`, `$.fn.parentsUntil()`, and `$.fn.closest()`. +The methods for finding the parents from a selection include `.parent()`, `.parents()`, `.parentsUntil()`, and `.closest()`. ```

@@ -50,7 +50,7 @@ $("div.child").closest("div"); ## Children -The methods for finding child elements from a selection include `$.fn.children()` and `$.fn.find()`. The difference between these methods lies in how far into the child structure the selection is made. `$.fn.children()` only operates on direct child nodes, while `$.fn.find()` can traverse recursively into children, children of those children, and so on. +The methods for finding child elements from a selection include `.children()` and `.find()`. The difference between these methods lies in how far into the child structure the selection is made. `.children()` only operates on direct child nodes, while `.find()` can traverse recursively into children, children of those children, and so on. ``` // Selecting an element's direct children @@ -66,7 +66,7 @@ $("div.grandparent").find("div"); ## Siblings -The rest of the traversal methods within jQuery all deal with finding sibling selections. There are a few basic methods as far as the direction of traversal is concerned. You can find previous elements with `$.fn.prev()`, next elements with `$.fn.next()`, and both with `$.fn.siblings()`. There are also a few other methods that build onto these basic methods: `$.fn.nextAll()`, `$.fn.nextUntil()`, `$.fn.prevAll()` and `$.fn.prevUntil()`. +The rest of the traversal methods within jQuery all deal with finding sibling selections. There are a few basic methods as far as the direction of traversal is concerned. You can find previous elements with `.prev()`, next elements with `.next()`, and both with `.siblings()`. There are also a few other methods that build onto these basic methods: `.nextAll()`, `.nextUntil()`, `.prevAll()` and `.prevUntil()`. ``` // Selecting a next sibling of the selectors @@ -98,7 +98,7 @@ $("div.surrogateParent2").prevAll().first(); $("div.surrogateParent2").prevAll().last(); ``` -Use `$.fn.siblings()` to select all siblings: +Use `.siblings()` to select all siblings: ``` // Selecting an element's siblings in both directions that matches the given selector diff --git a/page/using-jquery-core/utility-methods.md b/page/using-jquery-core/utility-methods.md index 101fc515..8376bf52 100644 --- a/page/using-jquery-core/utility-methods.md +++ b/page/using-jquery-core/utility-methods.md @@ -18,7 +18,7 @@ Removes leading and trailing whitespace. $.trim(" lots of extra whitespace "); ``` -### `$.each` +### `$.each()` Iterates over arrays and objects. @@ -32,9 +32,11 @@ $.each({ foo: "bar", baz: "bim" }, function( k, v ) { }); ``` -The method `$.fn.each` is also used for iterating over a selection of elements. +The method `.each()` can be called on a selection to iterate over the +elements contained in the selection. `.each()`, not `$.each()`, should be used +for iterating over elements in a selection. -### `$.inArray` +### `$.inArray()` Returns a value's index in an array, or -1 if the value is not in the array. ``` @@ -45,7 +47,7 @@ if ( $.inArray( 4, myArray ) !== -1 ) { } ``` -### `$.extend` +### `$.extend()` Changes the properties of the first object using the properties of subsequent objects. ``` @@ -70,9 +72,9 @@ console.log( firstObject.foo ); // "bar" console.log( newObject.foo ); // "baz" ``` -### `$.proxy` +### `$.proxy()` -Returns a function that will always run in the provided scope — that is, sets the meaning of this inside the passed function to the second argument. +Returns a function that will always run in the provided scope — that is, sets the meaning of `this` inside the passed function to the second argument. ``` var myFunction = function() { diff --git a/page/using-jquery-core/working-with-selections.md b/page/using-jquery-core/working-with-selections.md index ee55061d..f91e7727 100644 --- a/page/using-jquery-core/working-with-selections.md +++ b/page/using-jquery-core/working-with-selections.md @@ -8,12 +8,12 @@ level: beginner jQuery “overloads” its methods, so the method used to set a value generally has the same name as the method used to get a value. When a method is used to set a value, it's called a setter. When a method is used to get (or read) a value, it's called a getter. Setters affect all elements in a selection. Getters get the requested value only for the first element in the selection. ``` -//The $.fn.html method used as a setter +//The .html() method used as a setter $("h1").html("hello world"); ``` ``` -// The html method used as a getter +// The .html() method used as a getter $("h1").html(); ``` @@ -44,10 +44,10 @@ $("#content") .html("new text for the third h3!"); ``` -jQuery also provides the `$.fn.end` method to get back to the original selection should you change the selection in the middle of a chain: +jQuery also provides the `.end()` method to get back to the original selection should you change the selection in the middle of a chain: ``` -Restoring your original selection using $.fn.end +Restoring your original selection using .end() $("#content") .find("h3") .eq( 2 ) @@ -57,4 +57,4 @@ $("#content") .html("new text for the first h3!"); ``` -Chaining is extraordinarily powerful, and it's a feature that many libraries have adapted since it was made popular by jQuery. However, it must be used with care — extensive chaining can make code extremely difficult to modify or debug. There is no hard-and-fast rule to how long a chain should be — just know that it's easy to get carried away. \ No newline at end of file +Chaining is extraordinarily powerful, and it's a feature that many libraries have adapted since it was made popular by jQuery. However, it must be used with care — extensive chaining can make code extremely difficult to modify or debug. There is no hard-and-fast rule to how long a chain should be — just know that it's easy to get carried away. From 96f68945556fa8cea07571c16128807530de0fe1 Mon Sep 17 00:00:00 2001 From: Markus Amalthea Magnuson Date: Fri, 17 May 2013 12:18:35 -0400 Subject: [PATCH 008/379] Style fixes to the jQuery Mobile section. Fixes #329. --- page/jquery-mobile.md | 3 +- page/jquery-mobile/getting-started.md | 92 +++++++++++++-------------- page/jquery-mobile/theme-roller.md | 61 +++++++++--------- 3 files changed, 75 insertions(+), 81 deletions(-) diff --git a/page/jquery-mobile.md b/page/jquery-mobile.md index 8c2877bd..f30e102e 100644 --- a/page/jquery-mobile.md +++ b/page/jquery-mobile.md @@ -6,5 +6,4 @@ customFields: value: "th-large" --- -jQuery Mobile is the easiest way to build sites and apps that are accessible on all popular smartphone, tablet and desktop devices. This frameworks provides a set of touch-friendly UI widgets and an AJAX-powered navigation system to support animated page transitions. - +jQuery Mobile is the easiest way to build sites and apps that are accessible on all popular smartphone, tablet, and desktop devices. This framework provides a set of touch-friendly UI widgets and an AJAX-powered navigation system to support animated page transitions. diff --git a/page/jquery-mobile/getting-started.md b/page/jquery-mobile/getting-started.md index 1f86c2ee..fc5720b6 100644 --- a/page/jquery-mobile/getting-started.md +++ b/page/jquery-mobile/getting-started.md @@ -5,76 +5,74 @@ level: Beginner jQuery Mobile provides a set of touch-friendly UI widgets and an AJAX-powered navigation system to support animated page transitions. This guide will show you how you can build your first jQuery Mobile application. -## Create a basic page template +## Create a Basic Page Template -To get started, you can simply paste the template below in your favorite text editor, save and open the document in a browser. +To get started, you can simply paste the template below in your favorite text editor, save, and open the document in a browser. -In the `head` of this template, a meta `viewport` tag sets the screen width to the pixel width of the device. References to jQuery, jQuery Mobile and the mobile theme stylesheet from the CDN add all the styles and scripts. jQuery Mobile 1.2 (1.2.0) works with versions of jQuery core from 1.7.0 to 1.8.2. +In the `` of this template, a meta `viewport` tag sets the screen width to the pixel width of the device. References to jQuery, jQuery Mobile, and the mobile theme stylesheet from the CDN add all the styles and scripts. jQuery Mobile 1.2 (1.2.0) works with versions of jQuery core from 1.7.0 to 1.8.2. -In the `body`, a div with a `data-role` of `page` is the wrapper used to delineate a page. A header bar (`data-role="header"`), a content region (`data-role="content"`) and a footer bar (`data-role="footer"`) are added inside to create a basic page (all three are optional). These `data-` attributes are HTML5 attributes used throughout jQuery Mobile to transform basic markup into an enhanced and styled widget. +In the ``, a div with a `data-role` of `page` is the wrapper used to delineate a page. A header bar (`data-role="header"`), a content region (`data-role="content"`) and a footer bar (`data-role="footer"`) are added inside to create a basic page (all three are optional). These `data-` attributes are HTML5 attributes used throughout jQuery Mobile to transform basic markup into an enhanced and styled widget. ``` - + - - My Page - - - - - - - -

My Title

- -

Hello world

- -

My Footer

- -

- - + + My Page + + + + + + +

+ +

My Title

+ +

Hello world

+ +

My Footer

+ +

+ ``` +### Add Content -### Add content +The next step is to add content inside the content container. Any standard HTML elements – headings, lists, paragraphs, etc. can be added. You can write your own custom styles to create custom layouts by adding an additional stylesheet to the `` after the jQuery Mobile stylesheet. -The next step is to add content inside the content container. Any standard HTML elements - headings, lists, paragraphs, etc can be added. You can write your own custom styles to create custom layouts by adding an additional stylesheet to the `head` after the jQuery Mobile stylesheet. - -### Make a listview +### Make a Listview jQuery Mobile includes a diverse set of common listviews that are coded as lists with a `data-role="listview"` added. Here is a simple linked list that has a role of `listview`. The `data-inset="true"` attribute makes the listview look like an inset module, while `data-filter="true"` adds a dynamic search filter. ```

``` -### Add a slider +### Add a Slider -The framework contains a full set of form elements that automatically are enhanced into touch-friendly styled widgets. Here's a slider made with the new HTML5 input type of range, no `data-role` needed. All form elements must always be properly associated with a `label` and the group of form elements be wrapped in a `form` tag. +The framework contains a full set of form elements that are automatically enhanced into touch-friendly styled widgets. Here's a slider made with the new HTML5 input type of range, no `data-role` needed. All form elements must always be properly associated with a `` and the group of form elements be wrapped in a ` ``` -### Make a button +### Make a Button There are a few ways to make buttons. A common one is to turn a link into a button so it's easy to click. Just start with a link and add a `data-role="button"` attribute to it. You can add an icon with the `data-icon` attribute and optionally set its position with the `data-iconpos` attribute. @@ -82,9 +80,9 @@ There are a few ways to make buttons. A common one is to turn a link into a butt Star button ``` -### Choose a theme swatch +### Choose a Theme Swatch -jQuery Mobile has a robust theme framework that supports up to 26 sets of toolbar, content and button colors, called a "swatch". You can add a `data-theme="e"` attribute to any of the widgets on this page: page, header, list, input for the slider, or button to turn it yellow. Different swatch letters in default theme from a-e can be used to mix and match swatches. +jQuery Mobile has a robust theme framework that supports up to 26 sets of toolbar, content, and button colors, called a "swatch". You can add a `data-theme="e"` attribute to any of the widgets on this page: page, header, list, input for the slider, or button to turn it yellow. Different swatch letters from a-e in the default theme can be used to mix and match swatches. If you add the theme swatch to the page, all the widgets inside the content will automatically inherit the theme (headers and footers don't inherit and default to swatch "a"). @@ -94,7 +92,7 @@ If you add the theme swatch to the page, all the widgets inside the content will If you would like to create a custom theme, you can use [ThemeRoller](http://jquerymobile.com/themeroller/) that allows users to create their own theme through an easy to use drag and drop interface. You will then be able to download and use your newly created theme. -### Go forth and build something +### Go Forth and Build Something This guide has provided you with a basic structure for a jQuery Mobile page and a few enhanced elements. You can explore the full [jQuery Mobile documentation](http://jquerymobile.com/demos/1.2.0/) to learn about linking pages, adding animated page transitions, and creating dialogs and popups. diff --git a/page/jquery-mobile/theme-roller.md b/page/jquery-mobile/theme-roller.md index eeeab4f0..4211b31c 100644 --- a/page/jquery-mobile/theme-roller.md +++ b/page/jquery-mobile/theme-roller.md @@ -1,29 +1,29 @@ --- -title: Creating a custom theme with ThemeRoller +title: Creating a Custom Theme with ThemeRoller level: Beginner --- ## Theming Overview -jQuery Mobile has a robust theme framework that supports up to 26 sets of toolbar, content and button colors, called a "swatch". The framework comes with five defined themes (swatches 'a' to 'e') which can be used readily, removed or overwritten. +jQuery Mobile has a robust theme framework that supports up to 26 sets of toolbar, content, and button colors, called a "swatch". The framework comes with five defined themes (swatches "a" to "e") which can be used readily, removed, or overwritten. -### Default theme swatch mapping for components +### Default Theme Swatch Mapping for Components -If no theme swatch letter is set at all, the framework uses the 'a' swatch (black in the default theme) for headers and footers and the 'c' swatch (light gray in the default theme) for the page content to maximize contrast between the both. +If no theme swatch letter is set at all, the framework uses the "a" swatch (black in the default theme) for headers and footers and the "c" swatch (light gray in the default theme) for the page content to maximize contrast between the both. -All items in containers inherit the swatch from their parent. Exceptions to this rule are the listdivider in listviews, the header of nested list pages, and the button of split button lists, which all default to 'b' (blue in the default theme). Count bubbles default to 'c' (silver in the default theme). +All items in containers inherit the swatch from their parent. Exceptions to this rule are the listdivider in listviews, the header of nested list pages, and the button of split button lists, which all default to "b" (blue in the default theme). Count bubbles default to "c" (silver in the default theme). -Note that there is also a swatch named "active" (bright blue in the default theme) which is used to indicate an active selected item. See the Global "Active" state further down this page for further information on the active swatch. +Note that there is also a swatch named "active" (bright blue in the default theme) which is used to indicate an active selected item. See the global "Active" state further down this page for more information on the active swatch. -The page loading dialog and error message don't inherit a swatch theme. The loading dialog defaults to swatch 'a' (black in the default theme) and the error message to swatch 'e' (yellow in the default theme). You can configure those defaults globally. +The page loading dialog and error message don't inherit a swatch theme. The loading dialog defaults to swatch "a" (black in the default theme) and the error message to swatch "e" (yellow in the default theme). You can configure those defaults globally. -### Themes and swatches +### Themes and Swatches The theme system separates color and texture from structural styles that define things like padding and dimensions. This allows theme colors and textures to be defined once in the stylesheet and to be mixed, matched, and combined to achieve a wide range of visual effects. Each theme includes several global settings, including font family, drop shadows for overlays, and corner radius values for buttons and boxes. In addition, the theme can include multiple color swatches, each with color values for bars, content blocks, buttons and list items, and font text-shadow. -The default theme includes 5 swatches that are given letters (a, b, c, d, e) for quick reference. To make mapping of color swatches consistent across our widgets, we have followed the convention that swatch 'a' is the highest level of visual priority (black in our default theme), 'b' is secondary level (blue) and 'c' is the baseline level (gray) that we use by default in many situations, 'd' for an alternate secondary level and 'e' as an accent swatch. Themes may have additional swatches for accent colors or specific situations. For example, you could add a new theme swatch 'f' that has a red bar and button for use in error situations. +The default theme includes five swatches that are given letters (a, b, c, d, e) for quick reference. To make mapping of color swatches consistent across our widgets, we have followed the convention that swatch "a" is the highest level of visual priority (black in our default theme), "b" is secondary level (blue), "c" is the baseline level (gray) that we use by default in many situations, "d" for an alternate secondary level, and "e" as an accent swatch. Themes may have additional swatches for accent colors or specific situations. For example, you could add a new theme swatch "f" that has a red bar and button for use in error situations. Most theme changes can be done using ThemeRoller, but it is also fairly simple to manually edit the base swatches in the default theme and/or add additional swatches by editing the theme CSS file. Just copy a block of swatch styles, rename the classes with the new swatch letter name, and tweak colors as you see fit. @@ -31,47 +31,44 @@ Most theme changes can be done using ThemeRoller, but it is also fairly simple t ![picture Theme Roller Logo](/resources/jquery-mobile/themeroller-mobile-logo.png "Theme Roller") -The easiest way to create custom themes is with the ThemeRoller tool. It allows you to build a theme composed of up to 26 swatches, download a the newly created CSS file, and use it in your project. +The easiest way to create custom themes is with the ThemeRoller tool. It allows you to build a theme composed of up to 26 swatches, download the newly created CSS file, and use it in your project. +### Creating the Theme Swatches -### Creating the Theme swatches +The [ThemeRoller](http://jquerymobile.com/themeroller/) allows users to create their own theme through an easy to use drag and drop interface. By default, ThemeRoller offers three swatches (a, b and c). You can use the offered default colors, the Adobe kuler colors, or create your own. You will create your theme by dragging the chosen color onto the chosen element in the swatch of your choice. You can add more swatches by pressing the "+" sign near the "A", "B", and "C" tabs, in the left-hand side menu. -The [ThemeRoller](http://jquerymobile.com/themeroller/) allows users to create their own theme through an easy to use drag and drop interface. By default, ThemeRoller offers three swatches (a, b and c). You can use the offered default colors, the Adobe kuler colors, or create your own. You will create your theme by dragging the chosen color onto the chosen element in the swatch of your choice. You can add more swatches by pressing the '+' sign near the 'A', 'B', and 'C' tabs, in the left hand-side menu. +You can further edit your swatch from the menu. For example, you can expand the various element parts and carry out detailed editing. This will allow you to change text color, text shadow size, position and color, etc. You can also edit the gradient used on each element. -You can further edit your swatch from the menu. For example, you can expand the various element parts and carry out detailed editing. For example, this will allow you to text color, text shadow size, position and color, etc. You can also edit the gradient used on each element. +Here are two examples of theme swatches created, one with the default colors, and one with the kuler colors: -Here are two examples of theme swatches created, the first one with the default colors and with the kuler colors: +![picture Default colors theme example](/resources/jquery-mobile/Theme.png "Default colors theme example") ![picture Kuler theme example](/resources/jquery-mobile/Kuler.png "Kuler theme example") -![picture Default colors theme example](/resources/jquery-mobile/Theme.png "Default colors theme example") ![picture Kuler theme example](/resources/jquery-mobile/Kuler.png "Kuler theme example") +### Downloading the Created Theme -### Downloading the created Theme - -Once you are satisfied with the various swatches that you have created in your theme, you can download this theme to be able to start using it in your project. You will simply need to press the 'Download theme zip file button', and enter the name of your theme in the popup window. Then, press the 'Download Zip' button on the download popup window, see below: +Once you are satisfied with the various swatches that you have created in your theme, you can download this theme to be able to start using it in your project. You will simply need to press the "Download theme zip file button", and enter the name of your theme in the popup window. Then, press the "Download Zip" button on the download popup window, see below: ![picture Download Theme](/resources/jquery-mobile/downloadTheme.png "Download Theme") -### Using the downloaded Theme +### Using the Downloaded Theme -The theme gets downloaded on your local machine as a zip file. This contains an `index.html` file, and a `themes` folder. The `index.html` file is an example of how you can now se your theme. The `themes` folder contains your theme CSS files, and the icons that are used by jQuery Mobile. +The theme gets downloaded on your local machine as a zip file. This contains an `index.html` file, and a `themes` folder. The `index.html` file is an example of how you can now use your theme. The `themes` folder contains your theme CSS files, and the icons that are used by jQuery Mobile. -To start using your theme, you can either start from the provided `index.html` or start from scratch. As explained in the theme download popup window, all you need is to add your theme to the head of your page before the jquery.mobile.structure file, like this: +To start using your theme, you can either start from the provided `index.html`, or start from scratch. As explained in the theme download popup window, all you need is to add your theme to the head of your page before the jquery.mobile.structure file, like this: ``` - + - - jQuery Mobile page - - - - - - - + jQuery Mobile page + + + + + + ``` ### Final Note -You need to be aware that jQuery Mobile will default to certain swatches when none are specified. For example, page content will default to swatch 'c', list dividers to swatch 'b', etc. As the full jQuery Mobile CSS is replaced by your custom theme CSS and the jQuery Mobile structure CSS, the only swatches available are the ones that you have provided as part of your custom theme. Therefore, you need to either always specify a swatch letter for all your elements or their parent using for example the `data-theme` attribute, or you will need to provide a swatch in your custom theme for the possible defaults. Additionally, the error messages use the swatch 'e', so this should also be specified in your theme. +You need to be aware that jQuery Mobile will default to certain swatches when none are specified. For example, page content will default to swatch "c", list dividers to swatch "b", etc. As the full jQuery Mobile CSS is replaced by your custom theme CSS and the jQuery Mobile structure CSS, the only swatches available are the ones that you have provided as part of your custom theme. Therefore, you need to either always specify a swatch letter for all your elements or their parent using for example the `data-theme` attribute, or you will need to provide a swatch in your custom theme for the possible defaults. Additionally, the error messages use the swatch "e", so this should also be specified in your theme. From 17654086a2b0f778270029ff5985fb9fe644e90f Mon Sep 17 00:00:00 2001 From: Markus Amalthea Magnuson Date: Fri, 17 May 2013 12:25:58 -0400 Subject: [PATCH 009/379] Style and typography fixes and code style adherence in the jQuery UI section. Fixes #333. --- page/jquery-ui/getting-started.md | 106 ++-- page/jquery-ui/how-jquery-ui-works.md | 109 ++-- page/jquery-ui/theming.md | 20 +- page/jquery-ui/theming/api.md | 42 +- page/jquery-ui/theming/themeroller.md | 14 +- page/jquery-ui/theming/write-a-theme.md | 35 +- .../how-to-use-the-widget-factory.md | 560 +++++++----------- .../why-use-the-widget-factory.md | 91 ++- 8 files changed, 416 insertions(+), 561 deletions(-) diff --git a/page/jquery-ui/getting-started.md b/page/jquery-ui/getting-started.md index 1e532b7c..84794ef2 100644 --- a/page/jquery-ui/getting-started.md +++ b/page/jquery-ui/getting-started.md @@ -4,37 +4,45 @@ level: beginner --- ### What is jQuery UI? -jQuery UI is a widget and interaction library built on top of the jQuery JavaScript Library that you can use to build highly interactive web applications. This guide is designed to get you up to speed on how jQuery UI works. Follow along below to get started. -### Start by checking out the demos +jQuery UI is a widget and interaction library built on top of the jQuery JavaScript Library that you can use to build highly interactive web applications. This guide is designed to get you up to speed on how jQuery UI works. Follow along below to get started. + +### Start by Checking Out the Demos + To get a feel for what jQuery UI is capable of, check out the [UI Demos](http://jqueryui.com/demos/). In the demos section, the navigation lists all of the interactions and widgets that jQuery UI offers. Choose an interaction or widget and you'll be presented with several demo configurations for that particular plugin. Each demo allows you to view source code, change themes, and the URL can always be bookmarked. For example, check out the [accordion widget's fill space demo page](http://jqueryui.com/accordion/#fillspace). -### Build your custom jQuery UI download -Once you have a basic understanding of what jQuery UI is and what it does, you're ready to try it out! It's time to head over to the [Download Builder](http://jqueryui.com/download/) on the jQuery UI website to download a copy of jQuery UI. jQuery UI's download builder allows you to choose the components you would like to download and get a custom version of the library for your project. There are 3 easy steps to building your custom jQuery UI download: +### Build Your Custom jQuery UI Download + +Once you have a basic understanding of what jQuery UI is and what it does, you're ready to try it out! It's time to head over to the [Download Builder](http://jqueryui.com/download/) on the jQuery UI website to download a copy of jQuery UI. jQuery UI's Download Builder allows you to choose the components you would like to download and get a custom version of the library for your project. There are three easy steps to building your custom jQuery UI download: -#### Step 1: Choose which components you need -The main column of the Download Builder lists all of the javascript components in jQuery UI categorized into groups: core, interations, widgets, and effects. Some components in jQuery UI depend on other components. Just check the boxes for the widgets you'd like to download and any required dependencies will automatically be checked as well. The components you select will all be combined into a custom jQuery UI javascript file. +#### Step 1: Choose Which Components You Need + +The main column of the Download Builder lists all of the JavaScript components in jQuery UI categorized into groups: core, interations, widgets, and effects. Some components in jQuery UI depend on other components. Just check the boxes for the widgets you'd like to download and any required dependencies will automatically be checked as well. The components you select will all be combined into a custom jQuery UI JavaScript file. ![Configuring a download](/resources/jquery-ui/configure.png) -#### Step 2: Select a theme (or roll your own custom theme) -In the right column of the download builder, you'll find a field where you can choose from a number of pre-designed themes for your jQuery UI widgets. +#### Step 2: Select a Theme (or Roll Your Own Custom Theme) + +In the right column of the Download Builder, you'll find a field where you can choose from a number of pre-designed themes for your jQuery UI widgets. You can either choose from the various themes we provide, or you can design your own custom theme using ThemeRoller (more on that later). -**Advanced Theme Settings:** *The theme section of the download builder also offers some advanced configuration settings for your theme. If you plan to use multiple themes on a single page, these fields will come in handy. If you plan to only use one theme on a page, you can skip these settings entirely.* +**Advanced Theme Settings:** *The theme section of the Download Builder also offers some advanced configuration settings for your theme. If you plan to use multiple themes on a single page, these fields will come in handy. If you plan to only use one theme on a page, you can skip these settings entirely.* -#### Step 3: Choose a version of jQuery UI -The last step in the download builder is to select a version number. This is a very important step because jQuery UI versions are designed to work with specific versions of jQuery. The current versions are: +#### Step 3: Choose a Version of jQuery UI -* jQuery UI 1.10.0 - Requires jQuery 1.6+ -* jQuery UI 1.9.2 - Requires jQuery 1.6+ +The last step in the Download Builder is to select a version number. This is a very important step because jQuery UI versions are designed to work with specific versions of jQuery. The current versions are: + +* jQuery UI 1.10.2 – Requires jQuery 1.6 or later. +* jQuery UI 1.9.2 – Requires jQuery 1.6 or later. #### Click Download! -You're finished with the download builder! Click the download button and you'll get a customized zip file containing everything you selected. -### After downloading: Intro to using jQuery UI +You're finished with the Download Builder! Click the download button and you'll get a customized zip file containing everything you selected. + +### After Downloading: Intro to Using jQuery UI + Once you've downloaded jQuery UI, you'll get a zip containing the following files: * `/css/` @@ -42,73 +50,81 @@ Once you've downloaded jQuery UI, you'll get a zip containing the following file * `/js/` * `index.html` -### Basic overview: using jQuery UI on a web page -Open up index.html in a text editor and you'll see that it links to a few dependencies: your theme, jQuery, and jQuery UI. Generally, you'll need to include these 3 files on any page to use jQuery UI widgets and interactions: +### Basic Overview: Using jQuery UI on a Web Page +Open up `index.html` in a text editor and you'll see that it links to a few dependencies: your theme, jQuery, and jQuery UI. Generally, you'll need to include these three files on any page to use jQuery UI widgets and interactions: ```html - - - + + + ``` -Once you've included the necessary files, you can add some jQuery widgets to your page. For example, to make a datepicker widget, you'll add a text input element to your page and then call .datepicker(); on it. Like this: +Once you've included the necessary files, you can add some jQuery widgets to your page. For example, to make a datepicker widget, you'll add a text input element to your page and then call `.datepicker()` on it. Like this: **HTML:** + ```html - + ``` -**JS:** +**JavaScript:** + ```javascript -$('#date').datepicker(); +$( "#date" ).datepicker(); ``` ![Example Screenshot](/resources/jquery-ui/ex-datepicker.png) -#### That's it! -For demos of all of the jQuery UI widgets and interactions. Check out the demos section of the jQuery UI website. +#### That's It! -### Customizing jQuery UI to your needs -jQuery UI allows you to customize it in several ways. You've already seen how the download builder allows you to customize your copy of jQuery UI to include only the portions you want, but there are additional ways to customize that code to your implementation. +For demos of all of the jQuery UI widgets and interactions, check out the demos section of the jQuery UI website. -### jQuery UI basics: using options -Each plugin in jQuery UI has a default configuration which is catered to the most basic and common use case. But if you want a plugin to behave different from its default configuration, you can override each of its default settings using "options". Options are a set of properties passed into a jQuery UI widget as an argument. For example, the slider widget has an option for orientation, which allows you to specify whether the slider should be horizontal or vertical. To set this option for a slider on your page, you just pass it in as an argument, like this: +### Customizing jQuery UI to Your Needs + +jQuery UI allows you to customize it in several ways. You've already seen how the Download Builder allows you to customize your copy of jQuery UI to include only the portions you want, but there are additional ways to customize that code to your implementation. +### jQuery UI Basics: Using Options + +Each plugin in jQuery UI has a default configuration which is catered to the most basic and common use case. But if you want a plugin to behave different from its default configuration, you can override each of its default settings using "options". Options are a set of properties passed into a jQuery UI widget as an argument. For example, the slider widget has an option for orientation, which allows you to specify whether the slider should be horizontal or vertical. To set this option for a slider on your page, you just pass it in as an argument, like this: ```javascript -$('#mySliderDiv').slider({ - orientation: 'vertical' +$( "#mySliderDiv" ).slider({ + orientation: "vertical" }); ``` You can pass as many different options as you'd like by following each one with a comma (except the last one): ```javascript -$('#mySliderDiv').slider({ - orientation: 'vertical', - min: 0, - max: 150, - value: 50 +$( "#mySliderDiv" ).slider({ + orientation: "vertical", + min: 0, + max: 150, + value: 50 }); ``` Just remember to surround your options with curly brackets `{ }`, and you're well on your way. Of course, the example above barely touches on what you can do with jQuery UI. To get detailed information on the entire set of jQuery UI widgets, visit the [jQuery UI documentation](http://jqueryui.com/demos/). -### Visual customization: Designing a jQuery UI theme -If you want to design your own theme, jQuery UI has a very slick application for just that purpose. It's called ThemeRoller, and you can always get to it by either clicking the "Themes" link in the jQuery UI navigation, or simply going to [jQuery UI Themeroller](http://jqueryui.com/themeroller/). +### Visual Customization: Designing a jQuery UI Theme -ThemeRoller provides a custom interface for designing all of the elements used by jQuery UI widgets. As you tweak the "levers" in the left column, the widgets on the right will reflect your design. The Gallery tab of ThemeRoller offers a number of pre-designed themes (the same ones offered by the download builder) that you can tweak or download as they are. +If you want to design your own theme, jQuery UI has a very slick application for just that purpose. It's called ThemeRoller, and you can always get to it by either clicking the "Themes" link in the jQuery UI navigation, or simply going to [jQuery UI ThemeRoller](http://jqueryui.com/themeroller/). -![Themeroller Example](/resources/jquery-ui/themeroller.png) +ThemeRoller provides a custom interface for designing all of the elements used by jQuery UI widgets. As you tweak the "levers" in the left column, the widgets on the right will reflect your design. The Gallery tab of ThemeRoller offers a number of pre-designed themes (the same ones offered by the Download Builder) that you can tweak or download as they are. -### Downloading your theme -When you click the "Download theme" button in ThemeRoller, you'll be directed to the Download Builder and your custom theme will be auto-selected in the Theme dropdown menu. You can configure your download package further from there. Once you download, you'll see that the example.html page is styled using your custom theme. +![ThemeRoller Example](/resources/jquery-ui/themeroller.png) -**Quick tip:** *If you ever need to edit your theme, simply open the CSS file and find on line 43 where it says "To view and modify this theme, visit ..." That url will open the theme in ThemeRoller for editing.* +### Downloading Your Theme + +When you click the "Download theme" button in ThemeRoller, you'll be directed to the Download Builder and your custom theme will be auto-selected in the Theme dropdown menu. You can configure your download package further from there. Once you download, you'll see that the `example.html` page is styled using your custom theme. + +**Quick Tip:** *If you ever need to edit your theme, simply open the CSS file and find on line 43 where it says "To view and modify this theme, visit ..." That url will open the theme in ThemeRoller for editing.* + +### Support: Where Can I Get Help? -### Support: Where can I get help? JQuery UI user and developer resources are kept up-to-date at the [Support Center](http://jqueryui.com/support). ### Developers Wanted! + Want to join the jQuery UI team? We'd love your help! Visit the UI [Development Center](http://jqueryui.com/development) for details on how to get involved. diff --git a/page/jquery-ui/how-jquery-ui-works.md b/page/jquery-ui/how-jquery-ui-works.md index 41e5916b..938aa72a 100644 --- a/page/jquery-ui/how-jquery-ui-works.md +++ b/page/jquery-ui/how-jquery-ui-works.md @@ -7,97 +7,81 @@ jQuery UI contains many widgets that maintain [state](http://en.wikipedia.org/wi ## Initialization -In order to track the state of the widget, we must introduce a full life cycle for the widget. -The life cycle starts when the widget is initalized. -To initialize a widget, we simply call the plugin on one or more elements. +In order to track the state of the widget, we must introduce a full life cycle for the widget. The life cycle starts when the widget is initalized. To initialize a widget, we simply call the plugin on one or more elements. ``` - $( "#elem" ).progressbar(); +$( "#elem" ).progressbar(); ``` -This will initialize each element in the jQuery object, in this case the element with an id of "elem". -Because we called the `progressbar()` method with no parameters, the widget is initialized with its default options. -We can pass a set of options during initialization in order to override the default options. +This will initialize each element in the jQuery object, in this case the element with an id of "elem". Because we called the `.progressbar()` method with no parameters, the widget is initialized with its default options. We can pass a set of options during initialization in order to override the default options. ``` - $( "#elem" ).progressbar({ value: 20 }); +$( "#elem" ).progressbar({ value: 20 }); ``` -We can pass as many or as few options as we want during initialization. -Any options that we don't pass will just use their default values. +We can pass as many or as few options as we want during initialization. Any options that we don't pass will just use their default values. -The options are part of the widget's state, -so we can set options after initialization as well. -We'll see this later with the `option` method. +The options are part of the widget's state, so we can set options after initialization as well. We'll see this later with the `option` method. ## Methods -Now that the widget is initialized, we can query its state or perform actions on the widget. -All actions after initialization take the form of a method call. -To call a method on a widget, we pass the name of the method to the jQuery plugin. -For example, to call the `value` method on our progressbar widget, we would use: +Now that the widget is initialized, we can query its state or perform actions on the widget. All actions after initialization take the form of a method call. To call a method on a widget, we pass the name of the method to the jQuery plugin. For example, to call the `value` method on our progressbar widget, we would use: ``` - $( "#elem" ).progressbar( "value" ); +$( "#elem" ).progressbar( "value" ); ``` -If the method accepts parameters, we can pass them after the method name. -For example, to pass the parameter `40` to the `value` method, we can use: +If the method accepts parameters, we can pass them after the method name. For example, to pass the parameter `40` to the `value` method, we can use: ``` - $( "#elem" ).progressbar( "value", 40 ); +$( "#elem" ).progressbar( "value", 40 ); ``` Just like other methods in jQuery, most widget methods return the jQuery object for chaining. ``` - $( "#elem" ) - .progressbar( "value", 90 ) - .addClass( "almost-done" ); +$( "#elem" ) + .progressbar( "value", 90 ) + .addClass( "almost-done" ); ``` ### Common Methods -Each widget will have its own set of methods based on the functionality that the widget provides. -However, there are a few methods that exist on all widgets. +Each widget will have its own set of methods based on the functionality that the widget provides. However, there are a few methods that exist on all widgets. #### option -As we mentioned earlier, we can change options after initialization through the `option` method. -For example, we can change the progressbar's value to 30 by calling the `option` method. +As we mentioned earlier, we can change options after initialization through the `option` method. For example, we can change the progressbar's value to 30 by calling the `option` method. ``` - $( "#elem" ).progressbar( "option", "value", 30 ); +$( "#elem" ).progressbar( "option", "value", 30 ); ``` -Note that this is different from the previous example where we were calling the `value` method. -In this example, we're calling the `option` method and saying that we want to change the value option to 30. +Note that this is different from the previous example where we were calling the `value` method. In this example, we're calling the `option` method and saying that we want to change the value option to 30. We can also get the current value for an option. ``` - $( "#elem" ).progressbar( "option", "value" ); +$( "#elem" ).progressbar( "option", "value" ); ``` In addition, we can update multiple options at once by passing an object to the `option` method. ``` - $( "#elem" ).progressbar( "option", { - value: 100, - disabled: true - }); +$( "#elem" ).progressbar( "option", { + value: 100, + disabled: true +}); ``` -You may have noticed that the `option` method has the same signature as getters and setters in jQuery core, such as `.css()` and `.attr()`. -The only difference is that you have to pass the string "option" as the first parameter. +You may have noticed that the `option` method has the same signature as getters and setters in jQuery core, such as `.css()` and `.attr()`. The only difference is that you have to pass the string "option" as the first parameter. #### disable -As you might guess, the `disable` method disables the widget. -In the case of progressbar, this changes the styling to make the progressbar look disabled. +As you might guess, the `disable` method disables the widget. In the case of progressbar, this changes the styling to make the progressbar look disabled. ``` - $( "#elem" ).progressbar( "disable" ); +$( "#elem" ).progressbar( "disable" ); ``` Calling the `disable` method is equivalent to setting the `disabled` option to `true`. @@ -107,58 +91,49 @@ Calling the `disable` method is equivalent to setting the `disabled` option to ` The `enable` method is the opposite of the `disable` method. ``` - $( "#elem" ).progressbar( "enable" ); +$( "#elem" ).progressbar( "enable" ); ``` Calling the `enable` method is equivalent to setting the `disabled` option to `false`. #### destroy -If you no longer need the widget, you can destroy it and return back to the original markup. -This ends the life cycle of the widget. +If you no longer need the widget, you can destroy it and return back to the original markup. This ends the life cycle of the widget. ``` - $( "#elem" ).progressbar( "destroy" ); +$( "#elem" ).progressbar( "destroy" ); ``` -Once you destroy a widget, you can no longer call any methods on it unless you initialize the widget again. -If you're removing the element, either directly via `.remove()` or by modifying an ancestor with `.html()` or `.empty()`, -the widget will automatically destroy itself. +Once you destroy a widget, you can no longer call any methods on it unless you initialize the widget again. If you're removing the element, either directly via `.remove()` or by modifying an ancestor with `.html()` or `.empty()`, the widget will automatically destroy itself. #### widget -Some widgets generate wrapper elements, or elements disconnected from the original element. -In these cases, the `widget` method will return the generated element. -In cases like the progressbar, where there is no generated wrapper, the `widget` method returns the original element. +Some widgets generate wrapper elements, or elements disconnected from the original element. In these cases, the `widget` method will return the generated element. In cases like the progressbar, where there is no generated wrapper, the `widget` method returns the original element. ``` - $( "#elem" ).progressbar( "widget" ); +$( "#elem" ).progressbar( "widget" ); ``` ## Events -All widgets have events associated with their various behaviors to notify you when the state is changing. -For most widgets, when the events are triggered, the names are prefixed with the widget name. -For example, we can bind to progressbar's change event which is triggered whenever the value changes. +All widgets have events associated with their various behaviors to notify you when the state is changing. For most widgets, when the events are triggered, the names are prefixed with the widget name. For example, we can bind to progressbar's change event which is triggered whenever the value changes. ``` - $( "#elem" ).bind( "progressbarchange", function() { - alert( "The value has changed!" ); - }); +$( "#elem" ).bind( "progressbarchange", function() { + alert( "The value has changed!" ); +}); ``` -Each event has a corresponding callback, which is exposed as an option. -We can hook into progressbar's `change` callback instead of binding to the `progressbarchange` event, if we wanted to. +Each event has a corresponding callback, which is exposed as an option. We can hook into progressbar's `change` callback instead of binding to the `progressbarchange` event, if we wanted to. ``` - $( "#elem" ).progressbar({ - change: function() { - alert( "The value has changed!" ); - } - }); +$( "#elem" ).progressbar({ + change: function() { + alert( "The value has changed!" ); + } +}); ``` ### Common Events -While most events will be widget specific, all widgets have a `create` event. -This event will be triggered immediately after the widget is created. +While most events will be widget specific, all widgets have a `create` event. This event will be triggered immediately after the widget is created. diff --git a/page/jquery-ui/theming.md b/page/jquery-ui/theming.md index 318c9000..e6795eed 100644 --- a/page/jquery-ui/theming.md +++ b/page/jquery-ui/theming.md @@ -5,11 +5,11 @@ level: intermediate All jQuery UI plugins are designed to allow a developer to seamlessly integrate UI widgets into the look and feel of their site or application. Each plugin is styled with CSS and contains two layers of style information: standard [jQuery UI CSS Framework](/jquery-ui/theming/api/) styles and plugin-specific styles. -The jQuery UI CSS Framework provide semantic presentation classes to indicate the role of an element within a widget such as a header, content area, or clickable region. These are applied consistently across all widgets so a clickable tab, accordian or button will all have the same `ui-state-default` class applied to indicate that it is clickable. When a user mouses over one of these elements, this class is changed to `ui-state-hover`, then `ui-state-active` when selected. This level of class consistency makes it easy to ensure that all elements with a similar role or interaction state will look the same across all widgets. +The jQuery UI CSS Framework provide semantic presentation classes to indicate the role of an element within a widget such as a header, content area, or clickable region. These are applied consistently across all widgets so a clickable tab, accordion, or button will all have the same `ui-state-default` class applied to indicate that it is clickable. When a user mouses over one of these elements, this class is changed to `ui-state-hover`, then `ui-state-active` when selected. This level of class consistency makes it easy to ensure that all elements with a similar role or interaction state will look the same across all widgets. -The CSS Framework styles are encapsulated in a single file called ui.theme.css and this is the file modified by the [ThemeRoller](/jquery-ui/theming/themeroller) application. Framework styles only include attributes that affect the look and feel (primarily color, background images and icons) so these are 'safe' styles that will not affect functionality of individual plugins. This separation means that a developer can create a custom look and feel by modifying the colors and images in theme.css file and know that as future plugins or bug fixes become available, these should work with the theme without modification. +The CSS Framework styles are encapsulated in a single file called `ui.theme.css` and this is the file modified by the [ThemeRoller](/jquery-ui/theming/themeroller/) application. Framework styles only include attributes that affect the look and feel (primarily color, background images, and icons) so these are "safe" styles that will not affect functionality of individual plugins. This separation means that a developer can create a custom look and feel by modifying the colors and images in the `theme.css` file and know that as future plugins or bug fixes become available, these should work with the theme without modification. -Since the framework styles only cover look and feel, plugin specific stylesheets are included that contain all the additional structural style rules required to make the widget functional, such as dimensions, padding, margins, positioning and floats. Stylesheets for each plugin are located in the themes/base folder of the download and are named to match the plugin such as "jquery.ui.accordion.css". These styles must be carefully edited because they work in conjunction with the scripting and provide overrides of framework styles as needed. +Since the framework styles only cover look and feel, plugin specific stylesheets are included that contain all the additional structural style rules required to make the widget functional, such as dimensions, padding, margins, positioning, and floats. Stylesheets for each plugin are located in the `themes/base` folder of the download and are named to match the plugin such as "jquery.ui.accordion.css". These styles must be carefully edited because they work in conjunction with the scripting and provide overrides of framework styles as needed. We encourage all developers creating jQuery plugins to leverage the jQuery UI CSS Framework because it will make it much easier for end users to theme and use your plugin. @@ -17,18 +17,8 @@ We encourage all developers creating jQuery plugins to leverage the jQuery UI CS There are three general approaches to theming jQuery UI plugins: -* **Download a ThemeRoller theme**: The easiest way to build a theme is to use the [Themeroller](/jquery-ui/theming/themeroller) to generate and download a theme. This app will create a new `ui.theme.css` file and an images directory containing all necessary background images and icon sprites which can simply be dropped into your project. This approach will be the easiest to create and maintain but limits customization to the options provided in ThemeRoller. +* **Download a ThemeRoller theme**: The easiest way to build a theme is to use the [ThemeRoller](/jquery-ui/theming/themeroller/) to generate and download a theme. This app will create a new `ui.theme.css` file and an `images` directory containing all necessary background images and icon sprites which can simply be dropped into your project. This approach will be the easiest to create and maintain but limits customization to the options provided in ThemeRoller. * **Modify the CSS files**: To get a bit more control over the look and feel, you may choose to start with the default theme (Smoothness) or a ThemeRoller-generated theme and then adjust the `ui.theme.css` file or any of the individual plugin stylesheets. For example, you could easily tweak the corner radius for all buttons to be different than the rest of the UI components or change the path for the icon sprite to use a custom set. With a bit of style scoping, you can even use multiple themes together in a single UI. To keep maintenance simple, restricting changes to just the `ui.theme.css` file and images is recommended. * **Write completely custom CSS**: For the greatest amount of control, the CSS for each plugin can be written from scratch without using the framework classes or plugin-specific stylesheet. This may be necessary if the desired look and feel can't be achieved by modifying the CSS or if highly customized markup is used. This approach requires deep expertise in CSS and will require manual updates for future plugins. -### Using ThemeRoller and Themes - - -* [ThemeRoller application](http://jqueryui.com/themeroller/) -* [ThemeRoller documentation](/jquery-ui/theming/themeroller) - How to use the ThemeRoller application - -### jQuery UI CSS Framework & Custom themes - - -* [jQuery UI CSS Framework documentation](/jquery-ui/theming/api/) - Explore the full class API and icon set -* [How to create custom themes](/jquery-ui/theming/custom-themes) - Tutorial for creating a theme from scratch +### Using ThemeRoller, the jQuery UI CSS Framework, and Writing Custom Themes diff --git a/page/jquery-ui/theming/api.md b/page/jquery-ui/theming/api.md index d02ac812..f59946aa 100644 --- a/page/jquery-ui/theming/api.md +++ b/page/jquery-ui/theming/api.md @@ -3,7 +3,7 @@ title: jQuery UI CSS Framework API level: intermediate --- -[Back to jQuery UI Theming](/jquery-ui/theming) +[Back to jQuery UI Theming](/jquery-ui/theming/) ### The jQuery UI CSS Framework @@ -11,21 +11,21 @@ jQuery UI includes a robust CSS Framework designed for building custom jQuery wi ### Framework Classes -The following CSS classes are split between ui.core.css and ui.theme.css, depending on whether styles are fixed and structural, or themeable (colors, fonts, backgrounds, etc) respectively. These classes are designed to be applied to User Interface elements to achieve visual consistency across an application and allow components to be themeable by jQuery UI ThemeRoller. +The following CSS classes are split between `ui.core.css` and `ui.theme.css`, depending on whether styles are fixed and structural, or themeable (colors, fonts, backgrounds, etc.) respectively. These classes are designed to be applied to user interface elements to achieve visual consistency across an application and allow components to be themeable by jQuery UI ThemeRoller. ### Layout Helpers -* `.ui-helper-hidden`: Applies display: none to elements. -* `.ui-helper-hidden-accessible`: Applies accessible hiding to elements (via abs positioning off the page) -* `.ui-helper-reset`: A basic style reset for UI elements. Resets things such as padding, margins, text-decoration, list-style, etc. -* `.ui-helper-clearfix`: Applies float wrapping properties to parent elements -* `.ui-helper-zfix`: Applies iframe "fix" css to iframe elements when needed in overlays. +* `.ui-helper-hidden`: Applies `display: none` to elements. +* `.ui-helper-hidden-accessible`: Applies accessible hiding to elements (via absolute positioning off the page.) +* `.ui-helper-reset`: A basic style reset for UI elements. Resets things such as `padding`, `margin`, `text-decoration`, `list-style, etc. +* `.ui-helper-clearfix`: Applies float wrapping properties to parent elements. +* `.ui-helper-zfix`: Applies iframe "fix" CSS to ` - + + + + + + + ``` diff --git a/page/using-jquery-core/dollar-object-vs-function.md b/page/using-jquery-core/dollar-object-vs-function.md index a6e40d4e..64e2a2e3 100644 --- a/page/using-jquery-core/dollar-object-vs-function.md +++ b/page/using-jquery-core/dollar-object-vs-function.md @@ -5,35 +5,22 @@ 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 `$.fn.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 `.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 -- 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()`. +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 -- 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/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..067f08c3 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 @@ -7,8 +7,8 @@ You can check or uncheck a checkbox element or a radio button using the `.prop() ``` // 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..31e4cb7d 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 @@ -3,18 +3,20 @@ 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..79cd18ae 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 @@ -7,8 +7,8 @@ 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..ad78b54e 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 @@ -6,7 +6,7 @@ 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 +14,17 @@ The second is the text value of the select. For example, using the following sel ``` ``` -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..4bc00f6b 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 @@ -6,13 +6,13 @@ 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 37b45536..b3bf1a7f 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 @@ -3,18 +3,18 @@ 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" ); $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. +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 7e1bbfcb..8a8282cc 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 @@ -8,17 +8,17 @@ Because jQuery uses CSS syntax for selecting elements, some characters are inter 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. ``` -// 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: @@ -26,7 +26,7 @@ The following function takes care of escaping these characters and places a "#" ``` function jq( myid ) { - return "#" + myid.replace( /(:|\.|\[|\])/g, "\\$1" ); + return "#" + myid.replace( /(:|\.|\[|\])/g, "\\$1" ); } ``` @@ -34,5 +34,5 @@ function jq( myid ) { The function can be used like so: ``` -$( jq("some.id") ) +$( jq( "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..c0818d02 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 @@ -6,30 +6,30 @@ 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..95adc726 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 @@ -6,19 +6,19 @@ 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..eb9dee0b 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 @@ -3,12 +3,12 @@ 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 +16,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..bce0bd3b 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 @@ -3,31 +3,31 @@ 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 +35,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 ebd6a684..31e528ca 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. ### `$.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()` 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,20 +16,21 @@ 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 @@ -39,27 +41,27 @@ Notice that `arr[ index ]` can't be accessed as the value is conveniently passed ``` 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 @@ -70,9 +72,9 @@ Again, `obj[ key ]` is passed directly to the callback and thus can't be accesse This would be considered incorrect: ``` -// incorrect -$.each( $("p"), function() { - // Do something +// Incorrect: +$.each( $( "p" ), function() { + // Do something }); ``` @@ -86,17 +88,17 @@ For example, given the following markup: ```

``` `.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: @@ -112,19 +114,19 @@ The question is often raised, "If `this` is the element, why is there a second D 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: ``` -$("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 +135,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 +162,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,21 +187,20 @@ 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 + "%"; }); ``` @@ -215,16 +216,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 +233,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 +247,25 @@ For example: diff --git a/page/using-jquery-core/jquery-object.md b/page/using-jquery-core/jquery-object.md index eb99f0ff..deff1824 100644 --- a/page/using-jquery-core/jquery-object.md +++ b/page/using-jquery-core/jquery-object.md @@ -2,22 +2,23 @@ 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 element 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,19 +26,21 @@ 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" ); + +var newElement = document.createElement( "div" ); target.parentNode.insertBefore( target.nextSibling, newElement ) ``` @@ -45,41 +48,45 @@ target.parentNode.insertBefore( target.nextSibling, newElement ) 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 headers = $( "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`: +`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`: ``` -// Viewing the number of 'h1' tags on the page -var allHeaders = $("h1"); +// Viewing the number of

tags on the page. + +var allHeaders = $( "h1" ); alert( allHeaders.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 header 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 headers = $( "h1" ); var firstHeader = headers.eq( 0 ); ``` @@ -87,15 +94,17 @@ var firstHeader = headers.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. ``` -// Selecting only the first 'h1' element on the page -var firstHeaderElem = $("h1").get( 0 ); +// Selecting only the first

element on the page. + +var firstHeaderElem = $( "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 firstHeaderElem = $( "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. @@ -105,42 +114,46 @@ In either case, `firstHeaderElem` contains the native DOM element. This means it 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 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 d213020e..f49ae31e 100644 --- a/page/using-jquery-core/manipulating-elements.md +++ b/page/using-jquery-core/manipulating-elements.md @@ -5,25 +5,26 @@ 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 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](/working-with-selections/) section. Here are a few methods you can use to get and set information about 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. +* `.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 @@ -35,20 +36,19 @@ While there are a variety of ways to move elements around the DOM, there are gen For example, jQuery provides `.insertAfter()` and `.after()`. The `.insertAfter()` method places the selected element(s) after the element that 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, `.insertAfter()`, `.insertBefore()`, `.appendTo()`, and `.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 @@ -56,15 +56,14 @@ $("#myList").append( $("#myList li: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 `.clone()`. - ## Removing Elements 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. @@ -80,58 +79,56 @@ If you want to leave the element on the page but remove its contents, you can us 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 `text` and `href` are not. Property names generally do not need to be quoted unless they are [reserved words](/javascript-101/reserved-words/) (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 @@ -139,30 +136,28 @@ $myList.append( myItems.join("") ); 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: "super-special" }); ``` ``` -// 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: "super-special", + 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 bbdff1c8..94d1776a 100644 --- a/page/using-jquery-core/selecting-elements.md +++ b/page/using-jquery-core/selecting-elements.md @@ -3,70 +3,64 @@ 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 -$(".myClass"); +$( ".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']" ); // Beware, this can be very slow in older browsers ``` ## Selecting Elements by Compound CSS Selector ``` -// Selecting elements by compound CSS selector -$("#contents ul.people li"); +$( "#contents ul.people li" ); ``` -## Pseudo-selectors +## Pseudo-Selectors ``` -// Pseudo-selectors -$("a.external:first"); -$("tr:odd"); +$( "a.external:first" ); +$( "tr:odd" ); -// select all input-like elements in a form (more on this below) -$("#myForm :input"); -$("div:visible"); +// 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 except the first three divs. +$( "div:gt(2)" ); -// all currently animated divs -$("div:animated"); +// All currently animated divs. +$( "div:animated" ); ``` -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. +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. -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. +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. 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. 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']"); +// Find all elements 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. @@ -77,19 +71,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 ) { + ... } ``` @@ -98,10 +92,10 @@ 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. +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. @@ -112,12 +106,12 @@ 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 @@ -126,179 +120,159 @@ jQuery offers several pseudo-selectors that help find elements in forms. These a #### :button -Using the `:button` pseudo-selector targets just the `

My Title

My Footer

My Title

My Footer

tags. + +var headers = $( "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`: +`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`: ``` -// Viewing the number of 'h1' tags on the page -var allHeaders = $("h1"); +// Viewing the number of

tags on the page. + +var allHeaders = $( "h1" ); alert( allHeaders.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 `

element on the page (in a jQuery object) + +var headers = $( "h1" ); var firstHeader = headers.eq( 0 ); ``` @@ -87,15 +94,17 @@ var firstHeader = headers.eq( 0 ); Now `firstHeader` is a jQuery object containing only the first `

tags. + +var headers = $( "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`: +`headers` is now a jQuery element containing all the `