add deferreds content #156

Merged
merged 1 commit into from Dec 14, 2012

3 participants

@johnkpaul

No description provided.

@johnkpaul

This fixes issue #3

@ajpiano ajpiano commented on an outdated diff Oct 19, 2012
page/code-organization/deferreds.md
@@ -0,0 +1,676 @@
+---
+title: Deferreds
+level: advanced
+source: http://msdn.microsoft.com/en-us/magazine/gg723713.aspx
+attribution:
+ - Julian Aubourg <j@ubourg.net>
+ - Andree Hansson <peolanha@gmail.com>
@ajpiano
jQuery Foundation member
ajpiano added a line comment Oct 19, 2012

should add @addyosmani here, he and @jaubourg did the original content, @peolanha helped with converting it to markdown!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ajpiano ajpiano and 1 other commented on an outdated diff Oct 19, 2012
page/code-organization/deferreds.md
+attribution:
+ - Julian Aubourg <j@ubourg.net>
+ - Andree Hansson <peolanha@gmail.com>
+---
+
+At a high-level, deferreds can be thought of as a way to represent
+costly operations which can take a long time to complete. They&apos;re the
+asynchronous alternative to blocking functions and the general idea is
+that rather than your application blocking while it awaits some request
+to complete before returning a result, a deferred object can instead be
+returned immediately. You can then attach callbacks to the deferred
+object: they will be called once the request has actually completed.
+
+##Promises
+
+In its most basic form, a &apos;promise&apos; is a model that provides a solution
@ajpiano
jQuery Foundation member
ajpiano added a line comment Oct 19, 2012

why is there &apos here twice?

@rmurphey
rmurphey added a line comment Nov 25, 2012

I think just use normal punctuation here and it will get made pretty by the markdown converter as appropriate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ajpiano ajpiano commented on an outdated diff Oct 19, 2012
page/code-organization/deferreds.md
+
+```
+when(
+ promise1,
+ promise2,
+ ...
+).then(function( futureValue1, futureValue2, ... ) {
+ /* all promises have completed and are resolved */
+});
+```
+
+A good example is a scenario where you may have multiple concurrent
+animations that are being run. Without keeping track of each callback
+firing on completion, it can be difficult to truly establish once all
+your animations have finished running. Using promises and 'when' however
+this is very straight-forward as each of your animations can effectively
@ajpiano
jQuery Foundation member
ajpiano added a line comment Oct 19, 2012

straightforward is one word

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ajpiano ajpiano commented on an outdated diff Oct 19, 2012
page/code-organization/deferreds.md
+This means that one can basically write non-blocking logic that can be
+executed without synchronization. Rather than directly passing callbacks
+to functions, something which can lead to tightly coupled interfaces,
+using promises allows one to separate concerns for code that is
+synchronous or asynchronous.
+
+##jQuery Deferreds
+
+jQuery's implementation of deferreds, first introduced in jQuery 1.5,
+offers a solution which doesn't hugely differ from the section above
+describing the high-level concept of promises - in principle, you are
+given the ability to 'defer' the return of a result to some point in the
+future, which wasn't previously possible using the library alone.
+
+Deferreds were added as a part of a large rewrite of the ajax module,
+led by Julian following the CommonJS Promises/A design. Whilst 1.5 and
@ajpiano
jQuery Foundation member
ajpiano added a line comment Oct 19, 2012

add "Aubourg"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ajpiano ajpiano commented on an outdated diff Oct 19, 2012
page/code-organization/deferreds.md
+ element.attr( "src", src );
+ }, function() {
+ element.attr( "src", "error.png" );
+ } ).done(function() {
+ element.fadeIn();
+ });
+ } );
+ }
+});
+```
+
+Here, we first wait for the delay to be fulfilled before attempting to
+load the image. It can make a lot of sense when you want to limit the
+number or network requests on page load.
+
+##Conclusions
@ajpiano
jQuery Foundation member
ajpiano added a line comment Oct 19, 2012

I don't think we need this entire paragraph at all.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ajpiano ajpiano commented on an outdated diff Oct 19, 2012
page/code-organization/deferreds.md
+ promise2
+).then(function(){
+ /* once both animations have completed
+ we can then run our additional logic */
+});
+```
+
+This means that one can basically write non-blocking logic that can be
+executed without synchronization. Rather than directly passing callbacks
+to functions, something which can lead to tightly coupled interfaces,
+using promises allows one to separate concerns for code that is
+synchronous or asynchronous.
+
+##jQuery Deferreds
+
+jQuery's implementation of deferreds, first introduced in jQuery 1.5,
@ajpiano
jQuery Foundation member
ajpiano added a line comment Oct 19, 2012

