## Framesets are simple, useful, familiar ## Javadoc relies on HTML's <frameset> for it's "FRAMES" view of doc sets. This feature adds some convenient navigation whilst Javadoc's HTML output remains as-simple-as-possible. It is familiar and useful and you wouldn't abandon it unless an alternative was unquestionably better and just as simple.
## Framesets don't really fit on the web ## There is however, a weakness of <frameset> based sites - the URL in the address bar doesn't match the primary content being viewed. As a consequence: - navigating a hyperlink or via back and forwards button doesn't update the URL in the address bar, which is unexpected behavior (although not to those familiar with javadoc) - search engines will link to the primary content page, so users will arrive at the NOFRAMES view and need to manually choose the FRAMES view. - users can't bookmark pages or email the URL when in the FRAMES view ## With AJAX and pushState, framesets can be emulated / surpassed ## Fortunately, all up-to-date browsers have the `history.pushState()` API call which allows javascript to update the URL in address bar without reloading the page. This - together with the long-supported XMLHttpRequest - should allow a Javascript-driven **emulation** of framesets that also keeps the URL in the address bar valid. (Naturally it is not necessary to strictly emulate the current UI if something better is possible, e.g. a dynamic search box.) ## A frameset replacement must be (mostly) decoupled from Javadoc ## For this approach to be a viable replacement for framesets it must be possible to implement it with minimal change to javadoc's HTML output. Ideally this change would be a single <script src="boot.js"> in every page to bootstrap the enhanced UI. If this can be achieved then the UI can be updated independently of javadoc being run. This would make UI customization / rebranding / fixes / enhancement quicker and simpler. ## An implementation ## The good news is that this approach already has an implementation. The javadoc-panner project brings pushState-assisted-navigation and a customizable UI to documentation-sets generated by Javadoc-1.7. There is a public project page at https://github.com/meekostuff/javadoc-panner ### Proof of concept These enhancements **are** achieved with a single bootstrap script. Currently this is the most important feature of javadoc-panner. ### Demonstrations The generic method of applying javadoc-panner to a doc-set is with a javascript bookmarklet. This can be most easily installed from http://devel.meekostuff.net/javadoc-panner/0.1-devel/ There is also an introduction video with a few thoughts, a walk-through on how to install the bookmarklet, and a short demo of it running on a few sites. See http://youtu.be/LC45G7zsCFs ### The UI can be easily updated When you try out javadoc-panner or watch the demo, the most important thing to remember is that *you don't have to like the UI* because **it can be updated independently**. Another important thing to note is that the UI is implemented as a standalone HTML document - another feature that should make UI evolution quicker and simpler. ### Easily integrated It is also possible (though undocumented) to integrate javadoc-panner into an already generated doc-set. You can see this in action at http://playground.meekostuff.net/javadoc/jdk8/docs/jdk/api/jpda/jdi/overview-summary.html This doc-set is copied from the one at http://download.java.net/jdk8/docs/jdk/api/jpda/jdi/overview-summary.html The only difference between the HTML source files and the files in this doc-set is that each file is prepended with the lines: <!DOCTYPE html> <script src="/javadoc/boot.js"></script> ## Feedback required ## It would be great to have feedback. Any questions or comments on the approach outlined here are welcome. If there are other news groups where it would be appropriate to discuss this then please notify me. Issues / bugs / feature-requests for the javadoc-panner project are best directed to the project issues page https://github.com/meekostuff/javadoc-panner/issues regards, Sean Hogan
