Skip to content

Commit

Permalink
Cleanup.
Browse files Browse the repository at this point in the history
  • Loading branch information
@scottgonzalez
scottgonzalez committed Jul 10, 2013
1 parent 278a81a commit ad18d21
Show file tree
Hide file tree
Showing 64 changed files with 903 additions and 802 deletions.
11 changes: 9 additions & 2 deletions README.md
View file
Expand Up @@ -27,11 +27,13 @@ To build and deploy your changes for previewing in a [jquery-wp-content](https:/
* **No**: The `load`, `scroll` and `error` events (e.g., on an `<img>` element) do not bubble

#### Spelling

* The documentation standardizes on American English spelling. For example:
* **Yes**: color, while, among, customize, argument
* **No**: colour, whilst, amongst, customise, arguement

#### Pronoun Usage

* Use second-person pronoun ("you") when necessary, but try to avoid it.
* Favor the definite article ("the") over second-person possesive ("your").
* **Yes**: Insert the paragraph after the unordered list.
Expand All @@ -41,27 +43,32 @@ To build and deploy your changes for previewing in a [jquery-wp-content](https:/
* **No**: And now we have our paragraph beneath the unordered list.

#### "Voice"

* Prefer active voice over passive.
* **Active**: Calling `.click()` binds a click handler to the elements in the collection
* **Passive**: Click handlers are bound to elements in the collection when `.click()` is called

### Code Style
Code in the API documentation should follow the [jQuery Core Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) with the following addition:

Code in the API documentation should follow the [jQuery Core Style Guide](http://contribute.jquery.org/style-guide/) with the following addition:

* **Document ready syntax**: Use `$( document ).ready(function() {` instead of `$(function() {` as it's harder for new users to distinguish the difference between the latter and an IIFE.

#### Code within prose content (paragraphs and the like):
* Methods: use a dot, followed by the method name, followed by parentheses: e.g. The `.focus()` method is a shortcut for `.bind('focus', handler)` in the first and second variations, and `.trigger('focus')` in the third.

* Methods: use a dot, followed by the method name, followed by parentheses: e.g. The `.focus()` method is a shortcut for `.on( "focus", handler )` in the first and second variations, and `.trigger( "focus" )` in the third.
* Properties: use a dot, followed by the property name: e.g. `.length`.
* Functions: use the function name, followed by parentheses: `myFunction()`.

#### Examples

* Examples should indicate what the expected result will be before presenting the code. This makes code clearer and skimming easier, especially for newer coders who may not understand what is supposed to be happening from reading the code itself.
* **Yes**: Find all p elements that are children of a div element and apply a border to them.
* **No**: Find all p elements that are children of a div element.
* Make your example easy to follow with good comments so that the explanation isn't necessary.

### Rhetorical Context

* Subject
* The entirety of jQuery's public API
* Audience
Expand Down
35 changes: 18 additions & 17 deletions entries/add.xml
View file
Expand Up @@ -37,17 +37,17 @@
<desc>Add elements to the set of matched elements.</desc>
<longdesc>
<p>Given a jQuery object that represents a set of DOM elements, the <code>.add()</code> method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to <code>.add()</code> can be pretty much anything that <code>$()</code> accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.</p>
<p>Do not assume that this method appends the elements to the existing collection in the order they are passed to the <code>.add()</code> method. When all elements are members of the same document, the resulting collection from <code>.add()</code> will be sorted in document order; that is, in order of each element's appearance in the document. If the collection consists of elements from different documents or ones not in any document, the sort order is undefined. To create a jQuery object with elements in a well-defined order, use the <code>$(array_of_DOM_elements)</code> signature.</p>
<p>Do not assume that this method appends the elements to the existing collection in the order they are passed to the <code>.add()</code> method. When all elements are members of the same document, the resulting collection from <code>.add()</code> will be sorted in document order; that is, in order of each element's appearance in the document. If the collection consists of elements from different documents or ones not in any document, the sort order is undefined. To create a jQuery object with elements in a well-defined order, use the <code>$(array_of_DOM_elements)</code> signature.</p>
<p>The updated set of elements can be used in a following (chained) method, or assigned to a variable for later use. For example:</p>
<pre><code>
$( "p" ).add( "div" ).addClass( "widget" );
var pdiv = $( "p" ).add( "div" );
</code></pre>
</code></pre>
<p>The following will <em>not</em> save the added elements, because the <code>.add()</code> method creates a new set and leaves the original set in pdiv unchanged:</p>
<pre><code>
var pdiv = $( "p" );
pdiv.add( "div" ); // WRONG, pdiv will not change
</code></pre>
</code></pre>
<p>Consider a page with a simple list and a paragraph following it:</p>
<pre><code>
&lt;ul&gt;
Expand All @@ -56,9 +56,11 @@ pdiv.add( "div" ); // WRONG, pdiv will not change
&lt;li&gt;list item 3&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;a paragraph&lt;/p&gt;
</code></pre>
</code></pre>
<p>We can select the list items and then the paragraph by using either a selector or a reference to the DOM element itself as the <code>.add()</code> method's argument:</p>
<pre><code>$( "li" ).add( "p" ).css( "background-color", "red" );</code></pre>
<pre><code>
$( "li" ).add( "p" ).css( "background-color", "red" );
</code></pre>
<p>Or:</p>
<pre><code>
$( "li" ).add( document.getElementsByTagName( "p" )[ 0 ] )
Expand All @@ -82,24 +84,23 @@ $( "div" ).css( "border", "2px solid red" )
.css( "background", "yellow" );
]]></code>
<css><![CDATA[
div {
width: 60px;
height: 60px;
margin: 10px;
div {
width: 60px;
height: 60px;
margin: 10px;
float: left;
}
p {
clear: left;
font-weight: bold;
p {
clear: left;
font-weight: bold;
font-size: 16px;
color: blue;
margin: 0 10px;
padding: 2px;
margin: 0 10px;
padding: 2px;
}
]]></css>
]]></css>
<html><![CDATA[
<div></div>
<div></div>
<div></div>
<div></div>
Expand Down Expand Up @@ -142,7 +143,7 @@ $( "p" ).add( document.getElementById( "a" ) ).css( "background", "yellow" );
<desc>Demonstrates how to add (or push) elements to an existing collection</desc>
<code><![CDATA[
var collection = $( "p" );
// capture the new collection
// Capture the new collection
collection = collection.add( document.getElementById( "a" ) );
collection.css( "background", "yellow" );
]]></code>
Expand Down
13 changes: 7 additions & 6 deletions entries/addBack.xml
View file
Expand Up @@ -21,9 +21,10 @@
&lt;/ul&gt;
</code></pre>
<p>The result of the following code is a red background behind items 3, 4 and 5:</p>
<pre><code>$( "li.third-item" ).nextAll().addBack()
<pre><code>
$( "li.third-item" ).nextAll().addBack()
.css( "background-color", "red" );
</code></pre>
</code></pre>
<p>First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to <code>.nextAll()</code> then pushes the set of items 4 and 5 onto the stack. Finally, the <code>.addBack()</code> invocation merges these two sets together, creating a jQuery object that points to all three items in document order: <code>{[&lt;li.third-item&gt;,&lt;li&gt;,&lt;li&gt; ]}</code>.</p>
</longdesc>
<example>
Expand All @@ -39,8 +40,8 @@ $( "div.after-addback" ).find( "p" ).addBack().addClass( "background" );
]]></code>
<css><![CDATA[
p, div {
margin: 5px;
padding: 5px;
margin: 5px;
padding: 5px;
}
.border {
border: 2px solid red;
Expand All @@ -49,13 +50,13 @@ $( "div.after-addback" ).find( "p" ).addBack().addClass( "background" );
background: yellow;
}
.left, .right {
width: 45%;
width: 45%;
float: left;
}
.right {
margin-left: 3%;
}
]]></css>
]]></css>
<html><![CDATA[
<div class="left">
<p><strong>Before <code>addBack()</code></strong></p>
Expand Down
28 changes: 14 additions & 14 deletions entries/addClass.xml
View file
Expand Up @@ -41,15 +41,15 @@ $( "p" ).last().addClass( "selected" );
<css><![CDATA[
p {
margin: 8px;
font-size:16px;
font-size: 16px;
}
.selected {
color:blue;
color: blue;
}
.highlight {
background:yellow;
background: yellow;
}
]]></css>
]]></css>
<html><![CDATA[
<p>Hello</p>
<p>and</p>
Expand All @@ -62,17 +62,17 @@ $( "p" ).last().addClass( "selected" );
$( "p:last" ).addClass( "selected highlight" );
]]></code>
<css><![CDATA[
p {
margin: 8px;
font-size: 16px;
p {
margin: 8px;
font-size: 16px;
}
.selected {
color: red;
.selected {
color: red;
}
.highlight {
background: yellow;
.highlight {
background: yellow;
}
]]></css>
]]></css>
<html><![CDATA[
<p>Hello</p>
<p>and</p>
Expand All @@ -94,7 +94,7 @@ $( "div" ).addClass(function( index, currentClass ) {
});
]]></code>
<css><![CDATA[
div {
div {
background: white;
}
.red {
Expand All @@ -103,7 +103,7 @@ $( "div" ).addClass(function( index, currentClass ) {
.red.green {
background: green;
}
]]></css>
]]></css>
<html><![CDATA[
<div>This div should be white</div>
<div class="red">This div will be green because it now has the "green" and "red" classes.
Expand Down
42 changes: 25 additions & 17 deletions entries/after.xml
View file
Expand Up @@ -27,17 +27,20 @@
<longdesc>
<p>The <code>.after()</code> and <code><a href="/insertAfter">.insertAfter()</a></code> methods perform the same task. The major difference is in the syntax&#x2014;specifically, in the placement of the content and target. With <code>.after()</code>, the selector expression preceding the method is the container after which the content is inserted. With <code>.insertAfter()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted after the target container.</p>
<p>Using the following HTML:</p>
<pre><code>&lt;div class="container"&gt;
<pre><code>
&lt;div class="container"&gt;
&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="inner"&gt;Hello&lt;/div&gt;
&lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</code></pre>
&lt;/div&gt;
</code></pre>
<p>Content can be created and then inserted after several elements at once:</p>
<pre><code>
$( ".inner" ).after( "&lt;p&gt;Test&lt;/p&gt;" );
</code></pre>
<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
<pre><code>&lt;div class="container"&gt;
<pre><code>
&lt;div class="container"&gt;
&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="inner"&gt;Hello&lt;/div&gt;
&lt;p&gt;Test&lt;/p&gt;
Expand All @@ -62,16 +65,20 @@ $( ".container" ).after( $( "h2" ) );
<pre><code>$( "&lt;div&gt;&lt;/div&gt;" ).after( "&lt;p&gt;&lt;/p&gt;" );</code></pre>
<p>The result is a jQuery set containing a div and a paragraph, in that order. That set can be further manipulated, even before it is inserted in the document.</p>
<pre><code>
$( "&lt;div&gt;&lt;/div&gt;" ).after( "&lt;p&gt;&lt;/p&gt;" ).addClass( "foo" )
.filter( "p" ).attr( "id", "bar" ).html( "hello" )
$( "&lt;div&gt;&lt;/div&gt;" )
.after( "&lt;p&gt;&lt;/p&gt;" )
.addClass( "foo" )
.filter( "p" )
.attr( "id", "bar" )
.html( "hello" )
.end()
.appendTo( "body" );
</code></pre>
<p>This results in the following elements inserted just before the closing <code>&lt;/body&gt;</code> tag:</p>
<pre><code>
&lt;div class="foo"&gt;&lt;/div&gt;
&lt;p class="foo" id="bar"&gt;hello&lt;/p&gt;
</code></pre>
</code></pre>
<h4 id="passing-a-function">Passing a Function</h4>
<p>As of jQuery 1.4, <code>.after()</code> supports passing a function that returns the elements to insert.</p>
<pre><code>
Expand All @@ -85,11 +92,11 @@ $( "p" ).after(function() {
<p>For example, the following will insert two new <code>&lt;div&gt;</code>s and an existing <code>&lt;div&gt;</code> after the first paragraph:</p>
<pre><code>
var $newdiv1 = $( "&lt;div id='object1'/&gt;" ),
newdiv2 = document.createElement( "div" ),
existingdiv1 = document.getElementById( "foo" );
newdiv2 = document.createElement( "div" ),
existingdiv1 = document.getElementById( "foo" );

$( "p" ).first().after( $newdiv1, [ newdiv2, existingdiv1 ] );
</code></pre>
</code></pre>
<p>Since <code>.after()</code> can accept any number of additional arguments, the same result can be achieved by passing in the three <code>&lt;div&gt;</code>s as three separate arguments, like so: <code>$( "p" ).first().after( $newdiv1, newdiv2, existingdiv1 )</code>. The type and number of arguments will largely depend on the elements that are collected in the code.</p>
</longdesc>
<example>
Expand All @@ -99,9 +106,9 @@ $( "p" ).after( "<b>Hello</b>" );
]]></code>
<css><![CDATA[
p {
background: yellow;
background: yellow;
}
]]></css>
]]></css>
<html><![CDATA[
<p>I would like to say: </p>
]]></html>
Expand All @@ -112,10 +119,10 @@ $( "p" ).after( "<b>Hello</b>" );
$( "p" ).after( document.createTextNode( "Hello" ) );
]]></code>
<css><![CDATA[
p {
background: yellow;
p {
background: yellow;
}
]]></css>
]]></css>
<html><![CDATA[
<p>I would like to say: </p>
]]></html>
Expand All @@ -127,11 +134,12 @@ $( "p" ).after( $( "b" ) );
]]></code>
<css><![CDATA[
p {
background: yellow;
background: yellow;
}
]]></css>
]]></css>
<html><![CDATA[
<b>Hello</b><p>I would like to say: </p>
<b>Hello</b>
<p>I would like to say: </p>
]]></html>
</example>
<category slug="manipulation/dom-insertion-outside"/>
Expand Down
32 changes: 20 additions & 12 deletions entries/ajaxComplete.xml
View file
Expand Up @@ -11,36 +11,44 @@
<longdesc>
<p>Whenever an Ajax request completes, jQuery triggers the <code>ajaxComplete</code> event. Any and all handlers that have been registered with the <code>.ajaxComplete()</code> method are executed at this time.</p>
<p>To observe this method in action, set up a basic Ajax load request:</p>
<pre><code>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
<pre><code>
&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
&lt;div class="result"&gt;&lt;/div&gt;
&lt;div class="log"&gt;&lt;/div&gt;
</code></pre>
</code></pre>
<p>Attach the event handler to the document:</p>
<pre><code>$(document).ajaxComplete(function() {
<pre><code>
$( document ).ajaxComplete(function() {
$( ".log" ).text( "Triggered ajaxComplete handler." );
});
</code></pre>
</code></pre>
<p>Now, make an Ajax request using any jQuery method:</p>
<pre><code>$( ".trigger" ).click(function() {
<pre><code>
$( ".trigger" ).click(function() {
$( ".result" ).load( "ajax/test.html" );
});</code></pre>
});
</code></pre>
<p>When the user clicks the element with class <code>trigger</code> and the Ajax request completes, the log message is displayed.</p>
<p><strong>As of jQuery 1.8, the <code>.ajaxComplete()</code> method should only be attached to <code>document</code>.</strong></p>
<p>All <code>ajaxComplete</code> handlers are invoked, regardless of what Ajax request was completed. If you must differentiate between the requests, use the parameters passed to the handler. Each time an <code>ajaxComplete</code> handler is executed, it is passed the event object, the <code>XMLHttpRequest</code> object, and the settings object that was used in the creation of the request. For example, you can restrict the callback to only handling events dealing with a particular URL:</p>
<pre><code>$(document).ajaxComplete(function(event, xhr, settings) {
<pre><code>
$( document ).ajaxComplete(function( event, xhr, settings ) {
if ( settings.url === "ajax/test.html" ) {
$( ".log" ).text( "Triggered ajaxComplete handler. The result is " +
xhr.responseHTML );
xhr.responseHTML );
}
});</code></pre>
});
</code></pre>
<p><strong>Note:</strong> You can get the returned ajax contents by looking at <code>xhr.responseXML</code> or <code>xhr.responseHTML</code> for xml and html respectively.</p>
</longdesc>
<note id="ajax-global-false" type="additional" data-title=".ajaxComplete()"/>
<example>
<desc>Show a message when an Ajax request completes.</desc>
<code><![CDATA[$(document).ajaxComplete(function(event,request, settings) {
$( "#msg" ).append( "<li>Request Complete.</li>" );
});]]></code>
<code><![CDATA[
$( document ).ajaxComplete(function( event,request, settings ) {
$( "#msg" ).append( "<li>Request Complete.</li>" );
});
]]></code>
</example>
<category slug="ajax/global-ajax-event-handlers"/>
<category slug="version/1.0"/>
Expand Down

0 comments on commit ad18d21

Please sign in to comment.