Change this to from "jQuery's implementation of deferreds, ... , offers" to "jQuery's deferreds, ... , offer"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ajpiano
jQuery Foundation member

All the &apos; need to be fixed

In general, I can't help the feeling this should be broken into smaller bits - at the very least, separating out the "further examples" section into its own article. Thoughts?

@bobholt bobholt commented on an outdated diff Oct 20, 2012
page/code-organization/deferreds.md
+ /* all promises have completed and are resolved */
+});
+```
+
+A good example is a scenario where you may have multiple concurrent
+animations that are being run. Without keeping track of each callback
+firing on completion, it can be difficult to truly establish once all
+your animations have finished running. Using promises and 'when' however
+this is very straight-forward as each of your animations can effectively
+say &apos;we promise to let you know once we're done&apos;. The compounded result
+of this means it's a trivial process to execute a single callback once
+the animations are done. For example:
+
+```
+var promise1 = $('#id1').animate().promise();
+var promise2 = $('#id2').animate().promise();
@bobholt
jQuery Foundation member
bobholt added a line comment Oct 20, 2012

double quotes here, please.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@johnkpaul

@ajpiano I agree on separating this out into multiple articles, There is a lot more than should be in the single article about deferreds. I will look into this and the other notes this weekend.

@rmurphey rmurphey commented on an outdated diff Nov 25, 2012
page/code-organization/deferreds.md
@@ -0,0 +1,676 @@
+---
+title: Deferreds
+level: advanced
+source: http://msdn.microsoft.com/en-us/magazine/gg723713.aspx
+attribution:
+ - Julian Aubourg <j@ubourg.net>
+ - Andree Hansson <peolanha@gmail.com>
+---
+
+At a high-level, deferreds can be thought of as a way to represent
+costly operations which can take a long time to complete. They&apos;re the
@rmurphey
rmurphey added a line comment Nov 25, 2012

I wouldn't necessarily agree about the "costly" part -- it's really just about async operations generally, which aren't necessarily costly, just non-blocking .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@rmurphey rmurphey commented on an outdated diff Nov 25, 2012
page/code-organization/deferreds.md
+ - Andree Hansson <peolanha@gmail.com>
+---
+
+At a high-level, deferreds can be thought of as a way to represent
+costly operations which can take a long time to complete. They&apos;re the
+asynchronous alternative to blocking functions and the general idea is
+that rather than your application blocking while it awaits some request
+to complete before returning a result, a deferred object can instead be
+returned immediately. You can then attach callbacks to the deferred
+object: they will be called once the request has actually completed.
+
+##Promises
+
+In its most basic form, a &apos;promise&apos; is a model that provides a solution
+for the concept of deferred (or future) results in software engineering.
+The main idea behind it is something we&apos;ve already covered: rather than
@rmurphey
rmurphey added a line comment Nov 25, 2012

Two things:

  • avoid "we", per the style guide
  • since these articles may be consumed out of sequence, "already covered" isn't necessarily accurate -- better to link to another resource where the concept you're referring to is covered
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@johnkpaul

I've addressed all of the notes in this PR. I've rewritten the portions with 'we' and split this out into three separate articles.

@addyosmani
jQuery Foundation member

Nice work @johnkpaul :) The separation into three distinct pieces appears to have been done quite cleanly and this looks good for a merge to me.

@addyosmani addyosmani merged commit da12e4d into jquery:master Dec 14, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment