Geoff Chappell - Software Analyst
This website is constructed around the premise that although each page may know of other pages, and naturally will link to other pages, it need know only of itself and it doesn’t depend on which other pages link to it. The place of a page within the site is not a property of that page but of the site. The navigational support provided at this site is therefore external to all the document pages. Being one of those computer users who finds a directory tree entirely natural for depicting the storage of files, I have chosen to present the navigational support as a table of contents (TOC) that looks very much like a directory tree from a file system.
As it happens, there are several TOCs. The site has several subwebs, which are very nearly disjoint, in the sense that few pages in one subweb link naturally to any pages in any other subweb. Add that some of these subwebs run to several hundred pages (already) and it makes sense, if only to me, that each subweb should have its own TOC.
The basic design is that the document pages know nothing of any TOC, except by including scripts and stylesheets that are common to all document pages. Not only does this mean that I can reorganise the TOC without having to edit any document files, let alone to break any links, it also means that you can be sure of not missing any of a page’s text for want of running the scripts that are meant to show the TOC with the page.
If scripts on a document page do run as expected, the page is rebuilt into a viewer. There is an alternate user interface for when those scripts do not run, but I think the viewer is much better, not least for being interactive. The viewer has a banner across the top and a table of contents at the left. What remains is for the document page.
You select a subweb by clicking on a tab at the bottom of the blue banner, immediately adjoining a horizontal grey divider. The current subweb, i.e., the one that contains the currently loaded document, is highlighted in that same grey.
Most entries in the TOC are links to document pages. Clicking on the link in the left pane loads the corresponding document into the right pane. If the document is in a different subweb, clicking will also replace the TOC in the left pane.
The TOC is organised as a multi-level list which you can expand and collapse according to what interests you while you browse the site. Note that multiple branches can be open simultaneously, so that you may move easily between pages without my having planned any particular connection between those pages. (I am astonished at how many web-based TOCs permit only one branch to be expanded at a time.)
To expand a collapsed folder or collapse an expanded one, simply click on the icon immediately to the folder’s left. When you first expand a folder, it opens only one level deeper into the tree. If you collapse a folder, any expansions that you had made deeper into the tree are restored if you re-expand that folder.
To expand a folder and all its subfolders, even if any are already expanded, hold down the Ctrl key for the click. To collapse a folder and all its subfolders, hold down both the Ctrl and Shift keys while clicking. Collapsing a collapsed folder has no immediate visual effect, but is useful as a reset: it clears any expansions that had been made deeper into the tree. A re-expansion will then open only one level, as if the folder had never yet been expanded.
The TOC item that represents the currently loaded document page is always highlighted. There should never be any occasion to want to resynchronise the document page with the table of contents. If there is, and it isn’t resolved by refreshing the page, it is a bug. Please try to identify steps for reproduction, and then write to me about it. (Or just wait a few days, since sometimes it happens that I upload a new document but forget the new TOC that knows of this document.)
If you click on a link in a document page and this link takes you to another page at this site, then the target page becomes the current link in the TOC and its subweb is highlighted in the banner. If the source and target are in the same subweb, then whatever expanding and collapsing you have done in that subweb’s TOC is preserved. If the source and target are in different subwebs, then the state of the source subweb’s TOC is lost.
When the TOC has the focus, the usual Internet Explorer keyboard shortcuts of Tab and Shift-Tab work to move the focus down the table and back up (respectively), from one link to another, but only among those links that you have exposed by your expanding and collapsing of folders.
Sadly, most of the long-established keyboard shortcuts for moving around multi-panel Windows programs have fallen into disuse: yes, even as software manufacturers and commentators on user-interface design talk more and more about the importance of keyboard interfaces. Getting the focus to the TOC can be quite a bother!
Even Tab and Shift-Tab do not have universal support. Even more than a decade ago, I noted here that some other browsers treat Tab and Shift-Tab much as does Internet Explorer, but some, namely Opera and Safari, seem not to. I know of nothing I can sensibly do about this.
To expand or collapse a folder with the keyboard, get the focus to that folder and then press one of the following keys from the numeric keypad:
|+ (plus)||expand the folder|
|- (minus)||collapse the folder|
|* (multiply)||expand the folder and all its subfolders|
|/ (divide)||collapse the folder and all its subfolders|
These key assignments may be familiar, with slight variation, as those of the folder tree in the Windows Explorer and more generally of the tree-view control. A difference from tree views in such programs as the Windows Explorer is that arrow keys do not act either to move the focus or to expand or collapse folders: Internet Explorer has the arrow keys act on the scrollbars instead and I have chosen to work with that rather than to change it.
The minus and divide keys also act on list items that are not folders. They then collapse the enclosing folder, without your having had to move the focus to it.
These keyboard shortcuts also work in most browsers. I do not plan to modify this interface to suit other browsers. I may do something for the ever more frequently encountered keyboards that do not have a numeric keypad.
The user interface for resizing the TOC is in flux. When the viewer was a FRAMESET, the browser provided natively for resizing the divider between the TOC and document panels. WIth the change in 2021 to a set of DIV and IFRAME elements, similar resizing can be obtained from new browsers but otherwise requires support from scripts.
If only for now, the scripts provide for just two interactions with the divider. First, the divider can simply be dragged to wherever you want it. The scripts will carry your choice from page to page. This is of course just the minimum necessary functionality. It is well settled.
The other interactivity is that you can click on the divider or, presumably, tap on it. This developed from thinking ahead to what might be done for readers who try browsing the site with mobile phones or (more plausibly) tablets but anyway with narrow viewports. It is now settled that clicking on the divider will send it to the far left, thus hiding the TOC and maximising the space available for the document. Clicking the divider when it is at the far left will restore it to wherever it had been, thus retrieving the TOC for navigation.
If the viewport is narrow enough the TOC is initially hidden whenever a document loads. The only hint of its existence is the grey border at the left. It perhaps does not stand out as interactive. Yet at 8 pixels, it is hardly insubstantial: for some mobile phones, it’s more than 2% of the screen width! Hovering over it will reveal a tool tip. Clicking on it will “restore” the TOC to the full width. The divider then shows as the same grey border but on the right. Click on it to hide the TOC again and see the document. Click on a link while the TOC is spread across your screen, and when the new page loads, the TOC will automatically be hidden again. I don’t expect to improve on this any time soon, if ever.