Document how to use scrollTop() properly

[jzaefferer]

Via discussion in #14515.

This should be added to scrollTop():

Note that scrollTop can be used to read, but not write, the document scroll position. To scroll the document, animated or not, you have to call `scrollTop()` on the body element:

<pre><code>
// Without animation
$( document.body ).scrollTop( 500 );

// With animation
$( document.body ).animate({
  scrollTop: 500
});
</code></pre>

Any examples elsewhere that suggest $( "html, body" ).animate({ scrollTop: ... }); are wrong, since this will cause the animation callback to get triggered twice.

[jzaefferer]

I just reopened the Core ticket, see there for details: http://bugs.jquery.com/ticket/14515#comment:8

[gnarf]

I left some comments in #425 about the message here, I think we need to re-word it a bit and also add a similar note to scrollLeft()

[kswedberg]

@jzaefferer I left a comment on the Core ticket for you.

[jzaefferer]

Since Core won't try to normalize this, all we can do is document the canonical solution. Afaik this snippet works consistently and produces a single callback:

$( "html, body" ).animate({
  // scroll to end of page
  scrollTop: $(document).height()
}, 800).promise().then(function() {
  console.log("runs once!")
});

@leobalter would you update your branch and create a new PR? Thanks.

[gnarf]

That snippet has other side effects...

Namely:

$( "html, body" ).animate({
  // scroll to end of page
  scrollTop: $(document).height()
}, 800).promise().then(function() {
  console.log("runs once!")
}).animate({
  scrollTop: 0
}, 800); // but only after this animation ALSO finishes

$("body").animate({opacity: 0}, 500); // oh this one too

The promise on a jQuery object only gets called when its default animation queue empties, not as an inline callback to animation completion.

[jaubourg]

As gnarf said, you probably want something akin to this:

$.Deferred(function( defer ) {
    $( "html, body" ).animate({
        // scroll to end of page
        scrollTop: $(document).height()
    }, 800, defer.resolve );
}).done(function() {
    console.log( "runs once!" )
});

[leobalter]

IMHO, some of these examples are looking way complex to be presented as examples.

I think we can use the suggestions made by @gnarf to mention scrollLeft and we can also add another example using $.Deferred as mentioned by @jaubourg.

It might be worth to mention that jQuery Core don't try to force a normalization on this and explain why it's needed to handle scrollTop both on html and body to get a crossbrowser solution.

[jzaefferer]

We can start with an example that doesn't have the callback, to keep things simple at first. Use that to talk about the underlying issue and lack of normalization. Then talk about the issue with animation callbacks and how to deal with that, along with another example.

[dmethvin]

Can this be an article on learn perhaps, with a link from the api docs? It's starting to sound pretty big.

[kswedberg]

👍 to linking to a learn article.

[leobalter]

I'll try to write something by the weekend.

Anyway, I don't want to prevent anyone else to write it as well. If we have other article to be posted on learn I can push mine to a blog, maybe.