$.ready documentation #205

Open
PikadudeNo1 opened this Issue Jan 7, 2013 · 19 comments

Projects

None yet
@PikadudeNo1

Ticket #11470 brought a ready promise to jQuery 1.8, but it's not in the API docs yet.

@dmethvin
jQuery Foundation member

I want to introduce the ability to exclude both $.Deferred and $.Callbacks in 1.11 so let's wait until that's finalized before documenting this.

@dmethvin
jQuery Foundation member

Still not convinced this should be documented in situ since it's rather awkwardly placed. We need to determine how Promises will be handled in general for 1.12.

@he7d3r

Any news on this?

@timmywil
jQuery Foundation member

Rather than introducing the ability to exclude $.Deferred, we've introduced the ability to exclude .ready(). I think it's safe to document that is supports the jQuery Promise API.

@Krinkle
jQuery Foundation member

I'm not sure I see how Promise/Deferred possibly being excludable affects our decision about documenting this as a public API?

ajax can be excluded from the build as well, yet jQuery.ajax is a public API we support and document. Whether we want to support jQuery.read.promise() should be a fairly simple question (regardless of it being in module core, ready, deferred, or otherwise).

We also have $().promise in our API, and $().ready.

@timmywil
jQuery Foundation member

I'm not sure I see how Promise/Deferred possibly be excluded affects our decision about including this in the public API?

I see the argument. Documenting it implies a guarantee that Deferred will be present when using .ready(). Dave is thinking about future APIs as well as the current one. However, 1.11 has been finalized so I think we're good to document this.

@Krinkle Krinkle added a commit that referenced this issue Jul 15, 2014
@Krinkle Krinkle Document jQuery.ready.promise()
Also:
* Categorise jQuery.holdReady in events/document-loading,
  to match ready() and jQuery.ready.promise().
* Categorise jQuery.holdReady in properties/global-jquery-object-properties,
  to match jQuery.fx.off() and jQuery.ready.promise().

Fixes #205
98dadbf
@Krinkle Krinkle added a commit that referenced this issue Jul 15, 2014
@Krinkle Krinkle Document jQuery.ready.promise()
Also:
* Categorise jQuery.holdReady in events/document-loading,
  to match ready() and jQuery.ready.promise().
* Categorise jQuery.holdReady in properties/global-jquery-object-properties,
  to match jQuery.fx.off() and jQuery.ready.promise().

Fixes #205
ec9e1db
@arthurvr
jQuery Foundation member

PR #530.

@dmethvin
jQuery Foundation member

I still don't think we should document jQuery.ready.promise() because that implies jQuery.ready is a jQuery.Deferred-like object with a .promise() method. Instead, I'd like to document that jQuery.ready is accepted as a deferred/promise in APIs such as jQuery.when(). The distinction is subtle perhaps, but means that someone could exclude jQuery.Deferred but put in their own jQuery.ready implementation based on, for example, a native Promise, but still maintain decent interoperability. Does that seem sane?

@gibson042
jQuery Foundation member

I agree with that approach. The method is essentially an internal implementation detail for enabling things like jQuery.when( jQuery.ready ) or (hopefully) Promise.resolve( jQuery.ready ).

@dmethvin
jQuery Foundation member

The blueprint for exposing the ready promise is set in this comment by @gibson042. Basically, we're not documenting it to be a jQuery.Deferred but instead a thenable that is generally compatible with other promise mechanisms including jQuery.when and the standard Promise.resolve. I've updated the title of this issue to reflect that.

@dmethvin dmethvin changed the title from $.ready.promise() needs documentation to $.ready documentation May 13, 2015
@dmethvin
jQuery Foundation member

Also note that this approach is back-compatible so we can document it for existing versions and not just 3.0.

@benjamingr

Yeah, the point of the other (dupe) issue is that it's back compatible, you're likely not going to break 1.x or 2.x anyway and it'd be beneficial to document it since people are already using it when using promises anyway (passing it to Promise.all is pretty common when you want to wait for the page to load and to make an AJAX request for data).

Thanks for considering. I'd love to use this.

@benjamingr

ping.

@mnpenner

So....does jQuery have a Promise for when the document is ready or not?

@dmethvin
jQuery Foundation member

Yes it does. Think of it as a thenable though and to not make other assumptions about it.

https://github.com/jquery/jquery.com/blob/master/pages/upgrade-guide/3.0.md#feature-jqueryready-promise-is-formally-supported

@AurelioDeRosa
jQuery Foundation member

Should this be referred as what we'll call jQuery-Promise?

@dmethvin
jQuery Foundation member

No, this is actually just a thenable so we provide even fewer guarantees about what it is. It is acceptable to use jQuery.ready as input to jQuery.when) but not to do something like jQuery.ready.done(fn) because we don't guarantee that it will have a .done() method like a jQuery.Deferred would have. That's the gist of the upgrade guide explanation too.

Perhaps we could create a Thenable type since it would be used to define this property and also for the input type of jQuery.when()? Seems like another good thing for @gibson042 input.

@gibson042
jQuery Foundation member

Perhaps we could create a Thenable type since it would be used to define this property and also for the input type of jQuery.when()?

I like that. In practice, it is a base of both ES6 Promise and jQuery Promise, the latter of which is itself a base of jQuery Deferred.

@dmethvin
jQuery Foundation member

See also #906 and #530, there's some duplication among them.

@dmethvin dmethvin referenced this issue Aug 11, 2016
Open

3.0 Deprecations and removals #970

9 of 21 tasks complete
@Krinkle Krinkle added a commit to Krinkle/api.jquery.com that referenced this issue Sep 20, 2016
@Krinkle Krinkle Document jQuery.ready
Also:
* Categorise jQuery.holdReady in events/document-loading,
  to match ready() and jQuery.ready.promise().
* Categorise jQuery.holdReady in properties/global-jquery-object-properties,
  to match jQuery.fx.off() and jQuery.ready.promise().

Fixes #205
141c8fe
@Krinkle Krinkle added a commit to Krinkle/api.jquery.com that referenced this issue Sep 20, 2016
@Krinkle Krinkle Document jQuery.ready
Also:
* Categorise jQuery.holdReady in events/document-loading,
  to match ready() and jQuery.ready.promise().
* Categorise jQuery.holdReady in properties/global-jquery-object-properties,
  to match jQuery.fx.off() and jQuery.ready.promise().

Fixes #205
2b41797
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment