Javascript for info-style navigation - Week 9

by Mathieu Lirzin - 28 Jul 2017 12:41:57 GMT

This is an update on the work I am doing this summer for my Google Summer of Code. Please see the first article of this serie of reports for a general introduction on what this project is about.

Sidebar scrolling

In order to help users knowing where the current page is located inside the global manual, we provide a sidebar containing the table of content which highlights the current node. In the case of a huge manual that has a long table of content like the Kawa manual, It is possible to have a scollbar for the lateral iframe when accessing a deeply nested node. It is important that the current highlighted node stays visible when navigating with the keyboard. For that I have used the Element.scrollIntoView method in the sidebar browsing context which when applied on the highlighted link adapt the scrolling accordingly. This method is called when handling the update-sidebar message which is responsible for changing the currently displayed link.

on_message (event)
  var data =;
  if (data.message_kind === "update-sidebar")
      var selected = data.selected;
      /* ...Highlight the node corresponding to SELECTED.  */
      var elem = document.getElementById (selected);
      if (elem)
        elem.scrollIntoView (true);

if (inside_sidebar)
  window.addEventListener ("message", on_message, false);

While this is working nicely, before knowing this method, I have tried using Location.replace instead to change the hash part of the URL of the iframe. Using this method was definitely not the right approach since it messes with the focus of elements on Chromium.

Iframe reloads

Thanks to my mentor Per Bothner, we have noticed that the features added last week has the undesired effect of automatically reloading iframes every time, instead of loading it once and only switch their visibility the next times. This bug was the consequence of calling Location.replace with the empty string. The intending effect was to scroll to the top of the page and this can be acheived with window.scroll (0, 0).

Compatibility warning

When the browser used for reading the manual doesn't have the minimum requirements for making the Javascript UI work, we fallback to a basic HTML navigation. We want to notify the user that the script was unable to properly work in that browser, instead of silently fallback. For that I have added a simple warning message that popup and dissapear after 3 seconds.

Various improvements

Follow the developpement

I have updated the live demo of the Kawa manual which is available here. If you have already accessed this page, it is possible that you face invalid cache issues. Make sure that your local cache is cleared.

The development of this project is done in public. You can checkout the "js" directory in the "gsoc-2017" branch of the Git repository and run the build instructions from the README to see what is the current state of the project.