intra-page jumps do not always work properly

[kcoleman-marklogic]

The intra-page jumps are computed in JS, IIRC, and sometimes they do not work. When they're just off by a few lines, it is only mildly annoying/confusing. However, sometimes, they just don't work at all. For example, if you go to the following page:

http://docs.marklogic.com/guide/search-dev/query-options

And then use the browser's search feature to find "Search Term Completion" on that page, you'll come to a link to another topic by that name. The link goes to this URL

http://docs.marklogic.com/guide/search-dev/search-api#id_39268

However, if you click on it (from the doc app, not here in this issue), the app will navigate to that URL, but position you within the page to this topic instead of the desired one on Search Term Completion.

http://docs.marklogic.com/guide/search-dev/search-api#id_32545

If you reload the page, you will get to the correct topic.

My perception is that some positional information from the previous page (the query-options page) is carrying over when it computes the jump for the id_39268 anchor, so it gets it quite, quite, wrong. However, that is pure speculation as I have only very superficial knowledge of how this works.

This issue filed on behalf of internal bug 41354 by @sammefford.

[dmcassel]

Additional example from @jmckean17:

When I click on a link from the left nav bar, or from within a document, the actual text seems to roll up under the top panel.

For instance, from this page - /9.0/guide/security/element#id_81692, I click the REST Management link - /9.0/REST/GET/manage/v2/security/properties and the top half of the API signature is hidden.

Also if I click REST Management APIs in the left nav bar to go back, the page seems to be stuck on the API and/or takes me to another place in the chapter.

[kcoleman-marklogic]

@jmckean17 noticed the jumps are "working" particularly badly for the glossary, for some reason. A random sampling of links into the glossary consistently delivers me to the top of the glossary page instead of to the desired term.

Unfortunately, reloading the page does not correct the positioning problem for the glossary. The only thing that works is pasting the URL to the desired term into a new browser window/tab, which is horribly lame. At least, that's my experience in Chrome.

There are several examples that demonstrate this in the intro chapter of the Semantics guide (http://docs.marklogic.com/guide/semantics/intro), such as the terms near the end of the first paragraph.

[dmcassel]

I've started looking into this. No real progress yet. Good to know about the glossary.

[kcoleman-marklogic]

I am reminded this morning (by nerd rage) that I should have asked you yesterday if it would be OK to put this in the April milestone. At least an investigation of it.

IDK if it some change to JS or to Chrome, but I find the jumps are wrong more often than not these days. The fact that reloading the page frequently doesn't "fix" it any longer also raises the urgency.

I'm going to add the milestone, and you can change it as you see fit. I'm OK with whatever you decide.

[dmcassel]

I've been seeing this more often, too, so yes, good one to add.

[sammefford]

This issue seems to me to need a high priority. It significantly hampers my ability to use our docs. I can only imagine it is impacting our customer experience.

[kcoleman-marklogic]

Just updating this bug with my perception of when it happens besides just a vague "a lot":

My encounter with intrapage jumps a few years ago is that it is handled by some javascript that attempts to compute how far down to scroll to reach an anchor. Part of that computation includes a "where am i now" value, IIRC.

I see this bad jumping when I click on a link after scrolling down in the origin page. That is, I am not at the top of the page. My speculation is that the position in the origin page is being remembered across the jump and used as a starting place for the computation on the target page, with the result that it scrolls too far.

[kcoleman-marklogic]

FWIW, Mukul, I think the code around here is implicated in the problem:

https://github.com/marklogic-community/RunDMC/blob/master/src/apidoc/js/jquery.pjax.js#L328

I could be completely wrong about that, though, since I don't really understand most of what's going on in there, but it might give you a starting place.

[MukulAmbulgekar]

Thanks for the pointer Kim.

It seems, the main issue here is whenever there is reference from one page to section on the another page, it jumps to the wrong position. Please note that by saying section here, I mean url containing hash value e.g. /guide/search-dev/search-api#id_39268 . I noticed this happens for all cases.

Like in the example given, you are on /guide/search-dev/query-options page and clicking on "Search Term Completion" you should navigate to /guide/search-dev/search-api#id_39268 which is a different page (what I mean is, a different url) but it jumps to the wrong position, on the other hand if you click to section on the same page e.g. search for "Value Constraint Example" on query-options page, it will land you to the the correct section.

This happens for TOC as well. For example, go to "Introduction to MarkLogic Server" page http://docs.marklogic.com/guide/getting-started/intro and then directly go to "Template Driven Extraction (TDE)" using TOC tree structure (Guides > Getting Started Guides > Release Notes > New Features in MarkLogic 9 > Template Driven Extraction (TDE) ) - it will not jump to TDE section.

To fix this, I added scroll to page content logic so that it should scroll down to the proper section referenced by url. Deployed it to the staging app - http://engrlab-129-137:8011/guide/search-dev/query-options

[kcoleman-marklogic]

That looks great, Mukul. I did a bunch of skipping around and did not observe any bad behavior. I think we should deploy this to pubs for a few days (when you're ready) so that we have more eyes and hands on it. Even if we find edge cases where the behavior isn't right, I would still deploy it because it is a HUGE QoL improvement.

Is the fix in code that is specific to the documentation, so that it won't have any impact on the developer site? (say, under RunDMC/src/apidoc)

[MukulAmbulgekar]

Yes, it is- RunDMC/src/apidoc/js/toc_filter.js

[kcoleman-marklogic]

This is now live.

[dmcassel]

"And there was great rejoicing!"