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]

:+1: 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.

[arthurvr]

I'll try to write something by the weekend.

@leobalter Still interested in taking this? Or did you already do?

[leobalter]

I failed doing this. I may try it again but it shouldn't hold anyone else to fix it.

On Feb 8, 2015, at 11:23 AM, Arthur Verschaeve [email protected] wrote:

I'll try to write something by the weekend.

@leobalter Still interested in taking this? Or did you already do?

— Reply to this email directly or view it on GitHub.

[jzaefferer]

@arthurvr interested in taking this over? Or finding someone to write the docs? Sad to see this still open more than a year later...

[arthurvr]

interested in taking this over? Or finding someone to write the docs? Sad to see this still open more than a year later...

That's true for basically ever ticket open here :( One day I'll get to it for sure, but time just limits me.

[arthurvr]

@jzaefferer Although I do definitely agree that many things in this repo are taking way too long. There are still APIs from back in 2012 undocumented, just because we lack the time and the resources.

[dmethvin]

@arthurvr the important thing is that we are making progress, thanks to you! This issue in particular seemed to get lots of people suggesting changes without a clear consensus on what to do. I think that's why it sat around so long, it is tedious to sort through these kinds of tickets and there is always concern you'll upset someone by ignoring their concerns. So go for the low-hanging fruit if it's easier.

[jzaefferer]

Here's a good explanation of the underlying mess, along with a future-proof solution called document.scrollingElement: https://dev.opera.com/articles/fixing-the-scrolltop-bug/

If I read that correctly, we should document how to animate document.scrollingElement, along with a recommendation to load the polyfill.